From 3e7410b6bdcd4def9a38f527254c103c46dc9607 Mon Sep 17 00:00:00 2001 From: Developer Date: Tue, 16 Jun 2026 14:38:42 +0000 Subject: [PATCH] chore: track .pi-map.md and .pi-map.index.md artifacts Remove the map files from .gitignore so they are committed as project navigation artifacts, and also unignore them in the sample fixture. Regenerate all maps so the committed versions reflect the current source. --- .atl/.pi-map.index.md | 18 ++++++ .atl/.pi-map.md | 18 ++++++ .gitignore | 2 - .pi-map.index.md | 61 +++++++++++++++++++ .pi-map.md | 48 +++++++++++++++ fixtures/.pi-map.index.md | 20 ++++++ fixtures/.pi-map.md | 18 ++++++ fixtures/sample-project/.gitignore | 1 - fixtures/sample-project/.pi-map.index.md | 30 +++++++++ fixtures/sample-project/.pi-map.md | 22 +++++++ fixtures/sample-project/docs/.pi-map.index.md | 19 ++++++ fixtures/sample-project/docs/.pi-map.md | 19 ++++++ fixtures/sample-project/src/.pi-map.index.md | 30 +++++++++ fixtures/sample-project/src/.pi-map.md | 26 ++++++++ .../src/components/.pi-map.index.md | 21 +++++++ .../sample-project/src/components/.pi-map.md | 26 ++++++++ .../src/models/.pi-map.index.md | 20 ++++++ fixtures/sample-project/src/models/.pi-map.md | 26 ++++++++ .../sample-project/src/utils/.pi-map.index.md | 21 +++++++ fixtures/sample-project/src/utils/.pi-map.md | 28 +++++++++ .../sample-project/tests/.pi-map.index.md | 21 +++++++ fixtures/sample-project/tests/.pi-map.md | 21 +++++++ openspec/.pi-map.index.md | 22 +++++++ openspec/.pi-map.md | 20 ++++++ openspec/changes/.pi-map.index.md | 20 ++++++ openspec/changes/.pi-map.md | 18 ++++++ openspec/changes/archive/.pi-map.index.md | 26 ++++++++ openspec/changes/archive/.pi-map.md | 18 ++++++ .../.pi-map.index.md | 26 ++++++++ .../.pi-map.md | 26 ++++++++ .../.pi-map.index.md | 26 ++++++++ .../.pi-map.md | 26 ++++++++ .../.pi-map.index.md | 26 ++++++++ .../.pi-map.md | 26 ++++++++ src/.pi-map.index.md | 49 +++++++++++++++ src/.pi-map.md | 45 ++++++++++++++ src/ast/.pi-map.index.md | 20 ++++++ src/ast/.pi-map.md | 27 ++++++++ src/cli/.pi-map.index.md | 22 +++++++ src/cli/.pi-map.md | 22 +++++++ src/llm/.pi-map.index.md | 29 +++++++++ src/llm/.pi-map.md | 36 +++++++++++ src/types/.pi-map.index.md | 20 ++++++ src/types/.pi-map.md | 20 ++++++ tests/.pi-map.index.md | 37 +++++++++++ tests/.pi-map.md | 38 ++++++++++++ 46 files changed, 1158 insertions(+), 3 deletions(-) create mode 100644 .atl/.pi-map.index.md create mode 100644 .atl/.pi-map.md create mode 100644 .pi-map.index.md create mode 100644 .pi-map.md create mode 100644 fixtures/.pi-map.index.md create mode 100644 fixtures/.pi-map.md create mode 100644 fixtures/sample-project/.pi-map.index.md create mode 100644 fixtures/sample-project/.pi-map.md create mode 100644 fixtures/sample-project/docs/.pi-map.index.md create mode 100644 fixtures/sample-project/docs/.pi-map.md create mode 100644 fixtures/sample-project/src/.pi-map.index.md create mode 100644 fixtures/sample-project/src/.pi-map.md create mode 100644 fixtures/sample-project/src/components/.pi-map.index.md create mode 100644 fixtures/sample-project/src/components/.pi-map.md create mode 100644 fixtures/sample-project/src/models/.pi-map.index.md create mode 100644 fixtures/sample-project/src/models/.pi-map.md create mode 100644 fixtures/sample-project/src/utils/.pi-map.index.md create mode 100644 fixtures/sample-project/src/utils/.pi-map.md create mode 100644 fixtures/sample-project/tests/.pi-map.index.md create mode 100644 fixtures/sample-project/tests/.pi-map.md create mode 100644 openspec/.pi-map.index.md create mode 100644 openspec/.pi-map.md create mode 100644 openspec/changes/.pi-map.index.md create mode 100644 openspec/changes/.pi-map.md create mode 100644 openspec/changes/archive/.pi-map.index.md create mode 100644 openspec/changes/archive/.pi-map.md create mode 100644 openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.index.md create mode 100644 openspec/changes/archive/2026-06-11-layered-map-protocol/.pi-map.md create mode 100644 openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.index.md create mode 100644 openspec/changes/archive/2026-06-11-map-context-retrieval/.pi-map.md create mode 100644 openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.index.md create mode 100644 openspec/changes/archive/2026-06-11-project-map-prompt-injection/.pi-map.md create mode 100644 src/.pi-map.index.md create mode 100644 src/.pi-map.md create mode 100644 src/ast/.pi-map.index.md create mode 100644 src/ast/.pi-map.md create mode 100644 src/cli/.pi-map.index.md create mode 100644 src/cli/.pi-map.md create mode 100644 src/llm/.pi-map.index.md create mode 100644 src/llm/.pi-map.md create mode 100644 src/types/.pi-map.index.md create mode 100644 src/types/.pi-map.md create mode 100644 tests/.pi-map.index.md create mode 100644 tests/.pi-map.md 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 +-