phi-mapper

# 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 });