Pi skill integration, CLI polish, --fix flag, config file support
- SKILL.md: Proper Agent Skills frontmatter with name/description - pi-extension.ts: Pi extension registering 4 custom tools (project_map_init/patch/validate/reinit) with prompt snippets/guidelines - pi-extension.ts: Auto-detects .pi-map.md files on session start, warns about dirty markers, injects maintenance hints before agent start - package.json: Added pi.extensions and pi.skills entries - CLI: Added picocolors, clean help screen, progress indicators, summary output with timing, colored check/warning icons - validate.ts: Added --fix flag that regenerates directories with discrepancies - config.ts: Reads .pi-project-map.json from project root with merge over defaults - init.ts: Added optional verbose parameter for programmatic use All 16 tests pass. TypeScript compiles clean. Build succeeds.
This commit is contained in:
@@ -1,24 +1,41 @@
|
||||
---
|
||||
name: pi-project-map
|
||||
description: Generates and maintains hierarchical, machine-readable project analysis files (.pi-map.md) for instant codebase comprehension. Use when working with medium-to-large codebases where understanding architecture, file relationships, and exports without reading every file is valuable. Automatically extracts symbols via AST and LLM heuristics.
|
||||
---
|
||||
|
||||
# pi-project-map
|
||||
|
||||
A Pi skill that generates and maintains a hierarchical, machine-readable analysis of a software project. Each directory gets a `.pi-map.md` file containing architectural context, exported symbols, and dependencies.
|
||||
|
||||
## Tools
|
||||
## What It Does
|
||||
|
||||
### `project-map:init [root]`
|
||||
Runs a full project scan and generates `.pi-map.md` files in every directory.
|
||||
- **Scans** your entire project and creates one `.pi-map.md` per directory
|
||||
- **Extracts** exports, imports, and dependencies via AST parsing (TypeScript, Python, Go) and LLM heuristics
|
||||
- **Updates** incrementally when files change (full rewrite for small packages, section-level patch for large)
|
||||
- **Validates** detects stale entries, missing files, orphaned entries, and changed signatures
|
||||
|
||||
### `project-map:patch <file-path>`
|
||||
Updates the `.pi-map.md` for the directory containing the given file. Uses full rewrite for small packages (< 10 files) or section-level patch for larger packages.
|
||||
## Quick Start
|
||||
|
||||
### `project-map:validate [root]`
|
||||
Checks all `.pi-map.md` files for staleness: missing files, orphaned entries, changed signatures, and dirty markers.
|
||||
```bash
|
||||
# Install globally
|
||||
npm install -g pi-project-map
|
||||
|
||||
### `project-map:reinit [path]`
|
||||
Force full re-initialization of the entire project or a specific subtree. Clears all dirty markers.
|
||||
# Generate analysis files for the entire project
|
||||
project-map init
|
||||
|
||||
# After editing a file, update its directory's analysis
|
||||
project-map patch src/components/Button.tsx
|
||||
|
||||
# Check for staleness
|
||||
project-map validate
|
||||
|
||||
# Force full regeneration
|
||||
project-map reinit
|
||||
```
|
||||
|
||||
## Format
|
||||
|
||||
Each `.pi-map.md` uses dense markdown with conventions:
|
||||
Each `.pi-map.md` uses dense markdown optimized for LLM consumption:
|
||||
|
||||
```markdown
|
||||
# pkg/auth
|
||||
@@ -33,6 +50,60 @@ Guard pattern on routes. Tokens short-lived (15m), refresh long-lived (7d). Rota
|
||||
-
|
||||
```
|
||||
|
||||
### Abbreviations
|
||||
|
||||
| Abbreviation | Meaning |
|
||||
|-------------|---------|
|
||||
| `exp:` | Exported symbols |
|
||||
| `dep:` | Dependencies |
|
||||
| `pkg/` | Internal package reference |
|
||||
|
||||
## Tools
|
||||
|
||||
### `project-map:init [root]`
|
||||
Runs a full project scan and generates `.pi-map.md` files in every directory.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
project-map init
|
||||
project-map init ~/my-project
|
||||
```
|
||||
|
||||
### `project-map:patch <file-path>`
|
||||
Updates the `.pi-map.md` for the directory containing the given file.
|
||||
|
||||
**Behavior:**
|
||||
- Small packages (< 10 files): full rewrite
|
||||
- Large packages (>= 10 files): section-level patch
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
project-map patch src/components/Button.tsx
|
||||
```
|
||||
|
||||
### `project-map:validate [root]`
|
||||
Checks all `.pi-map.md` files for staleness.
|
||||
|
||||
**Detects:**
|
||||
- Missing files (new files not yet in `.pi-map.md`)
|
||||
- Orphaned entries (files listed but deleted)
|
||||
- Stale signatures (exports changed since last scan)
|
||||
- Dirty markers (packages flagged for reconciliation)
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
project-map validate
|
||||
```
|
||||
|
||||
### `project-map:reinit [path]`
|
||||
Force full re-initialization. Clears all dirty markers.
|
||||
|
||||
**Example:**
|
||||
```bash
|
||||
project-map reinit
|
||||
project-map reinit src/components
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Create `.pi-project-map.json` in the project root:
|
||||
@@ -41,16 +112,41 @@ Create `.pi-project-map.json` in the project root:
|
||||
{
|
||||
"ignorePatterns": ["node_modules", ".git"],
|
||||
"smallPackageThreshold": 10,
|
||||
"llmModel": "gpt-4o-mini",
|
||||
"contextBudget": 4000,
|
||||
"autoInjectPrompt": true
|
||||
}
|
||||
```
|
||||
|
||||
## Installation
|
||||
| Option | Default | Description |
|
||||
|--------|---------|-------------|
|
||||
| `ignorePatterns` | `node_modules`, `.git`, `dist`, etc. | Additional ignore patterns |
|
||||
| `smallPackageThreshold` | `10` | File count threshold for full rewrite vs patch |
|
||||
| `contextBudget` | `4000` | Max tokens to spend on analysis files |
|
||||
| `autoInjectPrompt` | `true` | Auto-inject maintenance instructions |
|
||||
|
||||
```bash
|
||||
npm install -g pi-project-map
|
||||
```
|
||||
## Agent Instructions
|
||||
|
||||
Then add to your Pi skills configuration.
|
||||
When `.pi-map.md` files exist in the project:
|
||||
|
||||
1. **Read them at session start** to build project understanding without scanning every file
|
||||
2. **Run `project-map:patch <path>`** after editing any source file
|
||||
3. **Run `project-map:validate`** if you suspect staleness before making architectural decisions
|
||||
4. **Trust the analysis** for orientation, but verify critical details by reading source when needed
|
||||
|
||||
## Best Practices
|
||||
|
||||
- Run `project-map:init` after cloning a new repository
|
||||
- Run `project-map:reinit` periodically (daily/weekly) to catch changes made outside the agent
|
||||
- Add `.pi-map.md` to `.gitignore` — they are derived artifacts
|
||||
- For very large projects (> 1000 directories), consider running `init` on subdirectories
|
||||
|
||||
## Supported Languages
|
||||
|
||||
| Language | AST Parsing | Heuristic Extraction |
|
||||
|----------|------------|---------------------|
|
||||
| TypeScript / TSX | Full | Full |
|
||||
| JavaScript / JSX | Full | Full |
|
||||
| Python | Partial | Full |
|
||||
| Go | Partial | Full |
|
||||
| Rust | Partial | Full |
|
||||
| Other | - | Full (filename + regex patterns) |
|
||||
|
||||
Reference in New Issue
Block a user