diff --git a/.atl/.pi-map.index.md b/.atl/.pi-map.index.md new file mode 100644 index 0000000..3497d6a --- /dev/null +++ b/.atl/.pi-map.index.md @@ -0,0 +1,18 @@ +# .atl (index) +dir: .atl + +## role +Empty directory placeholder, likely intended for Atlassian tool configuration or automation artifacts that have not yet been populated. +## parent +index: ./.pi-map.index.md +map: ./.pi-map.md +## children +- +## files +## links +index: .atl/.pi-map.index.md +map: .atl/.pi-map.md +## workflows +- +## dirty +- diff --git a/.atl/.pi-map.md b/.atl/.pi-map.md new file mode 100644 index 0000000..405a0f5 --- /dev/null +++ b/.atl/.pi-map.md @@ -0,0 +1,18 @@ +# .atl +dir: .atl + +index: .atl/.pi-map.index.md + +## role +Empty directory placeholder, likely intended for Atlassian tool configuration or automation artifacts that have not yet been populated. +## files +## arch +N/A - no files or architectural patterns present in this directory. +## tags +- +## symbols +- +## workflows +- +## dirty +- diff --git a/.gitignore b/.gitignore index 760ca28..d338246 100644 --- a/.gitignore +++ b/.gitignore @@ -4,8 +4,6 @@ coverage/ *.log .DS_Store .env -.pi-map.md -.pi-map.index.md # Local Pi runtime state .atl/ .pi diff --git a/.pi-map.index.md b/.pi-map.index.md new file mode 100644 index 0000000..d168f8f --- /dev/null +++ b/.pi-map.index.md @@ -0,0 +1,61 @@ +# . (index) +dir: . + +## Project Map Protocol + +1. Read this protocol and the root `.pi-map.index.md` first. +2. Use `index:` / `map:` references to open relevant directory indexes and maps. +3. Load indexes before rich maps during task-start navigation. +4. Read the local rich map and actual source before editing. +5. Treat non-empty `## dirty` sections in either artifact as stale. +6. If source and generated artifacts disagree, trust source. +7. If map and index disagree, trust neither blindly; verify from source and regenerate the pair. +8. After editing source, run `project_map_patch` for each changed file. +9. Before broad architectural claims or final handoff, run `project_map_validate` when freshness matters. + +Trust boundary: index routes, map orients, source decides. + +## role +A TypeScript/Node.js CLI tool and Pi extension that generates paired markdown analysis artifacts (.pi-map.index.md and .pi-map.md) to provide hierarchical codebase navigation and contextual orientation for AI coding agents. +## parent +- +## children +- .atl + index: .atl/.pi-map.index.md + map: .atl/.pi-map.md +- fixtures + index: fixtures/.pi-map.index.md + map: fixtures/.pi-map.md +- openspec + index: openspec/.pi-map.index.md + map: openspec/.pi-map.md +- src + index: src/.pi-map.index.md + map: src/.pi-map.md +- tests + index: tests/.pi-map.index.md + map: tests/.pi-map.md +## files +- .gitignore +- .npmrc +- README.md +- SKILL.md +- design-doc.md +- package-lock.json +- package.json +- pi-extension.ts +- troubleshooting.md +- tsconfig.json +- usage-guide.md +## links +index: ./.pi-map.index.md +map: ./.pi-map.md +## workflows +- change project behavior + read: .gitignore, .npmrc, pi-extension.ts +- change project config + read: package-lock.json, package.json, tsconfig.json +- explore project subdirectories + index: .atl/.pi-map.index.md, fixtures/.pi-map.index.md, openspec/.pi-map.index.md +## dirty +- diff --git a/.pi-map.md b/.pi-map.md new file mode 100644 index 0000000..433df53 --- /dev/null +++ b/.pi-map.md @@ -0,0 +1,48 @@ +# . +dir: . + +index: ./.pi-map.index.md + +## Project Map Protocol + +1. Read this protocol and the root `.pi-map.index.md` first. +2. Use `index:` / `map:` references to open relevant directory indexes and maps. +3. Load indexes before rich maps during task-start navigation. +4. Read the local rich map and actual source before editing. +5. Treat non-empty `## dirty` sections in either artifact as stale. +6. If source and generated artifacts disagree, trust source. +7. If map and index disagree, trust neither blindly; verify from source and regenerate the pair. +8. After editing source, run `project_map_patch` for each changed file. +9. Before broad architectural claims or final handoff, run `project_map_validate` when freshness matters. + +Trust boundary: index routes, map orients, source decides. + +## role +A TypeScript/Node.js CLI tool and Pi extension that generates paired markdown analysis artifacts (.pi-map.index.md and .pi-map.md) to provide hierarchical codebase navigation and contextual orientation for AI coding agents. +## files +- .gitignore | Specifies files and directories for Git to ignore in a Node.js/TypeScript project with Pi tooling integration | dep: git +- .npmrc | Configures npm to use legacy peer dependency resolution behavior | dep: npm +- README.md | Documents a CLI tool and Pi extension that generates paired machine-readable analysis artifacts (.pi-map.index.md and .pi-map.md) for hierarchical codebase navigation and agent orientation. | dep: npm, Node.js, Pi runtime environment, LLM provider (OpenAI, etc.), file system +- SKILL.md | Defines a Pi skill that generates and maintains hierarchical paired project-analysis artifacts (`.pi-map.index.md` + `.pi-map.md`) to enable AI agents to navigate codebases without reading every source file. | dep: markdown, AST parsing, LLM API, JSON configuration, CLI/tool interface +- design-doc.md | A design document explaining the internal architecture of `pi-project-map`, a TypeScript/Node.js tool that generates and maintains hierarchical paired markdown artifacts (`.pi-map.index.md` and `.pi-map.md`) to serve as navigation aids for AI coding agents, with both CLI and Pi extension runtime modes. | dep: TypeScript, Node.js, tree-sitter, ignore, LLM client (PiLLMClient/ExternalLLMClient/KimiLLMClient) +- package-lock.json | Auto-generated npm lock file that records exact dependency versions and tree structure for reproducible installs of the "pi-project-map" Node.js CLI tool. | dep: npm, esbuild, eslint, typescript, vitest, openai, tree-sitter, tree-sitter-python, tree-sitter-typescript, p-limit, picocolors, ignore +- package.json | Pi skill for hierarchical project analysis that generates and maintains .pi-map.md files | dep: ignore, openai, p-limit, picocolors, tree-sitter, tree-sitter-python, tree-sitter-typescript, typescript, vitest, eslint, @types/node, @typescript-eslint +- pi-extension.ts | Pi extension that registers tools for managing project map artifacts (.pi-map.md/.pi-map.index.md) and injects contextual hints into agent sessions based on configuration modes. | dep: @mariozechner/pi-coding-agent, typebox, fs, path, ./src/index.js, ./src/config.js, ./src/llm/llm-client.js, ./src/llm/llm-error.js +- troubleshooting.md | Troubleshooting guide for diagnosing and resolving issues with the pi-project-map tool across validation, prompt injection, strict mode, LLM provider, and testing scenarios. | dep: project_map_validate, project_map_patch, project_map_reinit, LLM client, Pi runtime, tree-sitter, npm +- tsconfig.json | Configures TypeScript compiler options for a Node.js project targeting ES2022 with strict type checking and declaration output +- usage-guide.md | User documentation explaining how to use the pi-project-map tool for navigating and maintaining project-map artifacts in codebases. +## arch +Dual-runtime architecture supporting both standalone CLI and Pi extension modes, using a hierarchical paired-file pattern (index + detail) with TypeScript/Node.js, strict type checking, and configuration-driven behavior injection for agent session integration. +## tags +map, project, tree, typescript, sitter, node, npm, js +## symbols +- +## workflows +- change project behavior + read: .gitignore, .npmrc, pi-extension.ts +- change project config + read: package-lock.json, package.json, tsconfig.json +- explore project subdirectories + index: .atl/.pi-map.index.md, fixtures/.pi-map.index.md, openspec/.pi-map.index.md +## dirty +- diff --git a/fixtures/.pi-map.index.md b/fixtures/.pi-map.index.md new file mode 100644 index 0000000..69cdb40 --- /dev/null +++ b/fixtures/.pi-map.index.md @@ -0,0 +1,20 @@ +# fixtures (index) +dir: fixtures + +## role +Provides test data and setup utilities for automated testing across the project. +## parent +index: ./.pi-map.index.md +map: ./.pi-map.md +## children +- fixtures/sample-project + index: fixtures/sample-project/.pi-map.index.md + map: fixtures/sample-project/.pi-map.md +## files +## links +index: fixtures/.pi-map.index.md +map: fixtures/.pi-map.md +## workflows +- +## dirty +- diff --git a/fixtures/.pi-map.md b/fixtures/.pi-map.md new file mode 100644 index 0000000..669d754 --- /dev/null +++ b/fixtures/.pi-map.md @@ -0,0 +1,18 @@ +# fixtures +dir: fixtures + +index: fixtures/.pi-map.index.md + +## role +Provides test data and setup utilities for automated testing across the project. +## files +## arch +Simple static data fixtures with possible factory/helper patterns for consistent test state generation. +## tags +- +## symbols +- +## workflows +- +## dirty +- diff --git a/fixtures/sample-project/.gitignore b/fixtures/sample-project/.gitignore index 711e716..a8b1485 100644 --- a/fixtures/sample-project/.gitignore +++ b/fixtures/sample-project/.gitignore @@ -1,4 +1,3 @@ dist/ node_modules/ -.pi-map.md .env diff --git a/fixtures/sample-project/.pi-map.index.md b/fixtures/sample-project/.pi-map.index.md new file mode 100644 index 0000000..7df5a55 --- /dev/null +++ b/fixtures/sample-project/.pi-map.index.md @@ -0,0 +1,30 @@ +# fixtures/sample-project (index) +dir: fixtures/sample-project + +## role +Provides a minimal sample Node.js/TypeScript project fixture for testing and demonstrating the pi-project-map functionality. +## parent +index: fixtures/.pi-map.index.md +map: fixtures/.pi-map.md +## children +- fixtures/sample-project/docs + index: fixtures/sample-project/docs/.pi-map.index.md + map: fixtures/sample-project/docs/.pi-map.md +- fixtures/sample-project/src + index: fixtures/sample-project/src/.pi-map.index.md + map: fixtures/sample-project/src/.pi-map.md +- fixtures/sample-project/tests + index: fixtures/sample-project/tests/.pi-map.index.md + map: fixtures/sample-project/tests/.pi-map.md +## files +- .gitignore +- README.md +- package.json +- tsconfig.json +## links +index: fixtures/sample-project/.pi-map.index.md +map: fixtures/sample-project/.pi-map.md +## workflows +- +## dirty +- diff --git a/fixtures/sample-project/.pi-map.md b/fixtures/sample-project/.pi-map.md new file mode 100644 index 0000000..6174c83 --- /dev/null +++ b/fixtures/sample-project/.pi-map.md @@ -0,0 +1,22 @@ +# fixtures/sample-project +dir: fixtures/sample-project + +index: fixtures/sample-project/.pi-map.index.md + +## role +Provides a minimal sample Node.js/TypeScript project fixture for testing and demonstrating the pi-project-map functionality. +## files +- .gitignore | Specifies files and directories for Git to ignore in version control | dep: git +- README.md | Provides a brief overview and directory structure for a small test project related to pi-project-map functionality. +- package.json | Defines a sample Node.js project configuration with TypeScript build and Vitest testing scripts. | dep: typescript, vitest +- tsconfig.json | Configures TypeScript compiler options for a Node.js project targeting ES2022 with strict type checking. +## arch +Standard Node.js project structure using TypeScript with strict compilation, Vitest for testing, and ES2022 module output. +## tags +project, typescript, git, readme, node, vitest, package, tsconfig +## symbols +- +## workflows +- +## dirty +- diff --git a/fixtures/sample-project/docs/.pi-map.index.md b/fixtures/sample-project/docs/.pi-map.index.md new file mode 100644 index 0000000..7e22e2e --- /dev/null +++ b/fixtures/sample-project/docs/.pi-map.index.md @@ -0,0 +1,19 @@ +# fixtures/sample-project/docs (index) +dir: fixtures/sample-project/docs + +## role +Provides API documentation and usage examples for the sample project's user management functionality. +## parent +index: fixtures/sample-project/.pi-map.index.md +map: fixtures/sample-project/.pi-map.md +## children +- +## files +- API.md +## links +index: fixtures/sample-project/docs/.pi-map.index.md +map: fixtures/sample-project/docs/.pi-map.md +## workflows +- +## dirty +- diff --git a/fixtures/sample-project/docs/.pi-map.md b/fixtures/sample-project/docs/.pi-map.md new file mode 100644 index 0000000..868e195 --- /dev/null +++ b/fixtures/sample-project/docs/.pi-map.md @@ -0,0 +1,19 @@ +# fixtures/sample-project/docs +dir: fixtures/sample-project/docs + +index: fixtures/sample-project/docs/.pi-map.index.md + +## role +Provides API documentation and usage examples for the sample project's user management functionality. +## files +- API.md | Documents a user management API with user creation/serialization functions and validation utilities +## arch +Documentation-as-code pattern with markdown-based reference material for external API consumers. +## tags +api, user, documents, management, creation, serialization, validation, utilities +## symbols +- +## workflows +- +## dirty +- diff --git a/fixtures/sample-project/src/.pi-map.index.md b/fixtures/sample-project/src/.pi-map.index.md new file mode 100644 index 0000000..847a9ba --- /dev/null +++ b/fixtures/sample-project/src/.pi-map.index.md @@ -0,0 +1,30 @@ +# fixtures/sample-project/src (index) +dir: fixtures/sample-project/src + +## role +Entry point module that demonstrates user creation, email validation, and logging for a sample project. +## parent +index: fixtures/sample-project/.pi-map.index.md +map: fixtures/sample-project/.pi-map.md +## children +- fixtures/sample-project/src/components + index: fixtures/sample-project/src/components/.pi-map.index.md + map: fixtures/sample-project/src/components/.pi-map.md +- fixtures/sample-project/src/models + index: fixtures/sample-project/src/models/.pi-map.index.md + map: fixtures/sample-project/src/models/.pi-map.md +- fixtures/sample-project/src/utils + index: fixtures/sample-project/src/utils/.pi-map.index.md + map: fixtures/sample-project/src/utils/.pi-map.md +## files +- index.ts +## links +index: fixtures/sample-project/src/.pi-map.index.md +map: fixtures/sample-project/src/.pi-map.md +## workflows +- change src behavior + read: index.ts +- explore src subdirectories + index: fixtures/sample-project/src/components/.pi-map.index.md, fixtures/sample-project/src/models/.pi-map.index.md, fixtures/sample-project/src/utils/.pi-map.index.md +## dirty +- diff --git a/fixtures/sample-project/src/.pi-map.md b/fixtures/sample-project/src/.pi-map.md new file mode 100644 index 0000000..ff11967 --- /dev/null +++ b/fixtures/sample-project/src/.pi-map.md @@ -0,0 +1,26 @@ +# fixtures/sample-project/src +dir: fixtures/sample-project/src + +index: fixtures/sample-project/src/.pi-map.index.md + +## role +Entry point module that demonstrates user creation, email validation, and logging for a sample project. +## files +- index.ts | Entry point that creates a user, validates their email, and logs the result | exp: func:main(), call:createUser, call:validateEmail, call:logger.error, call:logger.info | dep: ./models/user.js, ./utils/validation.js, ./utils/logger.js +## arch +Simple procedural script with direct function calls and sequential execution pattern. +## tags +user, email, js, main, call:create, call:validate, call:logger.error, call:logger.info +## symbols +- main +- call:createUser +- call:validateEmail +- call:logger.error +- call:logger.info +## workflows +- change src behavior + read: index.ts +- explore src subdirectories + index: fixtures/sample-project/src/components/.pi-map.index.md, fixtures/sample-project/src/models/.pi-map.index.md, fixtures/sample-project/src/utils/.pi-map.index.md +## dirty +- diff --git a/fixtures/sample-project/src/components/.pi-map.index.md b/fixtures/sample-project/src/components/.pi-map.index.md new file mode 100644 index 0000000..5abcda1 --- /dev/null +++ b/fixtures/sample-project/src/components/.pi-map.index.md @@ -0,0 +1,21 @@ +# fixtures/sample-project/src/components (index) +dir: fixtures/sample-project/src/components + +## role +Provides reusable UI components for building the application's interface. +## parent +index: fixtures/sample-project/src/.pi-map.index.md +map: fixtures/sample-project/src/.pi-map.md +## children +- +## files +- Button.tsx +- UserCard.tsx +## links +index: fixtures/sample-project/src/components/.pi-map.index.md +map: fixtures/sample-project/src/components/.pi-map.md +## workflows +- change components behavior + read: Button.tsx, UserCard.tsx +## dirty +- diff --git a/fixtures/sample-project/src/components/.pi-map.md b/fixtures/sample-project/src/components/.pi-map.md new file mode 100644 index 0000000..1f05758 --- /dev/null +++ b/fixtures/sample-project/src/components/.pi-map.md @@ -0,0 +1,26 @@ +# fixtures/sample-project/src/components +dir: fixtures/sample-project/src/components + +index: fixtures/sample-project/src/components/.pi-map.index.md + +## role +Provides reusable UI components for building the application's interface. +## files +- Button.tsx | A reusable React button component that renders a styled button with configurable label, visual variant, click handler, and disabled state. | exp: ButtonProps, func:Button({ label, variant = "primary", onClick, disabled = false, }: ButtonProps) → JSX.Element | dep: react, React +- UserCard.tsx | Renders a user card component with optional edit and delete action buttons. | exp: UserCardProps, func:UserCard({ user, onEdit, onDelete }: UserCardProps) → JSX.Element, call:onEdit, call:onDelete | dep: react, ../models/user.js, React +## arch +Simple functional React components with props-based configuration, following a basic presentational component pattern. +## tags +button, user, card, react, props, call:on, edit, delete +## symbols +- Button +- UserCard +- ButtonProps +- UserCardProps +- call:onEdit +- call:onDelete +## workflows +- change components behavior + read: Button.tsx, UserCard.tsx +## dirty +- diff --git a/fixtures/sample-project/src/models/.pi-map.index.md b/fixtures/sample-project/src/models/.pi-map.index.md new file mode 100644 index 0000000..0ea7038 --- /dev/null +++ b/fixtures/sample-project/src/models/.pi-map.index.md @@ -0,0 +1,20 @@ +# fixtures/sample-project/src/models (index) +dir: fixtures/sample-project/src/models + +## role +Defines the User data model with creation and serialization capabilities including email validation. +## parent +index: fixtures/sample-project/src/.pi-map.index.md +map: fixtures/sample-project/src/.pi-map.md +## children +- +## files +- user.ts +## links +index: fixtures/sample-project/src/models/.pi-map.index.md +map: fixtures/sample-project/src/models/.pi-map.md +## workflows +- change models behavior + read: user.ts +## dirty +- diff --git a/fixtures/sample-project/src/models/.pi-map.md b/fixtures/sample-project/src/models/.pi-map.md new file mode 100644 index 0000000..5a23888 --- /dev/null +++ b/fixtures/sample-project/src/models/.pi-map.md @@ -0,0 +1,26 @@ +# fixtures/sample-project/src/models +dir: fixtures/sample-project/src/models + +index: fixtures/sample-project/src/models/.pi-map.index.md + +## role +Defines the User data model with creation and serialization capabilities including email validation. +## files +- user.ts | Defines a User interface and provides functions to create and serialize users with email validation. | exp: User, func:createUser(data: Omit) → User, call:validateEmail, call:crypto.randomUUID, raise:Error, func:serializeUser(user: User) → string, call:JSON.stringify | dep: ../utils/validation.js +## arch +Domain model pattern with interface-based typing, pure functions for data transformation, and embedded validation logic. +## tags +user, create, serialize, email, validation, call:validate, call:crypto.random, uuid +## symbols +- createUser +- serializeUser +- User +- call:validateEmail +- call:crypto.randomUUID +- raise:Error +- call:JSON.stringify +## workflows +- change models behavior + read: user.ts +## dirty +- diff --git a/fixtures/sample-project/src/utils/.pi-map.index.md b/fixtures/sample-project/src/utils/.pi-map.index.md new file mode 100644 index 0000000..464b7c8 --- /dev/null +++ b/fixtures/sample-project/src/utils/.pi-map.index.md @@ -0,0 +1,21 @@ +# fixtures/sample-project/src/utils (index) +dir: fixtures/sample-project/src/utils + +## role +Provides foundational cross-cutting utility functions for logging and input validation used throughout the application. +## parent +index: fixtures/sample-project/src/.pi-map.index.md +map: fixtures/sample-project/src/.pi-map.md +## children +- +## files +- logger.ts +- validation.ts +## links +index: fixtures/sample-project/src/utils/.pi-map.index.md +map: fixtures/sample-project/src/utils/.pi-map.md +## workflows +- change utils behavior + read: logger.ts, validation.ts +## dirty +- diff --git a/fixtures/sample-project/src/utils/.pi-map.md b/fixtures/sample-project/src/utils/.pi-map.md new file mode 100644 index 0000000..8b10826 --- /dev/null +++ b/fixtures/sample-project/src/utils/.pi-map.md @@ -0,0 +1,28 @@ +# fixtures/sample-project/src/utils +dir: fixtures/sample-project/src/utils + +index: fixtures/sample-project/src/utils/.pi-map.index.md + +## role +Provides foundational cross-cutting utility functions for logging and input validation used throughout the application. +## files +- logger.ts | Provides a simple typed console logger with timestamps and convenience wrappers for different log levels. | exp: LogLevel, func:log(level: LogLevel, message: string) → void, call:new Date().toISOString, call:console.log, call:level.toUpperCase, func:debug(message: string) → void, call:log, func:info(message: string) → void, call:log, func:warn(message: string) → void, call:log, func:error(message: string) → void, call:log +- validation.ts | Provides basic string validation utilities for emails, non-empty checks, and minimum length requirements. | exp: func:validateEmail(email: string) → boolean, call:EMAIL_REGEX.test, func:validateNotEmpty(value: string) → boolean, call:value.trim, func:validateMinLength(value: string, min: number) → boolean +## arch +Flat utility module pattern with pure functions, no dependencies between modules, each exporting independent typed helper functions. +## tags +call:log, validate, log, logger, validation, empty, length, provides +## symbols +- log +- debug +- info +- warn +- error +- validateEmail +- validateNotEmpty +- validateMinLength +## workflows +- change utils behavior + read: logger.ts, validation.ts +## dirty +- diff --git a/fixtures/sample-project/tests/.pi-map.index.md b/fixtures/sample-project/tests/.pi-map.index.md new file mode 100644 index 0000000..d639c3a --- /dev/null +++ b/fixtures/sample-project/tests/.pi-map.index.md @@ -0,0 +1,21 @@ +# fixtures/sample-project/tests (index) +dir: fixtures/sample-project/tests + +## role +Provides unit test coverage for user model behavior and string validation utilities in the sample project. +## parent +index: fixtures/sample-project/.pi-map.index.md +map: fixtures/sample-project/.pi-map.md +## children +- +## files +- user.test.ts +- validation.test.ts +## links +index: fixtures/sample-project/tests/.pi-map.index.md +map: fixtures/sample-project/tests/.pi-map.md +## workflows +- update tests tests + read: user.test.ts, validation.test.ts +## dirty +- diff --git a/fixtures/sample-project/tests/.pi-map.md b/fixtures/sample-project/tests/.pi-map.md new file mode 100644 index 0000000..0622ac6 --- /dev/null +++ b/fixtures/sample-project/tests/.pi-map.md @@ -0,0 +1,21 @@ +# fixtures/sample-project/tests +dir: fixtures/sample-project/tests + +index: fixtures/sample-project/tests/.pi-map.index.md + +## role +Provides unit test coverage for user model behavior and string validation utilities in the sample project. +## files +- user.test.ts | Unit tests for user model creation, validation, and serialization | dep: vitest, ../src/models/user.js +- validation.test.ts | Unit tests for string validation utility functions | dep: vitest, ../src/utils/validation.js +## arch +Standard test suite using isolated unit tests with file-based grouping by domain concern (model vs. utility). +## tags +validation, unit, tests, user, vitest, src, js, user.test +## symbols +- +## workflows +- update tests tests + read: user.test.ts, validation.test.ts +## dirty +- diff --git a/openspec/.pi-map.index.md b/openspec/.pi-map.index.md new file mode 100644 index 0000000..f816f30 --- /dev/null +++ b/openspec/.pi-map.index.md @@ -0,0 +1,22 @@ +# openspec (index) +dir: openspec + +## role +Defines configuration and project conventions for a TypeScript CLI tool that generates AI-oriented codebase orientation maps for coding agents. +## parent +index: ./.pi-map.index.md +map: ./.pi-map.md +## children +- openspec/changes + index: openspec/changes/.pi-map.index.md + map: openspec/changes/.pi-map.md +## files +- config.yaml +- project.md +## links +index: openspec/.pi-map.index.md +map: openspec/.pi-map.md +## workflows +- +## dirty +- diff --git a/openspec/.pi-map.md b/openspec/.pi-map.md new file mode 100644 index 0000000..b95737c --- /dev/null +++ b/openspec/.pi-map.md @@ -0,0 +1,20 @@ +# openspec +dir: openspec + +index: openspec/.pi-map.index.md + +## role +Defines configuration and project conventions for a TypeScript CLI tool that generates AI-oriented codebase orientation maps for coding agents. +## files +- config.yaml | Defines project configuration, stack metadata, and software-driven development (SDD) workflow rules for a TypeScript-based CLI tool that generates AI-oriented codebase map files. | dep: TypeScript, Node.js, Vitest, npm, openspec +- project.md | Defines project context and conventions for pi-project-map, a Pi skill and CLI tool that generates hierarchical `.pi-map.md` orientation files for coding agents. +## arch +YAML-driven configuration with software-driven development (SDD) workflow rules, hierarchical markdown output generation, and Pi skill integration for AI agent context provision. +## tags +project, map, defines, typescript, cli, tool, generates, config +## symbols +- +## workflows +- +## dirty +- diff --git a/openspec/changes/.pi-map.index.md b/openspec/changes/.pi-map.index.md new file mode 100644 index 0000000..a8ba827 --- /dev/null +++ b/openspec/changes/.pi-map.index.md @@ -0,0 +1,20 @@ +# openspec/changes (index) +dir: openspec/changes + +## role +Manages change tracking, versioning, and audit history for OpenAPI specification modifications +## parent +index: openspec/.pi-map.index.md +map: openspec/.pi-map.md +## children +- openspec/changes/archive + index: openspec/changes/archive/.pi-map.index.md + map: openspec/changes/archive/.pi-map.md +## files +## links +index: openspec/changes/.pi-map.index.md +map: openspec/changes/.pi-map.md +## workflows +- +## dirty +- diff --git a/openspec/changes/.pi-map.md b/openspec/changes/.pi-map.md new file mode 100644 index 0000000..a5e556e --- /dev/null +++ b/openspec/changes/.pi-map.md @@ -0,0 +1,18 @@ +# openspec/changes +dir: openspec/changes + +index: openspec/changes/.pi-map.index.md + +## role +Manages change tracking, versioning, and audit history for OpenAPI specification modifications +## files +## arch +Event-sourced or changelog-based pattern with immutable change records and versioned snapshots +## tags +- +## symbols +- +## workflows +- +## dirty +- diff --git a/openspec/changes/archive/.pi-map.index.md b/openspec/changes/archive/.pi-map.index.md new file mode 100644 index 0000000..74d856d --- /dev/null +++ b/openspec/changes/archive/.pi-map.index.md @@ -0,0 +1,26 @@ +# openspec/changes/archive (index) +dir: openspec/changes/archive + +## role +Provides persistent storage and retrieval of historical change records in an archived format for audit trails and long-term data retention. +## parent +index: openspec/changes/.pi-map.index.md +map: openspec/changes/.pi-map.md +## children +- openspec/changes/archive/2026-06-11-layered-map-protocol + index: openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.index.md + map: openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.md +- openspec/changes/archive/2026-06-11-map-context-retrieval + index: openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.index.md + map: openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.md +- openspec/changes/archive/2026-06-11-project-map-prompt-injection + index: openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.index.md + map: openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.md +## files +## links +index: openspec/changes/archive/.pi-map.index.md +map: openspec/changes/archive/.pi-map.md +## workflows +- +## dirty +- diff --git a/openspec/changes/archive/.pi-map.md b/openspec/changes/archive/.pi-map.md new file mode 100644 index 0000000..6f5cf7c --- /dev/null +++ b/openspec/changes/archive/.pi-map.md @@ -0,0 +1,18 @@ +# openspec/changes/archive +dir: openspec/changes/archive + +index: openspec/changes/archive/.pi-map.index.md + +## role +Provides persistent storage and retrieval of historical change records in an archived format for audit trails and long-term data retention. +## files +## arch +Simple archive storage pattern using file-based serialization with read/write operations for immutable change log records, likely with date-based or sequential naming conventions. +## tags +- +## symbols +- +## workflows +- +## dirty +- diff --git a/openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.index.md b/openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.index.md new file mode 100644 index 0000000..5fe33f8 --- /dev/null +++ b/openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.index.md @@ -0,0 +1,26 @@ +# openspec/changes/archive/2026-06-11-layered-map-protocol (index) +dir: openspec/changes/archive/2026-06-11-layered-map-protocol + +## role +Contains archived specification documents for a deprecated layered map protocol that introduced paired navigation artifacts to replace bulk-loading of map files with a tiered directory-level routing system. +## parent +index: openspec/changes/archive/.pi-map.index.md +map: openspec/changes/archive/.pi-map.md +## children +- +## files +- apply-progress.md +- archive-report.md +- design.md +- proposal.md +- spec.md +- sync-report.md +- tasks.md +- verify-report.md +## links +index: openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.index.md +map: openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.md +## workflows +- +## dirty +- diff --git a/openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.md b/openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.md new file mode 100644 index 0000000..9337ef4 --- /dev/null +++ b/openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.md @@ -0,0 +1,26 @@ +# openspec/changes/archive/2026-06-11-layered-map-protocol +dir: openspec/changes/archive/2026-06-11-layered-map-protocol + +index: openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.index.md + +## role +Contains archived specification documents for a deprecated layered map protocol that introduced paired navigation artifacts to replace bulk-loading of map files with a tiered directory-level routing system. +## files +- apply-progress.md | Documents the completion status and summary of implemented features for an "Apply Progress" project or milestone. +- archive-report.md | Documents the archival status and metadata for a deprecated layered map protocol specification directory. +- design.md | Design document for a paired navigation-first artifact model that generates both routing indexes and orientation rich-maps from a shared intermediate directory model while preserving existing pipeline behavior. | dep: spec.md, src/format.ts, src/init.ts, src/patch.ts, src/validate.ts, pi-extension.ts, README.md, SKILL.md, design-doc.md, CLI argument parsing, YAML config handling +- proposal.md | Proposes a layered navigation protocol using paired index/map artifacts to replace bulk-loading of map files with a tiered, directory-level routing system. +- spec.md | Specifies a layered navigation protocol for project maps using paired index and rich map artifacts per directory with defined generation, patching, and validation behaviors. +- sync-report.md | Documents that a canonical spec synchronization was not performed due to legacy flat change artifact structure, with user-approved archival fallback +- tasks.md | Defines a phased task plan for implementing a layered paired-map protocol with directory-level `.pi-map.md` and `.pi-map.index.md` artifacts, routing metadata, patch sizing, validation, and documentation. | dep: design.md, pi-extension.ts, SKILL.md, README.md, design-doc.md, npm/node toolchain +- verify-report.md | Documents verification results for a code change implementing a layered map protocol with paired artifacts. | dep: npm, vitest, node, typescript +## arch +Document-driven specification archive using a layered architecture with paired index/map artifacts per directory, phased implementation tasks, and formal verification/synchronization reporting, preserved for historical reference despite legacy flat structure preventing canonical sync. +## tags +map, md, report, design, ts, layered, protocol, directory +## symbols +- +## workflows +- +## dirty +- diff --git a/openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.index.md b/openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.index.md new file mode 100644 index 0000000..c7a2d0d --- /dev/null +++ b/openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.index.md @@ -0,0 +1,26 @@ +# openspec/changes/archive/2026-06-11-map-context-retrieval (index) +dir: openspec/changes/archive/2026-06-11-map-context-retrieval + +## role +Archives a completed specification change package for implementing metadata-driven context retrieval capabilities in a project-map tool. +## parent +index: openspec/changes/archive/.pi-map.index.md +map: openspec/changes/archive/.pi-map.md +## children +- +## files +- apply-progress.md +- archive-report.md +- design.md +- proposal.md +- spec.md +- sync-report.md +- tasks.md +- verify-report.md +## links +index: openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.index.md +map: openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.md +## workflows +- +## dirty +- diff --git a/openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.md b/openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.md new file mode 100644 index 0000000..7186afc --- /dev/null +++ b/openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.md @@ -0,0 +1,26 @@ +# openspec/changes/archive/2026-06-11-map-context-retrieval +dir: openspec/changes/archive/2026-06-11-map-context-retrieval + +index: openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.index.md + +## role +Archives a completed specification change package for implementing metadata-driven context retrieval capabilities in a project-map tool. +## files +- apply-progress.md | Documents the completion status of a project implementing deterministic index-first context retrieval via tool and CLI, along with retrieval documentation and skill guidance. +- archive-report.md | Documents the archival of a set of specification change documents including metadata about archive location, mode, and preserved inputs. +- design.md | Design document for a lightweight context retrieval system that scans paired project-map metadata to find and return relevant code context as a markdown bundle for AI agents. | dep: pi-extension.ts, src/index.ts, src/cli/*, paired-artifact parser/model from layered protocol, .pi-map.index.md, .pi-map.md +- proposal.md | Proposes a "Map Context Retrieval" tool that enables natural-language queries to return compact, metadata-driven context bundles from a layered map protocol. | dep: layered-map-protocol, Pi tool, CLI +- spec.md | Defines a specification for adding a retrieval-oriented `context` command to a project-map tool that converts user tasks into compact routing bundles for LLM agents | dep: layered-map-protocol, project-map (Pi tool/CLI), markdown output formatting +- sync-report.md | Documents that a canonical spec synchronization was not performed due to legacy flat change artifact structure, with user-approved archival fallback +- tasks.md | Defines implementation tasks for adding map context retrieval functionality to a Pi tool, using paired index/map metadata for ranked, query-based context retrieval. | dep: design.md, Pi tool, project-map context, npm (typecheck, test, lint) +- verify-report.md | Documents verification results for a code change implementing deterministic index-first context retrieval. | dep: npm, vitest, node, CLI tooling +## arch +Flat archival directory structure preserving legacy change artifacts (specification, design, proposal, tasks, verification, sync, apply-progress, archive-report) without hierarchical organization. +## tags +map, context, retrieval, report, documents, project, index, tool +## symbols +- +## workflows +- +## dirty +- diff --git a/openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.index.md b/openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.index.md new file mode 100644 index 0000000..0cee878 --- /dev/null +++ b/openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.index.md @@ -0,0 +1,26 @@ +# openspec/changes/archive/2026-06-11-project-map-prompt-injection (index) +dir: openspec/changes/archive/2026-06-11-project-map-prompt-injection + +## role +Archives a completed prompt-injection feature specification that enables runtime injection of project-map artifacts into LLM context with configurable guidance modes and budget controls. +## parent +index: openspec/changes/archive/.pi-map.index.md +map: openspec/changes/archive/.pi-map.md +## children +- +## files +- apply-progress.md +- archive-report.md +- design.md +- proposal.md +- spec.md +- sync-report.md +- tasks.md +- verify-report.md +## links +index: openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.index.md +map: openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.md +## workflows +- +## dirty +- diff --git a/openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.md b/openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.md new file mode 100644 index 0000000..867c408 --- /dev/null +++ b/openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.md @@ -0,0 +1,26 @@ +# openspec/changes/archive/2026-06-11-project-map-prompt-injection +dir: openspec/changes/archive/2026-06-11-project-map-prompt-injection + +index: openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.index.md + +## role +Archives a completed prompt-injection feature specification that enables runtime injection of project-map artifacts into LLM context with configurable guidance modes and budget controls. +## files +- apply-progress.md | Documents the completion status and implementation details of a prompt-injection feature delivered across five incremental slices. +- archive-report.md | Documents the archival status and metadata of a deprecated project change specification directory. +- design.md | Design document for adding a runtime prompt injection layer that guides LLM behavior using paired map/index artifacts through configurable modes, canonical markers, and budgeted context expansion. | dep: pi-extension.ts, src/config.ts, spec.md, event.messages, before_agent_start, before_provider_request, context hooks, .pi-project-map.json, .pi-map.index.md, .pi-map.md +- proposal.md | Proposes a runtime prompt-injection policy for project-map artifacts with configurable guidance modes, hybrid context budgets, and reinjection avoidance +- spec.md | Defines a specification for automatic runtime prompt injection of project map/index artifacts with configurable guidance modes, budgeted expansion, and reinjection avoidance based on actual outgoing context scanning. +- sync-report.md | Documents that a canonical spec synchronization was not performed due to legacy flat change artifact structure, with user-approved archival fallback +- tasks.md | Defines phased implementation tasks for a prompt injection policy system that controls how project map artifacts are injected into LLM context with budget constraints, mode semantics, and reinjection avoidance. +- verify-report.md | Documents verification results for a prompt-injection security feature implementation in a software project. +## arch +Document-driven specification architecture using phased slice-based delivery (proposal → design → spec → tasks → verification), with flat artifact structure and canonical marker-based context expansion patterns. +## tags +map, prompt, injection, project, report, documents, artifacts, context +## symbols +- +## workflows +- +## dirty +- diff --git a/src/.pi-map.index.md b/src/.pi-map.index.md new file mode 100644 index 0000000..14b4b32 --- /dev/null +++ b/src/.pi-map.index.md @@ -0,0 +1,49 @@ +# src (index) +dir: src + +## role +A project mapping and codebase navigation system that generates, maintains, and queries AI-readable documentation artifacts for software projects. +## parent +index: ./.pi-map.index.md +map: ./.pi-map.md +## children +- src/ast + index: src/ast/.pi-map.index.md + map: src/ast/.pi-map.md +- src/cli + index: src/cli/.pi-map.index.md + map: src/cli/.pi-map.md +- src/llm + index: src/llm/.pi-map.index.md + map: src/llm/.pi-map.md +- src/types + index: src/types/.pi-map.index.md + map: src/types/.pi-map.md +## files +- cli.ts +- config.ts +- directory-model.ts +- discover.ts +- format.ts +- index.ts +- init.ts +- merge.ts +- patch.ts +- prompt-injection.ts +- retrieve.ts +- routing-metadata.ts +- validate.ts +## links +index: src/.pi-map.index.md +map: src/.pi-map.md +## workflows +- change src behavior + read: cli.ts, config.ts, directory-model.ts +- change src CLI + read: cli.ts +- change src config + read: config.ts +- explore src subdirectories + index: src/ast/.pi-map.index.md, src/cli/.pi-map.index.md, src/llm/.pi-map.index.md +## dirty +- diff --git a/src/.pi-map.md b/src/.pi-map.md new file mode 100644 index 0000000..11457bb --- /dev/null +++ b/src/.pi-map.md @@ -0,0 +1,45 @@ +# src +dir: src + +index: src/.pi-map.index.md + +## role +A project mapping and codebase navigation system that generates, maintains, and queries AI-readable documentation artifacts for software projects. +## files +- cli.ts | Entry point for a CLI application that delegates to the cli.js module | dep: ./cli/cli.js +- config.ts | Defines configuration types, defaults, and loading logic for a project mapping tool | exp: PromptInjectionMode, SkillConfig, DEFAULT_CONFIG, func:loadConfig(cwd: string) → SkillConfig, call:join, call:existsSync, call:readFileSync, call:JSON.parse | dep: fs, path +- directory-model.ts | Defines TypeScript interfaces and utilities for modeling directory artifacts, file entries, and project map protocols in a codebase navigation system. | exp: FileEntry, DirectoryArtifactModel, WorkflowHint, PROJECT_MAP_PROTOCOL_LINES, RoutingMetadataOptions, func:createDirectoryModel(opts: { dir: string; role: string; files: FileEntry[]; arch: string; parent?: string; children?: string[]; isRoot?: boolean; dirty?: string; }) → DirectoryArtifactModel +- discover.ts | Recursively discovers and lists files in a project directory while respecting .gitignore patterns and default ignore rules. | exp: DirectoryEntry, func:discoverProject(rootPath: string) → DirectoryEntry[], call:ignore().add, call:readFileSync, call:ig.add, call:relative, call:ig.ignores, call:relDir.replace, call:readdirSync, call:join(relDir, item).replace, call:statSync, call:st.isDirectory, call:subdirs.push, call:files.push, call:entries.push, call:walk | dep: fs, path, ignore +- format.ts | Renders and parses markdown-based directory/package maps and index files for project documentation, converting between structured data models and human-readable markdown formats. | exp: PackageMapData, func:renderPackageMap(data: PackageMapData) → string, call:convertPackageMapToModel, call:renderDirectoryMap, func:parsePackageMap(markdown: string) → PackageMapData, call:parseDirectoryMap, call:convertModelToPackageMap, func:renderDirectoryMap(model: DirectoryArtifactModel) → string, call:lines.push, call:file.exports.join, call:file.deps.join, call:parts.push, call:parts.join, call:model.tags.join, call:wf.read.join, call:wf.index.join, call:wf.map.join, call:wf.files.join, call:lines.join, func:parseDirectoryMap(markdown: string) → DirectoryArtifactModel, call:markdown.split("\n").map, call:l.trimEnd, call:line.startsWith, call:line.slice(2).trim, call:line.slice(5).trim, call:parseFileLine, call:result.files.push, call:result.tags.push, call:line .split(",") .map((s) => s.trim()) .filter, call:s.trim, call:result.symbols.push, call:result.workflows.push, call:line .slice(8) .trim() .split(",") .map((s) => s.trim()) .filter, call:line .slice(9) .trim() .split(",") .map((s) => s.trim()) .filter, call:line .slice(7) .trim() .split(",") .map((s) => s.trim()) .filter, func:renderDirectoryIndex(model: DirectoryArtifactModel) → string, call:lines.push, call:wf.read.join, call:wf.index.join, call:wf.map.join, call:wf.files.join, call:lines.join, func:parseDirectoryIndex(markdown: string) → DirectoryArtifactModel, call:markdown.split("\n").map, call:l.trimEnd, call:line.startsWith, call:line.slice(2).trim, call:title.replace, call:line.slice(5).trim, call:line.slice(7).trim().replace, call:result.children.push, call:result.files.push, call:result.workflows.push, call:line .slice(8) .trim() .split(",") .map((s) => s.trim()) .filter, call:s.trim, call:line .slice(9) .trim() .split(",") .map((s) => s.trim()) .filter, call:line .slice(7) .trim() .split(",") .map((s) => s.trim()) .filter | dep: ./directory-model.js +- index.ts | Main entry point for a project mapping skill that exports initialization, patching, validation, formatting, directory modeling, routing metadata, context retrieval, and prompt injection utilities | dep: init.js, patch.js, validate.js, format.js, directory-model.js, routing-metadata.js, retrieve.js, prompt-injection.js +- init.ts | Generates and writes project map artifacts (.pi-map.md and .pi-map.index.md) for directories by processing files through LLM and AST extraction, with support for full project initialization and smart partial reinitialization. | exp: ProgressInfo, InitOptions, DirectoryContext, ArtifactWriteMode, func:initProject(rootPath: string, options: InitOptions) → Promise, call:discoverProject, call:entries.reduce, call:loadConfig, call:options.onProgress, call:entries.map, call:buildParentMap, call:buildChildrenMap, call:generateDirectoryArtifacts, call:entries.slice(0, i).reduce, call:console.log, func:getAncestorEntries(entries: DirectoryEntry[], ctx: DirectoryContext, entry: DirectoryEntry) → DirectoryEntry[], call:ctx.parentMap.get, call:entries.find, call:result.push, func:buildDirectoryContext(entries: DirectoryEntry[], targetEntry: DirectoryEntry) → DirectoryContext, call:entries.map, call:buildParentMap, call:buildChildrenMap, func:buildDirectoryArtifactModel(entry: DirectoryEntry, ctx: DirectoryContext, llmClient: LLMClient, cacheDir: string, onProgress: (info: ProgressInfo) => void, routingOpts: RoutingMetadataOptions) → Promise, call:processFiles, call:join, call:extractFileLLM, call:extractFileAST, call:mergeFileData, call:onProgress, call:extractPackageLLM, call:createDirectoryModel, call:ctx.parentMap.get, call:ctx.childrenMap.get, call:populateRoutingMetadata, func:writeDirectoryArtifacts(entry: DirectoryEntry, model: DirectoryArtifactModel, writeMode: ArtifactWriteMode) → void, call:join, call:writeFileSync, call:renderDirectoryMap, call:renderDirectoryIndex, func:generateDirectoryArtifacts(entry: DirectoryEntry, ctx: DirectoryContext, llmClient: LLMClient, cacheDir: string, onProgress: (info: ProgressInfo) => void, routingOpts: RoutingMetadataOptions, writeMode: ArtifactWriteMode) → Promise, call:buildDirectoryArtifactModel, call:writeDirectoryArtifacts, func:reinitPath(path: string, options: InitOptions) → Promise, call:resolve, call:findProjectRoot, call:normalizeRelativePath, call:relative, call:discoverProject, call:loadConfig, call:countFiles, call:initProject, call:entries.filter, call:isSubdirectory, call:entries.find, call:buildDirectoryContext, call:getAncestorEntries, call:Array.from, call:generateDirectoryArtifacts, call:options.onProgress, call:console.log, call:percentage.toFixed, func:generateDirectoryMap(entry: DirectoryEntry, llmClient: LLMClient, cacheDir: string) → Promise, call:buildDirectoryContext, call:loadConfig, call:generateDirectoryArtifacts | dep: ./discover.js, ./directory-model.js, ./format.js, ./llm/llm-extract.js, ./ast/ast-extract.js, ./merge.js, ./llm/llm-batch.js, fs, path, ./llm/llm-client.js, ./routing-metadata.js, ./config.js +- merge.ts | Merges LLM-generated file metadata with AST-extracted structural data into a unified FileEntry format using a compact DSL encoding. | exp: func:mergeFileData(fileName: string, llm: LLMFileData, ast: ASTFileData | null) → FileEntry, call:richNames.add, call:mergedExports.filter, call:richNames.has, call:method.params.join(", ").replace, call:method.returns.replace, call:classExports.push, call:dedupedExports.push, call:func.params.join(", ").replace, call:func.returns.replace | dep: ./directory-model.js +- patch.ts | Patches project directory artifacts by determining whether a file change requires small or structural updates to `.pi-map.md` files | exp: PatchMode, PatchOptions, func:patchFile(filePath: string, llmClient: LLMClient, cacheDir: string, options: PatchOptions) → Promise, call:resolve, call:process.cwd, call:dirname, call:normalizeRelativePath, call:relative, call:discoverProject, call:entries.find, call:console.warn, call:loadConfig, call:determinePatchMode, call:buildDirectoryContext, call:generateDirectoryArtifacts, call:getAncestorEntries, call:console.log, call:joinArtifactPath | dep: path, fs, ./format.js, ./init.js, ./discover.js, ./llm/llm-client.js, ./config.js +- prompt-injection.ts | Implements a prompt injection system for project-map context management, including root-pair artifact detection, mode-based injection decisions, protocol-path validation, and strict-mode bypass guards for sensitive AI actions. | exp: ReinjectDecision, RelevantTurnType, RootPairMtimes, ROOT_PAIR_START_MARKER, ROOT_PAIR_END_MARKER, TRUST_BOUNDARY_TEXT, BYPASS_MARKER_PREFIX, StrictBypassDecision, ArtifactPair, func:shouldReinjectForEvent(event: { messages?: Array<{ content?: unknown; text?: string }>; type?: string; payload?: unknown; }, mode: PromptInjectionMode) → ReinjectDecision, call:outgoingMessagesHaveMarker, call:providerPayloadHasMarker, call:isRelevantTurnForReinjection, func:outgoingMessagesHaveMarker(messages: Array<{ content?: unknown; text?: string }>) → boolean, call:messages.some, call:hasRootPairMarker, call:extractTextFromMessage, func:providerPayloadHasMarker(payload: unknown) → boolean, call:hasRootPairMarker, call:JSON.stringify, func:isRelevantTurnForReinjection(eventType: string) → boolean, call:relevant.includes, func:detectEditIntent(messages: Array<{ content?: unknown; text?: string }>) → boolean, call:messages.map(extractTextFromMessage).join, call:detectEditIntentFromText, func:detectArchitectureSensitiveReasoning(messages: Array<{ content?: unknown; text?: string }>) → boolean, call:messages.map(extractTextFromMessage).join, call:detectArchitectureSensitiveReasoningFromText, func:getRootPairMtimes(cwd: string) → RootPairMtimes, call:join, call:statSync, func:rootPairChanged(current: RootPairMtimes, previous: RootPairMtimes) → boolean, func:buildRootPairBlock(indexContent: string, mapContent: string) → string, call:[ ROOT_PAIR_START_MARKER, "## Project Map Protocol", "", "1. Read this protocol and the root `.pi-map.index.md` first.", "", TRUST_BOUNDARY_TEXT, "", "### Root index", indexContent, "", "### Root map", mapContent, ROOT_PAIR_END_MARKER, ].join, func:hasRootPairMarker(content: string) → boolean, call:content.includes, func:buildPreInitHint() → string, call:[ "📋 Project maps not initialized.", "", "The project-map extension is active. Run `project_map_init` to generate paired `.pi-map.md` and `.pi-map.index.md` artifacts for this project.", "After init, the root pair will be preloaded automatically (default mode: strong). Source remains the final authority before edits.", ].join, func:computeInjectionBudget(config: Pick, contextWindow: number) → number, call:Math.floor, call:Math.min, func:modeAllowsPreInitHint(mode: PromptInjectionMode) → boolean, func:modeAllowsInjection(mode: PromptInjectionMode) → boolean, func:modeRequiresProtocolPath(mode: PromptInjectionMode) → boolean, func:hasProtocolPath(messages: Array<{ content?: unknown; text?: string }>, payload: unknown) → boolean, call:sources.push, call:extractTextFromMessage, call:extractTextFromPayload, call:sources.join, call:combined.includes, func:isSensitiveAction(eventType: string, messages: Array<{ content?: unknown; text?: string }>, payload: unknown) → boolean, call:explicit.includes, call:messages.map(extractTextFromMessage).join, call:extractTextFromPayload, call:`${messageText}\n${payloadText}`.trim, call:detectEditIntentFromText, call:detectArchitectureSensitiveReasoningFromText, func:messagesHaveBypass(messages: Array<{ content?: unknown; text?: string }>, payload: unknown) → boolean, call:extractBypassReason, func:extractBypassReason(messages: Array<{ content?: unknown; text?: string }>, payload: unknown) → string | undefined, call:parts.push, call:messages.map(extractTextFromMessage).join, call:extractTextFromPayload, call:parts.join, call:BYPASS_MARKER_PREFIX.replace, call:new RegExp(`${escapedPrefix}\\s*([^\\]]+)\\]`).exec, call:match[1].trim, func:evaluateStrictBypass(event: | { messages?: Array<{ content?: unknown; text?: string }>; type?: string; payload?: unknown; } | undefined | null, mode: PromptInjectionMode) → StrictBypassDecision, call:isSensitiveAction, call:extractBypassReason, call:hasProtocolPath, func:buildAdvisoryReminder() → string, call:[ "📋 Project map advisory mode active.", "", "Root `.pi-map.index.md` and `.pi-map.md` are available but are not automatically injected. Read them manually when you need routing or orientation context, and remember that source remains the final authority before edits.", ].join, func:buildStrictBypassGuard(reason: string) → string, call:[ "🛑 Strict project-map guard", "", reason || "A sensitive action was detected without the project-map protocol path.", "", "The protocol path requires the root `.pi-map.index.md` / `.pi-map.md` pair plus the trust boundary (`index routes, map orients, source decides`) to be present in context.", "", "To proceed, either restore the project-map context or include an explicit bypass marker: `[PI_MAP_BYPASS: ]`.", ].join, func:discoverContextWindow(ctx: any) → number | undefined, func:estimateTokens(text: string) → number, call:Math.ceil, func:findAllArtifactPairs(cwd: string) → ArtifactPair[], call:readdirSync, call:entry.isDirectory, call:entry.name.startsWith, call:walk, call:join, call:statSync, call:results.push, call:relative, call:results.sort, call:a.dir.split, call:b.dir.split, call:a.dir.localeCompare, func:buildInjectionPayload(cwd: string, config: Pick, contextWindow: number | undefined) → { content: string; display: false }, call:computeInjectionBudget, call:findAllArtifactPairs, call:pairs.findIndex, call:pairs.splice, call:parts.push, call:estimateTokens, call:readFileSync, call:join, call:buildRootPairBlock, call:parts.join | dep: fs, path, ./config.js +- retrieve.ts | Retrieves and ranks directory context artifacts based on a query string, returning a formatted context bundle of the top-K matching directories. | exp: RetrieveContextOptions, func:retrieveContext(query: string, rootPath: string, opts: RetrieveContextOptions) → string, call:collectCandidates, call:normalizeTerms, call:candidates .map((model) => ({ model, score: scoreDirectory(model, queryTerms), })) .filter((c) => c.score > 0) .sort((a, b) => b.score - a.score) .slice, call:scoreDirectory, call:renderNoResultsBundle, call:renderContextBundle, call:scored.map | dep: fs, path, ./format.js, ./directory-model.js +- routing-metadata.ts | Generates routing metadata (tags, symbols, workflow hints) for directory artifacts by analyzing file contents, exports, dependencies, and structure. | exp: func:populateRoutingMetadata(model: DirectoryArtifactModel, opts: RoutingMetadataOptions) → void, call:generateTags, call:generateSymbols, call:generateWorkflows | dep: ./directory-model.js +- validate.ts | Validates project directory maps and indexes against actual filesystem state, detecting discrepancies and optionally repairing them using an LLM client. | exp: ValidationResult, ValidationOptions, Discrepancy, func:validateMaps(rootPath: string, options: ValidationOptions) → Promise, call:resolve, call:discoverProject, call:loadConfig, call:buildDirectoryContext, call:join, call:ctx.parentMap.get, call:[ ...(ctx.childrenMap.get(entry.relativePath) ?? []), ].sort, call:ctx.childrenMap.get, call:discrepancies.push, call:markRepairMode, call:existsSync, call:readFileSync, call:parseDirectoryMap, call:parseDirectoryIndex, call:structuralFlag, call:mapText.includes, call:indexText.includes, call:mapData.files.map, call:indexData.files.map, call:mapFiles.has, call:indexFiles.has, call:actualFiles.has, call:sameStringArrays, call:expectedChildren.join, call:sameWorkflowShapes, call:collectWorkflowTargets, call:targetExists, call:extractFileAST, call:normalizeListedExports, call:actualExports.has, call:listedExports.has, call:entries.find, call:addRepairChain, call:Array.from(repairPlan.entries()).sort, call:repairPlan.entries, call:depthOfPath, call:generateDirectoryArtifacts, call:console.log, raise:Error | dep: fs, path, ./discover.js, ./format.js, ./ast/ast-extract.js, ./init.js, ./llm/llm-client.js, ./config.js, ./patch.js +## arch +Modular pipeline architecture with file system discovery, LLM/AST hybrid metadata extraction, markdown-based serialization, and retrieval-augmented context injection for AI assistants. +## tags +directory, map, project, js, root, pair, path, sync +## symbols +- loadConfig +- createDirectoryModel +- discoverProject +- renderPackageMap +- parsePackageMap +- renderDirectoryMap +- parseDirectoryMap +- renderDirectoryIndex +## workflows +- change src behavior + read: cli.ts, config.ts, directory-model.ts +- change src CLI + read: cli.ts +- change src config + read: config.ts +- explore src subdirectories + index: src/ast/.pi-map.index.md, src/cli/.pi-map.index.md, src/llm/.pi-map.index.md +## dirty +- diff --git a/src/ast/.pi-map.index.md b/src/ast/.pi-map.index.md new file mode 100644 index 0000000..e05c9e9 --- /dev/null +++ b/src/ast/.pi-map.index.md @@ -0,0 +1,20 @@ +# src/ast (index) +dir: src/ast + +## role +Extracts structured metadata from source code ASTs across multiple languages to enable code analysis and dependency understanding. +## parent +index: src/.pi-map.index.md +map: src/.pi-map.md +## children +- +## files +- ast-extract.ts +## links +index: src/ast/.pi-map.index.md +map: src/ast/.pi-map.md +## workflows +- change ast behavior + read: ast-extract.ts +## dirty +- diff --git a/src/ast/.pi-map.md b/src/ast/.pi-map.md new file mode 100644 index 0000000..0df7b69 --- /dev/null +++ b/src/ast/.pi-map.md @@ -0,0 +1,27 @@ +# src/ast +dir: src/ast + +index: src/ast/.pi-map.index.md + +## role +Extracts structured metadata from source code ASTs across multiple languages to enable code analysis and dependency understanding. +## files +- ast-extract.ts | Extracts AST-based metadata (exports, dependencies, classes, functions, method calls, and exceptions) from source code files across multiple languages using Tree-sitter parsers. | exp: ASTFileData, func:extractFileAST(filePath: string) → Promise, call:extname(filePath).toLowerCase, call:require, call:parser.setLanguage, call:readFileSync, call:parser.parse, call:extractPythonData, call:extractTypeScriptData, call:extractGoData, call:extractExportsFromTree, call:extractDepsFromTree | dep: fs, path, tree-sitter, tree-sitter-typescript, tree-sitter-python, tree-sitter-go, tree-sitter-rust, tree-sitter-java, tree-sitter-c, tree-sitter-cpp, tree-sitter-ruby +## arch +Language-agnostic parser abstraction using Tree-sitter grammars with unified extraction pipeline for cross-language code analysis. +## tags +tree, sitter, call:extract, data, ast, extract, python, go +## symbols +- extractFileAST +- ASTFileData +- call:extname(filePath).toLowerCase +- call:require +- call:parser.setLanguage +- call:readFileSync +- call:parser.parse +- call:extractPythonData +## workflows +- change ast behavior + read: ast-extract.ts +## dirty +- diff --git a/src/cli/.pi-map.index.md b/src/cli/.pi-map.index.md new file mode 100644 index 0000000..5ce9f7c --- /dev/null +++ b/src/cli/.pi-map.index.md @@ -0,0 +1,22 @@ +# src/cli (index) +dir: src/cli + +## role +Command-line interface entry point for a project mapping tool that manages hierarchical `.pi-map.md` files through generation, patching, validation, and LLM-powered context retrieval. +## parent +index: src/.pi-map.index.md +map: src/.pi-map.md +## children +- +## files +- cli.ts +## links +index: src/cli/.pi-map.index.md +map: src/cli/.pi-map.md +## workflows +- change cli behavior + read: cli.ts +- change cli CLI + read: cli.ts +## dirty +- diff --git a/src/cli/.pi-map.md b/src/cli/.pi-map.md new file mode 100644 index 0000000..2ec7a00 --- /dev/null +++ b/src/cli/.pi-map.md @@ -0,0 +1,22 @@ +# src/cli +dir: src/cli + +index: src/cli/.pi-map.index.md + +## role +Command-line interface entry point for a project mapping tool that manages hierarchical `.pi-map.md` files through generation, patching, validation, and LLM-powered context retrieval. +## files +- cli.ts | CLI entry point for a project mapping tool that generates, patches, validates, and retrieves context from hierarchical `.pi-map.md` files using LLM-powered analysis. | dep: ../init.js, ../patch.js, ../validate.js, ../discover.js, ../retrieve.js, ../llm/llm-client.js, ../config.js, picocolors, process, fs (implied via require) +## arch +Single-file CLI facade with command routing to core engine services, likely using a command pattern or direct service delegation for map lifecycle operations. +## tags +js, cli, llm, entry, point, project, mapping, tool +## symbols +- +## workflows +- change cli behavior + read: cli.ts +- change cli CLI + read: cli.ts +## dirty +- diff --git a/src/llm/.pi-map.index.md b/src/llm/.pi-map.index.md new file mode 100644 index 0000000..1ebc44b --- /dev/null +++ b/src/llm/.pi-map.index.md @@ -0,0 +1,29 @@ +# src/llm (index) +dir: src/llm + +## role +Provides a unified abstraction layer for interacting with multiple LLM providers (OpenAI, Kimi, Pi) with caching, batching, and structured response extraction capabilities. +## parent +index: src/.pi-map.index.md +map: src/.pi-map.md +## children +- +## files +- external-llm-client.ts +- kimi-llm-client.ts +- llm-batch.ts +- llm-cache.ts +- llm-client.ts +- llm-error.ts +- llm-extract.ts +- pi-llm-client.ts +## links +index: src/llm/.pi-map.index.md +map: src/llm/.pi-map.md +## workflows +- change llm behavior + read: external-llm-client.ts, kimi-llm-client.ts, llm-batch.ts +- change llm CLI + read: external-llm-client.ts, kimi-llm-client.ts, llm-client.ts +## dirty +- diff --git a/src/llm/.pi-map.md b/src/llm/.pi-map.md new file mode 100644 index 0000000..4cf40d3 --- /dev/null +++ b/src/llm/.pi-map.md @@ -0,0 +1,36 @@ +# src/llm +dir: src/llm + +index: src/llm/.pi-map.index.md + +## role +Provides a unified abstraction layer for interacting with multiple LLM providers (OpenAI, Kimi, Pi) with caching, batching, and structured response extraction capabilities. +## files +- external-llm-client.ts | Implements an LLM client adapter for OpenAI's API to send code analysis prompts and return structured responses. | exp: class:ExternalLLMClient, method:constructor(options: LLMClientOptions), raise:LLMError, method:complete(prompt: string) → Promise, call:this.client.chat.completions.create, call:response.choices[0]?.message?.content?.trim, raise:LLMError | dep: openai, ./llm-error.js, ./llm-client.js +- kimi-llm-client.ts | Implements an LLM client for the Kimi.com API using an Anthropic-compatible HTTP interface. | exp: class:KimiLLMClient, method:constructor(options: LLMClientOptions), raise:LLMError, method:complete(prompt: string) → Promise, call:fetch, call:JSON.stringify, call:response.text, call:response.json, call:data.content?.[0]?.text?.trim, raise:LLMError, raise:err | dep: ./llm-error.js, ./llm-client.js, llm-error.js, llm-client.js +- llm-batch.ts | Provides batched, concurrent file processing with retry logic and progress callbacks for LLM operations. | exp: BatchOptions, func:withRetry(fn: () => Promise, options: Pick) → Promise, call:fn, call:sleep, raise:lastError, func:processFiles(files: T[], processor: (file: T) => Promise, options: BatchOptions, onProgress: (completed: number, total: number, currentFile: T) => void) → Promise, call:pLimit, call:files.map, call:limit, call:sleep, call:withRetry, call:processor, call:onProgress, call:Promise.all | dep: p-limit, ./llm-error.js +- llm-cache.ts | Provides a persistent file-based caching system for LLM responses keyed by hash, storing results in JSON with atomic writes and automatic directory creation. | exp: func:getCached(hash: string, cacheDir: string) → string | undefined, call:getCachePath, call:loadCache, func:setCached(hash: string, result: string, cacheDir: string) → void, call:getCachePath, call:loadCache, call:Date.now, call:saveCache | dep: fs, path +- llm-client.ts | Factory for creating LLM client instances based on different provider modes (pi, openai, kimi). | exp: LLMClient, LLMClientOptions, func:createLLMClient(mode: "pi" | "openai" | "kimi", options: LLMClientOptions) → LLMClient | dep: ./llm-error.js, ./external-llm-client.js, ./kimi-llm-client.js, ./pi-llm-client.js, LLMError, ExternalLLMClient, KimiLLMClient, PiLLMClient +- llm-error.ts | Defines a custom error class for LLM-related errors with optional cause chaining | exp: class:LLMError, method:constructor(message: string, cause: unknown) +- llm-extract.ts | Extracts structured metadata (purpose, dependencies, concepts) from source files and packages using an LLM client, with binary detection, caching, and context window management. | exp: func:extractFileLLM(filePath: string, client: LLMClient, cacheDir: string) → Promise, call:isBinaryFile, call:readFileSync, call:createHash("sha256").update(content).digest, call:getCached, call:parseFileResponse, call:statSync, call:buildFilePrompt, call:truncateForContext, call:client.complete, call:setCached, raise:LLMError, func:extractPackageLLM(relativePath: string, fileData: { name: string; purpose: string }[], client: LLMClient, _cacheDir: string) → Promise, call:buildPackagePrompt, call:client.complete, call:parsePackageResponse, call:basename, raise:LLMError | dep: fs, crypto, path, ./llm-client.js, ./llm-cache.js, ./llm-error.js +- pi-llm-client.ts | Implements an LLM client adapter that bridges to Pi's internal AI runtime using its built-in `complete()` function | exp: class:PiLLMClient, method:constructor(extensionContext: unknown), method:complete(prompt: string) → Promise, call:ctx.modelRegistry?.get, call:ctx.modelRegistry?.getApiKeyAndHeaders, call:complete, call:Date.now, call:response.content .filter((c: any) => c.type === "text") .map((c: any) => c.text) .join("") .trim, raise:LLMError, raise:err | dep: ./llm-error.js, ./llm-client.js, @mariozechner/pi-ai +## arch +Adapter pattern for provider-specific LLM clients with a factory; decorator/wrapper pattern for cross-cutting concerns (caching, batching, retries, error handling); functional pipeline for file extraction with binary detection and context window management. +## tags +llm, client, js, raise:llmerror, cache, llmclient, error, constructor +## symbols +- ExternalLLMClient +- KimiLLMClient +- LLMError +- PiLLMClient +- constructor +- complete +- withRetry +- processFiles +## workflows +- change llm behavior + read: external-llm-client.ts, kimi-llm-client.ts, llm-batch.ts +- change llm CLI + read: external-llm-client.ts, kimi-llm-client.ts, llm-client.ts +## dirty +- diff --git a/src/types/.pi-map.index.md b/src/types/.pi-map.index.md new file mode 100644 index 0000000..9046707 --- /dev/null +++ b/src/types/.pi-map.index.md @@ -0,0 +1,20 @@ +# src/types (index) +dir: src/types + +## role +Provides TypeScript type declarations for the Pi AI module's LLM chat completion functionality within the Pi runtime. +## parent +index: src/.pi-map.index.md +map: src/.pi-map.md +## children +- +## files +- pi-ai.d.ts +## links +index: src/types/.pi-map.index.md +map: src/types/.pi-map.md +## workflows +- change types behavior + read: pi-ai.d.ts +## dirty +- diff --git a/src/types/.pi-map.md b/src/types/.pi-map.md new file mode 100644 index 0000000..a97b4bc --- /dev/null +++ b/src/types/.pi-map.md @@ -0,0 +1,20 @@ +# src/types +dir: src/types + +index: src/types/.pi-map.index.md + +## role +Provides TypeScript type declarations for the Pi AI module's LLM chat completion functionality within the Pi runtime. +## files +- pi-ai.d.ts | TypeScript declaration file for the Pi AI module's `complete` function that provides LLM chat completions within the Pi runtime | exp: complete +## arch +Minimal declaration-only types package using ambient module declarations (.d.ts) to define external API interfaces without implementation. +## tags +complete, pi, ai.d, typescript, declaration, provides, llm, chat +## symbols +- complete +## workflows +- change types behavior + read: pi-ai.d.ts +## dirty +- diff --git a/tests/.pi-map.index.md b/tests/.pi-map.index.md new file mode 100644 index 0000000..a5a39cc --- /dev/null +++ b/tests/.pi-map.index.md @@ -0,0 +1,37 @@ +# tests (index) +dir: tests + +## role +Comprehensive test suite for a project mapping tool that generates AI-readable codebase documentation with LLM integration, caching, and CLI query capabilities. +## parent +index: ./.pi-map.index.md +map: ./.pi-map.md +## children +- +## files +- ast-extract.test.ts +- cli.test.ts +- format.test.ts +- integration.test.ts +- llm-batch.test.ts +- llm-cache.test.ts +- llm-extract.test.ts +- llm-integration.test.ts +- merge.test.ts +- mock-llm.ts +- pi-extension.test.ts +- prompt-injection.test.ts +- retrieve.test.ts +- routing-metadata.test.ts +## links +index: tests/.pi-map.index.md +map: tests/.pi-map.md +## workflows +- change tests behavior + read: mock-llm.ts +- update tests tests + read: ast-extract.test.ts, cli.test.ts, format.test.ts +- change tests CLI + read: cli.test.ts +## dirty +- diff --git a/tests/.pi-map.md b/tests/.pi-map.md new file mode 100644 index 0000000..40a1f1b --- /dev/null +++ b/tests/.pi-map.md @@ -0,0 +1,38 @@ +# tests +dir: tests + +index: tests/.pi-map.index.md + +## role +Comprehensive test suite for a project mapping tool that generates AI-readable codebase documentation with LLM integration, caching, and CLI query capabilities. +## files +- ast-extract.test.ts | Tests AST extraction of TypeScript exports, imports, and dependency resolution with fallback for unsupported file types | dep: vitest, ../src/ast/ast-extract.js, fs, path, os, ast-extract.js +- cli.test.ts | Integration tests for a CLI tool that queries project context bundles from `.pi-map.md` and `.pi-map.index.md` files | dep: vitest, fs, path, os, child_process, url +- format.test.ts | Tests markdown rendering and parsing functions for package maps, directory maps, and directory indexes in a project mapping tool. | dep: vitest, ../src/format.js, ../src/directory-model.js +- integration.test.ts | Integration tests for a project mapping tool that generates and maintains .pi-map.md and .pi-map.index.md files across a codebase. | dep: vitest, fs, path, os, ../src/init.js, ../src/patch.js, ../src/validate.js, ./mock-llm.js, ../src/format.js +- llm-batch.test.ts | Unit tests for retry and batch processing utilities in an LLM module | dep: vitest, ../src/llm/llm-batch.js, ../src/llm-error.js +- llm-cache.test.ts | Tests a file-based caching system for LLM responses with get/set operations and cleanup. | dep: vitest, ../src/llm/llm-cache.js, fs, path, os +- llm-extract.test.ts | Unit tests for LLM-based file extraction with mock client, testing file size limits, binary detection, and response parsing | dep: vitest, ../src/llm/llm-extract.js, fs, path, os, ../src/llm/llm-client.js +- llm-integration.test.ts | Integration tests for LLM client functionality including Kimi API calls, file/package extraction, caching, parallel processing, and error handling | dep: vitest, fs, path, os, ../src/llm/llm-client.js, ../src/llm/llm-extract.js, ../src/llm/llm-batch.js, llm-client, llm-extract, llm-batch +- merge.test.ts | Tests that mergeFileData normalizes multi-line function/method parameters and return types into single-line export signatures | dep: vitest, ../src/merge.js +- mock-llm.ts | Provides mock LLM client implementations for testing purposes | exp: func:createMockFileClient(purpose) → LLMClient, func:createMockPackageClient() → LLMClient | dep: ../src/llm/llm-client.js, llm-client.js +- pi-extension.test.ts | Tests a Pi coding agent extension that manages project map initialization, patching, validation, reinitialization, and context retrieval with configurable prompt injection modes. | dep: vitest, fs, path, os, ../src/prompt-injection.js, ../pi-extension.js, @mariozechner/pi-coding-agent, @mariozechner/pi-ai, typebox +- prompt-injection.test.ts | Tests a prompt injection mitigation system that manages root-pair markers, context budgets, mode-based injection policies, and bypass detection for LLM interactions. | dep: vitest, fs, path, os, ../src/prompt-injection.js +- retrieve.test.ts | Tests the `retrieveContext` function that searches and ranks project map files to build context bundles for AI queries. | dep: vitest, fs, path, os, ../src/retrieve.js +- routing-metadata.test.ts | Tests the `populateRoutingMetadata` function which generates tags, symbols, and workflow hints from directory models for code navigation/routing purposes | dep: vitest, ../src/directory-model.js, ../src/routing-metadata.js +## arch +Layered testing architecture with unit, integration, and mock layers; uses file-based fixtures, mock LLM clients, and tests across AST extraction, LLM batching/caching, markdown rendering, context retrieval, and prompt injection security. +## tags +llm, js, src, tests, vitest, client, fs, path +## symbols +- createMockFileClient +- createMockPackageClient +## workflows +- change tests behavior + read: mock-llm.ts +- update tests tests + read: ast-extract.test.ts, cli.test.ts, format.test.ts +- change tests CLI + read: cli.test.ts +## dirty +-