Reskil

[alvinunreal]

Summary

Changes

[greptile-apps]

Greptile Overview

Greptile Summary

This PR adds a new "Cartography" skill that enables AI agents to generate hierarchical codebase documentation. The implementation introduces a hash-based change detection system that tracks file modifications in .codemap.json and generates human/AI-readable codemap.md files for each directory.

Key Changes:

• New cartography CLI script (scripts/cartography.ts) with scan/hash/update/changes commands
• Integration as a plugin tool via src/tools/cartography/tool.ts
• Cartography skill assigned to the Explorer agent by default
• Dependencies added: hash-wasm, ignore, yaml
• Generated codemap.md files documenting existing codebase structure
• Comprehensive design documentation in cartography.md

Implementation Details:

• Uses MD5 hashing for fast change detection (not for security)
• Respects .gitignore patterns and default excludes (node_modules, .git, etc.)
• Parallel exploration workflow: Orchestrator coordinates multiple Explorer agents
• Bottom-up analysis: leaf folders mapped before parents

Issue Found:

• Line 254 in scripts/cartography.ts contains redundant computation (already noted in previous review thread)

Confidence Score: 4/5

• This PR is safe to merge with one minor redundant computation issue already identified
• The implementation is solid with good architecture and comprehensive documentation. The only issue (line 254 redundant computation) was already flagged in previous reviews and doesn't affect runtime correctness, just efficiency. All integrations are clean, dependencies are appropriate, and the feature is well-documented.
• Pay attention to scripts/cartography.ts line 254 - the redundant .replace(/^\./, '') after adding a dot prefix

Important Files Changed

Filename	Overview
package.json	Added dependencies: hash-wasm, ignore, yaml, and included scripts folder in distribution
scripts/cartography.ts	New CLI script for scanning, hashing, and tracking codebase changes. Contains redundant computation on line 254
src/index.ts	Integrated cartography tool into main plugin tool registry
src/tools/cartography/tool.ts	Plugin wrapper that executes cartography script with session context and JSON parsing
src/tools/skill/builtin.ts	Added cartography skill definition and assigned to explorer agent by default

Sequence Diagram

sequenceDiagram
    participant User
    participant Orchestrator
    participant CartographyTool
    participant CartographyScript
    participant FileSystem
    participant Explorer

    User->>Orchestrator: Request codebase mapping
    Orchestrator->>CartographyTool: cartography scan . --extensions ts,tsx
    CartographyTool->>CartographyScript: Execute bun run scripts/cartography.ts scan
    CartographyScript->>FileSystem: Read .gitignore and scan directories
    FileSystem-->>CartographyScript: Return file list
    CartographyScript-->>CartographyTool: Return JSON with files
    CartographyTool-->>Orchestrator: Return scanned files
    
    Orchestrator->>CartographyTool: cartography update src --extensions ts,tsx
    CartographyTool->>CartographyScript: Execute update command
    CartographyScript->>FileSystem: Read existing .codemap.json
    CartographyScript->>FileSystem: Calculate MD5 hashes for files
    FileSystem-->>CartographyScript: Return file contents
    CartographyScript->>CartographyScript: Calculate folder hash
    CartographyScript->>CartographyScript: Compare with existing hashes
    CartographyScript->>FileSystem: Write updated .codemap.json
    CartographyScript-->>CartographyTool: Return changedFiles list
    CartographyTool-->>Orchestrator: Return update result
    
    Orchestrator->>Explorer: Analyze changed files
    Explorer->>FileSystem: Read source files
    FileSystem-->>Explorer: Return file contents
    Explorer->>FileSystem: Write/update codemap.md
    Explorer-->>Orchestrator: Analysis complete
    
    Orchestrator->>CartographyTool: cartography update src --extensions ts,tsx
    CartographyTool->>CartographyScript: Refresh hashes after analysis
    CartographyScript->>FileSystem: Update .codemap.json with new hashes
    CartographyScript-->>CartographyTool: Confirm update
    CartographyTool-->>Orchestrator: Complete
    Orchestrator-->>User: Codebase mapping finished

Loading

[greptile-apps]

_{1 file reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

[greptile-apps]

Redundant computation - the dot prefix is already added by the .map(), so .replace(/^\./, '') just removes what was added.

Suggested change

	.map((e) => '.' + e.trim().replace(/^\./, '')); // 预先计算点号前缀
	.map((e) => (e.startsWith('.') ? e : '.' + e.trim()));

Prompt To Fix With AI

This is a comment left during a code review.
Path: scripts/cartography.ts
Line: 254:254

Comment:
Redundant computation - the dot prefix is already added by the `.map()`, so `.replace(/^\./, '')` just removes what was added.

```suggestion
        .map((e) => (e.startsWith('.') ? e : '.' + e.trim()));
```

How can I resolve this? If you propose a fix, please make it concise.