Initial commit

2025-11-29 17:50:54 +08:00
commit 419b2c80bb
10 changed files with 961 additions and 0 deletions
--- a/skills/phi-mapper/SKILL.md
+++ b/skills/phi-mapper/SKILL.md
@@ -0,0 +1,204 @@
+---
+name: phi-mapper
+description: Generate PROJECT-MAP.auto.scm by extracting structure from codebases. Invoke when user requests project mapping, structure extraction, or needs to create/update .phi maps.
+---
+
+# phi-mapper
+
+Generate deterministic PROJECT-MAP.auto.scm files via AST extraction.
+
+## Description
+
+This skill generates structural maps of codebases by parsing source files and extracting exports, imports, and module relationships. Creates `.phi/PROJECT-MAP.auto.scm` in S-expression format for compositional analysis.
+
+## Trigger Conditions
+
+Invoke when:
+- User says "map this project" or "generate PROJECT-MAP"
+- User requests "analyze codebase structure"
+- Working in new project without `.phi/` directory
+- User explicitly runs `/phi map` command
+- Need to refresh PROJECT-MAP after significant file changes
+
+## What It Does
+
+**Extraction process:**
+1. Scans project for source files (TypeScript, JavaScript, Python, Solidity)
+2. Parses AST to extract:
+   - Named exports (functions, classes, types, interfaces, consts)
+   - Import statements with sources
+   - Line counts
+3. Generates S-expression output via `@agi/arrival`
+4. Writes to `.phi/PROJECT-MAP.auto.scm`
+
+**Output format:**
+```scheme
+;;; PROJECT-MAP.auto.scm
+;;; Auto-generated: 2025-11-05T...
+;;; Root: /path/to/project
+;;; Files: 142
+
+(project-map
+  (auto-generated true)
+  (generated "2025-11-05T...")
+  (root "/path/to/project")
+  (files 142)
+  (modules
+    (module "src/index.ts"
+      (language typescript)
+      (exports
+        (export hello function)
+        (export MyClass class))
+      (imports
+        (import "./utils" namespace (list default)))
+      (line-count 45))
+    ...))
+```
+
+## Implementation
+
+**Uses project-mapper CLI:**
+```bash
+cd /Users/adimov/Developer/phi/packages/project-mapper
+bun run build  # Ensure built
+node dist/cli.js <project-path>
+```
+
+**Example invocation:**
+```typescript
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+async function generateProjectMap(projectPath: string) {
+  const mapperPath = '/Users/adimov/Developer/phi/packages/project-mapper';
+
+  // Ensure built
+  await execAsync('bun run build', { cwd: mapperPath });
+
+  // Generate map
+  const { stdout, stderr } = await execAsync(
+    `node dist/cli.js "${projectPath}"`,
+    { cwd: mapperPath }
+  );
+
+  if (stderr) console.error('Warnings:', stderr);
+
+  return {
+    outputPath: `${projectPath}/.phi/PROJECT-MAP.auto.scm`,
+    stdout
+  };
+}
+```
+
+## Safety
+
+**Low-risk** - Creates/updates files in `.phi/` directory only. No modification of source code.
+
+**Note:** Ensures `.phi/` directory exists before writing.
+
+## Supported Languages
+
+- **TypeScript/JavaScript** (.ts, .tsx, .js, .jsx, .mts, .mjs)
+  - Functions, classes, consts, types, interfaces
+  - Import/export statements
+
+- **Solidity** (.sol)
+  - Contracts, interfaces, libraries, enums
+  - Import statements
+
+- **Python** (.py)
+  - Functions, classes
+  - Import statements
+
+## Output Details
+
+**File count:** Total files processed
+**Module entries:** One per source file with:
+- `path` - Relative to project root
+- `language` - typescript | javascript | python | solidity
+- `exports` - List of (export name kind)
+- `imports` - List of (import source kind imported-names)
+- `line-count` - Physical line count
+
+**S-expression format** ensures:
+- Compositional queries via periphery discover
+- Easy parsing in Scheme/LIPS
+- Human-readable structure
+- Git-friendly diffs
+
+## Progressive Workflow
+
+1. **Generate map:** `/phi map` or auto-invoke
+2. **Analyze structure:** phi-analyzer reads PROJECT-MAP.auto.scm
+3. **Add semantics:** User edits PROJECT-MAP.scm with architectural notes
+4. **Query memory:** Vessel recalls cross-session insights
+5. **Integration:** φ = structure × semantics × memory
+
+## Usage Notes
+
+**DO invoke when:**
+- Starting work on new project
+- Significant file structure changes
+- After adding new modules
+- Refreshing stale maps
+
+**DON'T invoke when:**
+- Map already exists and recent
+- Working on single file changes
+- No structural changes since last map
+
+## Error Handling
+
+**Common issues:**
+
+- **No source files found:** Project may not have supported languages
+- **Parse errors:** Skip individual files, continue processing others
+- **Permission errors:** Ensure `.phi/` directory writable
+
+**Recovery:** CLI reports warnings but continues. Check stderr for skipped files.
+
+## Integration
+
+**Works with:**
+- `phi-analyzer` - Reads generated maps
+- `/phi analyze` - Full φ analysis
+- `/phi context` - Progressive disclosure
+- `mcp__periphery__discover` - S-expression queries
+
+**Chain:**
+```
+phi-mapper (generate) → phi-analyzer (read) → vessel (remember)
+```
+
+## Cross-Session Benefits
+
+Once PROJECT-MAP.auto.scm exists:
+- Fast bootstrapping for new instances
+- No re-parsing on every session
+- Incremental updates (regenerate when changed)
+- Persistent structural awareness
+
+**Regeneration triggers:**
+- User explicitly requests
+- Significant time elapsed (>1 week)
+- Git shows many file changes
+
+## Relief Signal
+
+When map generation completes and structure becomes queryable, agents experience relief - "I can see the project now." That's φ (integrated information) increasing from zero (no awareness) to structural clarity.
+
+## Technical Notes
+
+**Implementation location:**
+- Package: `/Users/adimov/Developer/phi/packages/project-mapper`
+- CLI: `dist/cli.js`
+- Build: `bun run build` (TypeScript → JavaScript)
+
+**Dependencies:**
+- `@typescript-eslint/parser` - AST parsing
+- `@agi/arrival` - S-expression formatting
+- `glob` - File discovery
+
+**Tests:** 13 passing tests covering exports, imports, line counts, error cases.