Project Modular Management (PM2)

> Zero-configuration project structure analyzer with 11-digit hierarchical encoding. Drop it into any project, run once, get a complete module map with change tracking.

Features

11-Digit Encoding Scheme

L PPP OOO FFFF
│ ─┬─  ─┬─  ─┬─
│  │    │    └── File index (0000 = directory or standalone file)
│  │    │         0001+ = file inside a directory (sub-index)
│  │    └────── Fixed separator "000"
│  └────────── Level sequential number (001-999), global per level
└──────────── Level letter (A = root depth 1, B = depth 2, C = depth 3, ...)

Encoding Rules

Example

yunheiku/
├── api/                     A0010000000
│   ├── .env                   B0010000000
│   ├── routes/                B0020000000
│   │   ├── query.js             C0010000000
│   │   └── submit.js            C0020000000
│   └── services/              B0030000000
│       └── token-cache.js       C0030000000
├── src/                      A0020000000
│   ├── App.tsx                 B0040000000
│   └── components/             B0050000000
│       └── Header.tsx            C0040000000
└── docs/                     A0030000000
    └── README.md               B0060000000

When to Use This Tool

Recommended Scenarios

Not Recommended For

Quick Start

# First run — auto-discovers module structure
python generate_module_map.py

# Subsequent runs — stable codes, detects changes
python generate_module_map.py

# Generate a Markdown report
python generate_module_map.py --format md -o modules.md

# JSON export
python generate_module_map.py --format json -o modules.json

# Force re-discovery (discard existing codes)
python generate_module_map.py --reset

# Run on a specific project
python generate_module_map.py /path/to/project

# Suppress progress messages
python generate_module_map.py --quiet

# Force run even if project exceeds recommended limits
python generate_module_map.py --force

Output Example

======================================================================
  React Project Module Map
  Project : D:\.workbuddy\yunheiku
  Generated: 2026-07-16 21:30:00 | Files: 962 | LoC: 251.8k
======================================================================

|-- [D] api                              A0010000000
|   |-- [F] .env                             B0010000000  110B
|   |-- [D] routes                           B0020000000
|   |   +-- [F] query.js                         C0010000000  6.8KB
|   +-- [D] services                         B0030000000
|       +-- [F] token-cache.js                   C0020000000  2.9KB
|-- [D] src                              A0020000000
|   |-- [F] App.tsx                          B0040000000  1.2KB
|   +-- [D] components                       B0050000000
|       +-- [F] Header.tsx                       C0030000000  892B
+-- [D] Documentation                    A0030000000
    |-- [F] README.md                        B0060000000  2.1KB
    +-- [F] SETUP.md                          B0070000000  3.5KB

======================================================================
  Change Log
======================================================================
  + Added [A0040000000] new-module/index.ts (1.2KB, 45 lines)
  - Removed [B0080000000] old-file.ts (tombstoned)
  ~ Modified [C0030000000] components/Header.tsx (892B -> 1.2KB)

  Total: 3 change(s)

  Data: .../yunheiku-modular/data/a43bf6a5

Configuration (.modularrc.json)

Place in your project root to customize behavior:

{
  "skip_dirs": ["generated", "fixtures"],
  "skip_files": ["*.gen.ts"]
}

Data Storage

All data is kept inside the skill directory, isolated per project (MD5 hash of project path):

skills/yunheiku-modular/
├── SKILL.md
├── generate_module_map.py
└── data/                          # Safe to delete — auto-rebuilds
    └── a43bf6a5/                  # One folder per project
        ├── tree-config.json       # Stable code assignments + tombstones
        ├── snapshot.json          # Full file metadata snapshot
        └── change-log.json        # Last 50 change entries

Why Append-Only + Tombstones?

• Stability: A file's code never changes once assigned, so external references (docs, tickets, PRs) stay valid
• Traceability: Tombstones show what was deleted and when
• No cascading renumbers: Adding a file never shifts codes of other files
• Git-friendly: Predictable, merge-conflict-free encoding

Error Codes

Warnings

Best Practices

Do's

1. New project onboarding: Run once to get a bird's-eye view of the architecture
2. Before coding: Check the module map to understand which files to touch
3. After coding: Run again to confirm the change scope matches expectations
4. Code review: Use the change log to understand what was modified and why
5. CI integration: Generate a Markdown report as a build artifact
6. Team alignment: Share .modularrc.json to ensure consistent module boundaries
7. When adding files: Just create them — PM2 auto-assigns the next available code on next run
8. When deleting files: Safe to delete — PM2 tombstones the old code, new files won't reuse it

Don'ts (Anti-Patterns)

1. Don't run on extremely large projects (>5000 files) — it will be slow and memory-intensive
2. Don't expect real-time updates — PM2 runs on-demand, not continuously
3. Don't modify the data directory manually — let PM2 manage it
4. Don't use for temporary directories — overhead not justified
5. Don't rely on module codes for runtime logic — codes are for reference only
6. Don't panic if you see warnings — warnings don't prevent analysis from completing

FAQ

Q: What does the error "Project exceeds recommended size limits" mean?

A: PM2 limits projects to 5000 files by default to ensure reasonable performance. If your project has more files, you can either:
- Use --force flag to override the limit
- Add more directories to .modularrc.json's skip_dirs to reduce scope
- Run PM2 on subdirectories separately

Q: Why do deleted files still show up in the codes?

A: PM2 uses a "tombstone" system — deleted files retain their codes but are marked as deleted. This ensures:
- References to those codes remain valid (e.g., in documentation or tickets)
- New files don't accidentally reuse old codes
- You can see what was deleted and when

Q: Can I integrate PM2 into my CI pipeline?

A: Yes! Add this to your CI workflow:

python generate_module_map.py --format md -o module-report.md

Then upload module-report.md as an artifact.

Q: How do I reset all codes and start fresh?

A: Run with --reset flag:

python generate_module_map.py --reset

This will discard all existing codes and re-discover the project from scratch.

Q: My project has no source files after filtering. What's wrong?

A: Check your .modularrc.json — you may have over-aggressive skip patterns. Also verify that your .gitignore isn't excluding too much.

Q: Can I use PM2 on network drives or read-only directories?

A: PM2 requires write access to its data/ directory for storing snapshots and configs. Read-only project directories should work as long as the data directory is writable.

Q: What happens if PM2 encounters a file it can't read?

A: PM2 will skip unreadable files with a warning and continue processing. The file will show "N/A" for size and line count in the output.

Q: How do I handle special characters in file paths?

A: PM2 will warn about files with special characters but will still process them. For best results, rename files to use only alphanumeric characters, underscores, and hyphens.

Q: Can I use PM2 with other tools?

A: Yes! PM2 can be integrated with:
- VS Code: Add a task to run PM2 on save
- Git hooks: Run on pre-commit to verify change scope
- Project management tools: Export JSON and parse in your workflow
- Documentation generators: Use Markdown output in your docs

Q: How often should I run PM2?

A: It depends on your workflow:
- Daily: For active development to track changes
- Before/after major changes: To document scope
- On demand: When you need to understand the current structure

Q: What if I move a file?

A: Moving a file is treated as deleting the old path and adding a new path. The old code becomes a tombstone, and the new location gets a new code. To preserve the code, you would need to manually update tree-config.json.

Tool Integration Examples

VS Code Task

Add this to .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Generate Module Map",
      "type": "shell",
      "command": "python generate_module_map.py --format md -o MODULE_MAP.md",
      "group": "build",
      "presentation": {
        "reveal": "always",
        "panel": "new"
      }
    }
  ]
}

Git Pre-Commit Hook

Create .git/hooks/pre-commit:

#!/bin/bash
python generate_module_map.py --format md -o MODULE_MAP.md
git add MODULE_MAP.md

GitHub Actions Workflow

Create .github/workflows/module-map.yml:

name: Generate Module Map
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: python generate_module_map.py --format md -o module-report.md
      - uses: actions/upload-artifact@v4
        with:
          name: module-report
          path: module-report.md

Limitations

• Performance: Best for projects under 5000 files and 15 directory levels deep
• Memory: Large projects may consume significant memory during analysis
• Real-time: PM2 runs on-demand; it doesn't monitor for file changes automatically
• Encoding: Files with non-UTF-8 encoding may not be processed correctly
• Permissions: Requires read access to project files and write access to data directory