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.
This commit is contained in:
Developer
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -4,8 +4,6 @@ coverage/
|
|||||||
*.log
|
*.log
|
||||||
.DS_Store
|
.DS_Store
|
||||||
.env
|
.env
|
||||||
.pi-map.md
|
|
||||||
.pi-map.index.md
|
|
||||||
# Local Pi runtime state
|
# Local Pi runtime state
|
||||||
.atl/
|
.atl/
|
||||||
.pi
|
.pi
|
||||||
|
|||||||
@@ -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
|
||||||
|
-
|
||||||
+48
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -1,4 +1,3 @@
|
|||||||
dist/
|
dist/
|
||||||
node_modules/
|
node_modules/
|
||||||
.pi-map.md
|
|
||||||
.env
|
.env
|
||||||
|
|||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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, "id" | "createdAt">) → 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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
File diff suppressed because one or more lines are too long
@@ -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
|
||||||
|
-
|
||||||
@@ -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<ASTFileData | null>, 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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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<string>, 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<string>, 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<T>, options: Pick<BatchOptions, "maxRetries" | "retryDelaysMs">) → Promise<T>, call:fn, call:sleep, raise:lastError, func:processFiles(files: T[], processor: (file: T) => Promise<R>, options: BatchOptions, onProgress: (completed: number, total: number, currentFile: T) => void) → Promise<R[]>, 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<LLMFileData>, 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<LLMPackageData>, 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<string>, 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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
@@ -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
|
||||||
|
-
|
||||||
Reference in New Issue
Block a user