dsh-project-compass
Project Compass is a zero-dependency DSH plugin that statically scans a codebase to generate evidence-cited architecture and onboarding docs, plus offline extractive Q&A by default.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/lpeixin--dsh-project-compass)HTML
<a href="/listings/lpeixin--dsh-project-compass"><img src="/api/listings/lpeixin--dsh-project-compass/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requirements
| Item | Requirement | | --- | --- | | Node.js | ≥ 20.11 (built-in `node:test` / `TextDecoder` / `fs/promises`) | | DSH | Any version that supports Cordis plugins and the `dsh.bundle.patch` contract | | Dependencies | None. This plugin has zero external dependencies: clone it and it runs, with no build step |
Install through the plugin manager
In the GUI, ask the agent to run `install_bundle` with this spec:
file:/absolute/path/to/dsh-project-compass
This writes the bundle and the dependency into the profile's `bundles` / `dependencies`.
> The path is installed by pnpm as a **`file:` dependency**. If your package manager materializes it as hard links, > the installed copy can still hold the old content after repository files are replaced by "write + rename" — > after changing code, reinstall once to be sure.
Manual install for local development (symlink the repository into the profile)
ln -s "$PWD" ~/.dsh/profiles/desktop/node_modules/dsh-project-compass
> `desktop` is the profile name; substitute the profile you actually use. On Windows, use `mklink /D` or copy the > directory instead.
Then append to `~/.dsh/profiles/desktop/cordis.patch.yml`:
- insert:
- id: project-compass
name: 'dsh-project-compass'Restart or reload DSH and run `/compass status` in a session; if it lists a status, the installation works.
Temporarily disabling it (without uninstalling)
- id: project-compass disabled: true
In-repo self-test (no DSH required)
This plugin ships a command-line channel that does not depend on the host process, so every capability can be run in a plain Node environment:
node --test # unit tests (all green means pass) node scripts/compass-cli.mjs analyze <path/to/project> # scan + parse + IR + dependency graph node scripts/compass-cli.mjs report <path/to/project> # generate the 6 artifacts node scripts/compass-cli.mjs ask <path/to/project> "登录流程经过哪些模块?" node scripts/compass-cli.mjs status <path/to/project> # current status and cache size
Replace `<path/to/project>` with the absolute path of any real project. All of this only reads your project's source code; writes happen only inside that project's `.project-compass/` and `docs/project-compass/`.
> `scripts/compass-cli.mjs` is the in-repo self-test entry point and the channel used by CI and regression runs. > It goes through **the same implementation path** as the DSH tools (`lib/pipeline.js`); the only difference is that > it does not pass through the host, so the `llm.*` enhancements are unavailable (degrading as "no LLM service in > the host").
---
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 476 lines
- **English** | [中文](README.zh-CN.md)
- <img src="assets/banner.png" alt="Project Compass — understand any codebase in 10 minutes, with evidence not guesses" width="1280">
- # dsh-project-compass · Project Compass 项目罗盘
- **Codebase reconnaissance and citation-backed Q&A for DeepSeek Harness.**
- **Project Compass reads an existing project and turns "how is this thing put together" into a set of evidence-cited documents, plus a question-answering interface you can keep asking.**
- It does not require you to get the project running first, does not require you to read all the code, and does not go online.
- Give it a path and it returns six artifacts: an onboarding guide, an architecture description, a module map,
- the key flows, the steps to get it running, and a machine-readable JSON.
- ---
- > **Documentation language.** The detailed documents under `docs/` — [TOOLS](docs/TOOLS.md), [CONFIG](docs/CONFIG.md),
- > [OUTPUT-FORMAT](docs/OUTPUT-FORMAT.md), [ARCHITECTURE](docs/ARCHITECTURE.md), [ROADMAP](docs/ROADMAP.md) and
- > [VERIFICATION](docs/VERIFICATION.md) — are currently written in Chinese. If you need English versions,
- > please raise it in an [issue](https://github.com/lpeixin/dsh-project-compass/issues).
- ---
- ## Table of contents
- - [What problem it solves](#what-problem-it-solves)
- - [Output artifacts](#output-artifacts)
- - [Capability matrix](#capability-matrix)
- - [Installation](#installation)
- - [Quick start](#quick-start)
- - [Configuration](#configuration)
- - [Tools and command reference](#tools-and-command-reference)
- - [How it works: the six-step pipeline](#how-it-works-the-six-step-pipeline)
- - [Privacy and security](#privacy-and-security)
- - [How it integrates with DSH](#how-it-integrates-with-dsh)
- - [Development and testing](#development-and-testing)
- - [License](#license)
- ---
- ## What problem it solves
- When you take over an unfamiliar codebase, the expensive part is not reading code — it is **not knowing where to
- start reading, and not knowing what will break when you change something.**
- | Situation | What it used to cost | What Project Compass gives you |
- | --- | --- | --- |
- | **New developer onboarding** | A colleague explains verbally for two hours, and afterwards you still don't know where the entry point is; the README was last updated three years ago | `GETTING_STARTED.md` gives runnable steps to get up and running, `ONBOARDING.md` gives a reading order arranged by role, and every item carries `path:line` so you can jump straight into the code |
- | **Inheriting a legacy project** | No documentation, the original owner has left, and changing one line feels like a three-day risk | `ARCHITECTURE.md` + `MODULE_MAP.md` give module boundaries, dependency direction, cycles and high-risk modules; risks come with reasons, not with feelings |
- | **A tech lead reviewing a change** | "How big is the blast radius of this change?" can only be guessed from experience | A module / file / symbol three-level dependency graph plus reachability from entry points, so blast radius is something you look at rather than guess at; key flows come with Mermaid sequence diagrams |
- | **An AI agent that needs project context** | Every turn re-greps, the context fills up with scattered fragments, and it still invents files that do not exist | `project_compass_ask` returns answers with `citations` (`path:line` + symbol + rationale); every claim passes a validator first — paths, line numbers and symbols must really exist, and claims that fail validation are explicitly dropped and counted |
- In one sentence: **it turns "understanding a project" from oral tradition into an artifact that is reproducible,
- reviewable and diffable.**
- ---
- ## Output artifacts
- `project_compass_report` generates 6 artifacts in one pass, written by default to `<project>/docs/project-compass/`:
- | Artifact | Audience | Content |
- | --- | --- | --- |
- | `ONBOARDING.md` | Newcomers / people taking over | Project overview, reading routes and checklists by role (backend / frontend / test / devops / data), terminology and conventions, common pitfalls |
- | `ARCHITECTURE.md` | Tech leads / architecture review | Module layering diagram (Mermaid), dependency direction, cycles, hub modules, high-risk modules with the reasons behind their scores |
- | `MODULE_MAP.md` | All developers | Per-module responsibility, file list, lines of code, public surface, dependencies and dependents, risk level |
- | `KEY_FLOWS.md` | Debugging / change assessment | Key flows starting from HTTP routes, CLI entry points and event entry points, step by step + Mermaid sequence diagrams + evidence |
- | `GETTING_STARTED.md` | Everyone | Environment requirements, install / build / test / start commands (with the source of each command), common failures and how to diagnose them |
- | `project-compass.json` | CI / other tooling | An IR summary view: modules, dependencies, routes, risks, statistics and metadata, with a `schemaVersion` for programmatic consumption |
- > **This repository does not commit its own generated artifacts.** `docs/project-compass/` is ignored via
- > [`.gitignore`](.gitignore): the reports are generated output, they go stale the moment the code changes, and they
- > weigh close to 500 KB — while being trivially reproducible. To generate the example yourself, run:
- >
- > ```bash
- > node scripts/compass-cli.mjs analyze . && node scripts/compass-cli.mjs report .
- > ```
- > The excerpts below are **illustrative excerpts (not real output)**, meant to show what the artifacts look like and
- > how specific the format is. The actual content is determined by your own scan of your own project.
- > (Reports are currently rendered in Chinese; the excerpts keep that real format.)
- ```markdown
- <!-- Illustrative excerpt (not real output): ONBOARDING.md fragment -->
- # ONBOARDING · example-shop 上手报告
- > **生成时间**:2026-10-02T09:12:44.108Z | **项目**:`example-shop` | **工具版本**:dsh-project-compass@0.1.0
- > **证据口径**:所有结论均标注静态证据:`path:line` 或 `path#symbol`;……无证据的推断显式标注"未验证"。
- > **LLM 参与**:否 —— 本报告全部结论来自静态证据,未调用 LLM
- ## 6. 按角色阅读路线
- | 角色 | 关注点 | 推荐阅读路线 | 检查清单 |
- | --- | --- | --- | --- |
- | 后端 | HTTP/CLI 入口、路由与处理函数、服务与数据访问层 | 1. 阅读入口(http-server)(`src/server.ts:24`)<br>2. 路由集中模块 src/api(12 条路由)(`src/api/orders.ts:41`) | - 确认全部 HTTP 路由与中间件(IR 记录 26 条)<br>- 确认模块依赖方向单一、无环 |
- ```
- ````markdown
- <!-- Illustrative excerpt (not real output): ARCHITECTURE.md fragment -->
- # ARCHITECTURE · example-shop 架构说明
- ## 1. 分层架构总览
- ```mermaid
- graph LR
- api["src/api"]
- domain["src/domain"]
- infra["src/infra"]
- api --> domain
- domain --> infra
- infra --> api
- ```
- ## 4. 循环依赖与高风险模块
- - 循环依赖:`src/api` → `src/domain` → `src/infra` → `src/api`
- 证据:`src/api/orders.ts:5`、`src/domain/order.ts:2`、`src/infra/db.ts:3`
- - 高风险模块:`src/infra`(评分 72;理由:fanIn=11、被 4 个模块依赖、位于循环依赖中)
- ````
- ```jsonc
- // Illustrative excerpt (not real output): project-compass.json fragment
- {
- "schemaVersion": 1,
- "generatedAt": "2026-10-02T09:12:44.108Z",
- "tool": { "name": "dsh-project-compass", "version": "0.1.0" },
- "project": {
- "name": "example-shop",
- "kinds": ["api-service"],
- "size": { "files": 213, "sourceFiles": 198, "modules": 14, "symbols": 1480, "routes": 26, "flows": 9 }
- },
- "graph": {
- "hubs": [{ "id": "src/infra", "fanIn": 11, "fanOut": 2 }],
- "cycles": [["src/api", "src/domain", "src/infra"]],
- "riskModules": [{ "id": "src/infra", "score": 72, "reasons": ["fanIn=11", "位于循环依赖中"] }]
- },
- "risks": { "count": 3, "signals": { "todoCount": 17 } },
- "evidence": { "validation": { "droppedCount": 0 }, "warnings": [] }
- }
- ```
- > All three excerpts above are **illustrative** (the structure matches the real artifacts, the numbers and content
- > have nothing to do with any real project); they exist to show what the artifacts look like and how specific the
- > format is. The complete field reference is in [docs/OUTPUT-FORMAT.md](docs/OUTPUT-FORMAT.md).
- ---
- ## Capability matrix
- The table below maps one-to-one onto the 12 functional requirements in the requirements document (FR1–FR12).
- **This version still targets full FR1–FR12 coverage**, of which 10 items are fully implemented,
- **1 is implemented in a way that differs from the requirement text (FR2)**, and
- **1 is limited by host capability (streaming progress in FR10)** — the differences are stated in the table
- rather than smoothed over.
- | FR | Requirement | What this plugin actually does | Status |
- | --- | --- | --- | --- |
- | FR1 | Project scan: scan the root directory, apply ignore rules, identify languages, frameworks, entry points, configuration | Same, plus sensitive-file registration (path only, contents never read), risk signals and engineering gaps | Implemented in this version |
- | FR2 | Multi-language AST parsing: parse TS/JS, Python, Java with Tree-sitter; extract symbols, imports, calls, routes | **Deviation**: Tree-sitter is not used (the host and the repository convention are zero external dependencies, so the dependency is not available); replaced by a purpose-built zero-dependency lexical / structural extractor. Language coverage is unchanged | Implemented in this version (**different implementation**) |
- | FR3 | Unified IR: Project / Module / File / Symbol / Import / Call / Route | Same, and it carries `schemaVersion`, statistics, warnings and budget | Implemented in this version |
- | FR4 | Dependency graph: module level, file level, symbol level | Same, plus fan-in/fan-out, hubs, orphans, entry-point reachability, cycle detection and risk scoring | Implemented in this version |
- | FR5 | Incremental cache: content-hash-based caching of AST, IR, graph, summaries, embeddings | **Precise scope**: content-hash caching applies to per-file parse results; the IR and the graph are recomputed in memory from those cached results (milliseconds, hence not persisted); the retrieval index supports incremental updates for changed files | Implemented in this version (**see the note on cache granularity**) |
- | FR6 | LLM summarization and validation: generate summaries from facts, validate entities, paths, line numbers | Same, off by default; every claim goes through the validator, and anything that fails is dropped and counted | Implemented in this version |
- | FR7 | RAG index and Q&A: chunking, embeddings, hybrid retrieval, reranking, citation-backed answers | Same; embeddings are local deterministic vectors (no network, no model files) | Implemented in this version |
- | FR8 | Report generation: Markdown + Mermaid + JSON | Same, producing 6 artifacts; plus per-role reading routes | Implemented in this version |
- | FR9 | DSH tool registration: register analyze / report / ask / update / status tools and commands | Same; 6 tools in fact (including `project_compass_scan`) + the `/compass` command + an embedded methodology skill | Implemented in this version |
- | FR10 | Configuration and progress: configuration, budget, concurrency, ignore rules, streaming progress | Configuration / budget / concurrency / ignore rules are all implemented; `analyze` already has an internal `onProgress({phase,done,total,message})` callback. **Streaming progress is limited by host capability**: `ToolDefinition` provides no progress channel at all (only `deferContext` / `concludeTurn`), and the event table has no emittable event such as `tool/progress`, so the plugin side cannot surface in-flight progress to the GUI | **Partially implemented (host limitation, not an implementation gap)** |
- | FR11 | Multi-role reports: reading routes for backend / frontend / test / devops | Same; in fact five roles — backend / frontend / test / devops / data — derived from IR evidence, with roles that have no evidence stated as such | Implemented in this version |
- | FR12 | Security and privacy: ignore sensitive files, local first, cloud LLM requires confirmation | Same: sensitive files are never read, nothing goes online by default, and the LLM must be explicitly enabled and consented to | Implemented in this version |
- On the FR5 cache scope: what lands on disk under `.project-compass/cache/` is the **per-file parse result**
- (keyed by content hash); the IR and the dependency graph are rebuilt in memory from those results — both are pure
- computation on the millisecond scale, so they are not persisted separately, which avoids several derived artifacts
- drifting out of sync with each other.
- A few capabilities are not numbered separately in the requirements document but are implemented in this version
- all the same: **key-flow extraction** starting from routes / CLI / event entry points (step-by-step plus Mermaid
- sequence diagrams and confidence), and the in-repo `scripts/compass-cli.mjs` self-test channel — both belong to
- the graph analysis and tool registration in the table above, and do not take a separate number.
- Design discipline (written into the contract and into code review): **better to under-report than to misreport.**
- Line numbers, symbols and paths must be checkable in the IR; conclusions that cannot be checked either do not make
- it into the report or are explicitly marked "unverified".
- ### Two adjustments to §5 of the requirements document ("plugin integration design")
- The skeleton given by the requirements document is TypeScript + `inject = ['fs','llm','tools','logger','storage','workspace']`.
- Under the authorization of that section's final clause — "adjust the integration code to the actual DSH plugin API,
- abstracting an adapter layer where necessary" — this implementation makes two adjustments and states them here:
- 1. **Zero-dependency ESM JavaScript, not TypeScript + npm dependencies.** Reason: the host runtime does not provide
- dependencies such as Tree-sitter, and the convention of the existing plugin in this repository (`dsh-qualityforge`)
- is to "import `node:*` only" — this way there is no build step, and loading cannot fail because of how the
- `@deepseek-ai/*` packages inside the host are resolved or because of a version change.
- 2. **`inject` declares only the real hard dependency, `tools`**; the other services are probed as optional
- capabilities: `ctx.get('commands')` (the `/compass` command), `ctx.get('skills')` (the methodology skill),
- `ctx.get('systemPrompt')` (optional context injection), `ctx.get('llm')` + `agentDefaultModel` (optional narrative
- enhancement). When any of these services is missing the plugin **degrades silently** rather than failing to load —
- it should be usable in any combination.
- ---
- ## Installation
- ### Requirements
- | Item | Requirement |
- | --- | --- |
- | Node.js | ≥ 20.11 (built-in `node:test` / `TextDecoder` / `fs/promises`) |
- | DSH | Any version that supports Cordis plugins and the `dsh.bundle.patch` contract |
- | Dependencies | None. This plugin has zero external dependencies: clone it and it runs, with no build step |
- ### Install through the plugin manager
- In the GUI, ask the agent to run `install_bundle` with this spec:
- ```text
- file:/absolute/path/to/dsh-project-compass
- ```
- This writes the bundle and the dependency into the profile's `bundles` / `dependencies`.
- > The path is installed by pnpm as a **`file:` dependency**. If your package manager materializes it as hard links,
- > the installed copy can still hold the old content after repository files are replaced by "write + rename" —
- > after changing code, reinstall once to be sure.
- ### Manual install for local development (symlink the repository into the profile)
- ```bash
- ln -s "$PWD" ~/.dsh/profiles/desktop/node_modules/dsh-project-compass
- ```
- > `desktop` is the profile name; substitute the profile you actually use. On Windows, use `mklink /D` or copy the
- > directory instead.
- Then append to `~/.dsh/profiles/desktop/cordis.patch.yml`:
- ```yaml
- - insert:
- - id: project-compass
- name: 'dsh-project-compass'
- ```
- Restart or reload DSH and run `/compass status` in a session; if it lists a status, the installation works.
- ### Temporarily disabling it (without uninstalling)
- ```yaml
- - id: project-compass
- disabled: true
- ```
- ### In-repo self-test (no DSH required)
- This plugin ships a command-line channel that does not depend on the host process, so every capability can be run in
- a plain Node environment:
- ```bash
- node --test # unit tests (all green means pass)
- node scripts/compass-cli.mjs analyze <path/to/project> # scan + parse + IR + dependency graph
- node scripts/compass-cli.mjs report <path/to/project> # generate the 6 artifacts
- node scripts/compass-cli.mjs ask <path/to/project> "登录流程经过哪些模块?"
- node scripts/compass-cli.mjs status <path/to/project> # current status and cache size
- ```
- Replace `<path/to/project>` with the absolute path of any real project. All of this only reads your project's source
- code; writes happen only inside that project's `.project-compass/` and `docs/project-compass/`.
- > `scripts/compass-cli.mjs` is the in-repo self-test entry point and the channel used by CI and regression runs.
- > It goes through **the same implementation path** as the DSH tools (`lib/pipeline.js`); the only difference is that
- > it does not pass through the host, so the `llm.*` enhancements are unavailable (degrading as "no LLM service in
- > the host").
- ---
- ## Quick start
- Inside a DSH session (with the working directory set to the target project):
- ```text
- /compass analyze # reconnaissance + parse + build IR + build dependency graph (first run; incremental afterwards)
- /compass report # generate the 6 artifacts into docs/project-compass/
- /compass ask 登录流程经过哪些模块? # citation-backed Q&A, every claim carries path:line
- /compass status # see whether it is analyzed, artifact paths, cache size, suggested next step
- ```
- You can also skip the commands entirely and just tell the agent:
- > Use Project Compass to analyze the current project, generate the onboarding docs, then tell me which modules the
- > authentication flow goes through.
- The agent will call these 6 tools as needed:
- ```text
- project_compass_scan → reconnaissance: directories, languages, entry points, commands, sensitive files, risk signals
- project_compass_analyze → parse + IR + dependency graph (supports incremental / budget / concurrency)
- project_compass_report → generate the 6 artifacts
- project_compass_ask → citation-backed Q&A (local retrieval, no LLM by default)
- project_compass_update → recompute only changed files, refresh IR / index / report
- project_compass_status → current status and suggested next step
- ```
- The typical rhythm: **`analyze` → `report` the first time; `update` after each change; `ask` whenever a question
- comes up.**
- ---
- ## Configuration
- Configuration lives in the profile's `cordis.patch.yml`, addressed by the id `project-compass`:
- ```yaml
- - id: project-compass
- name: dsh-project-compass
- config:
- outputDir: docs/project-compass
- concurrency: 8
- budget:
- maxFiles: 20000
- maxFileBytes: 262144
- maxTotalBytes: 67108864
- maxDurationMs: 600000
- maxChunks: 20000
- ignore: []
- include: []
- sensitive:
- extraPatterns: []
- llm:
- enabled: false
- contextInjection: false
- ```
- | Key | Default | Effect |
- | --- | --- | --- |
- | `outputDir` | `docs/project-compass` | Output directory for the human artifacts (relative to the project root) |
- | `concurrency` | `8` | Parse concurrency; raise it for IO-bound workloads, lower it on spinning disks or when there are many very large files |
- | `budget.*` | see above | Caps on file count / per-file bytes / total bytes / duration / chunk count; exceeding them truncates and tags the result |
- | `ignore` / `include` | `[]` | Additional ignore rules (`.gitignore` syntax, `!` negation supported) and force-include rules |
- | `sensitive.extraPatterns` | `[]` | Additional sensitive-file patterns; matching paths are registered only and their contents are never read |
- | `llm.enabled` | `false` | Whether the LLM may be called to generate narrative (does not change retrieval or fact extraction) |
- | `contextInjection` | `false` | Whether to inject a project brief into the agent's system prompt |
- Per-key details, matching semantics, the default sensitive-file list, tuning for large repos / monorepos and the LLM
- privacy notes are in **[docs/CONFIG.md](docs/CONFIG.md)**.
- > Project-level configuration (letting a repository carry its own preferences) is out of scope for this version;
- > see [docs/ROADMAP.md](docs/ROADMAP.md).
- ---
- ## Tools and command reference
- ### Command: `/compass`
- | Subcommand | Equivalent tool | Description |
- | --- | --- | --- |
- | `/compass analyze` | `project_compass_analyze` | Full or incremental analysis, producing the IR |
- | `/compass report` | `project_compass_report` | Generate the 6 artifacts |
- | `/compass ask <question>` | `project_compass_ask` | Citation-backed Q&A |
- | `/compass update` | `project_compass_update` | Incremental update |
- | `/compass status` | `project_compass_status` | Show status |
- | `/compass help` | — | Quick usage reference |
- ### Tools
- | Tool | In one line | Main parameters | Artifacts |
- | --- | --- | --- | --- |
- | `project_compass_scan` | Reconnoiter the project: languages / frameworks / entry points / commands / sensitive files / gaps | `projectPath` | `.project-compass/scan.json` |
- | `project_compass_analyze` | Scan + parse + unified IR + three-level dependency graph | `projectPath`, `force`, `withLlm`, `maxFiles` | `.project-compass/ir.json` |
- | `project_compass_report` | Generate the 6 artifacts (with Mermaid diagrams and role routes) | `projectPath`, `withLlm` | 6 files under `docs/project-compass/` |
- | `project_compass_ask` | Project-level citation-backed Q&A (local retrieval, extractive by default) | `projectPath`, `question` | Returns `citations` and a confidence level; the Q&A log is kept locally |
- | `project_compass_update` | Recompute only changed files, refresh IR / index / report | `projectPath` | Refreshes the artifacts above |
- | `project_compass_status` | Whether it is analyzed, artifact paths, cache size, last budget, suggested next step | `projectPath` | Returns status only, writes nothing |
- The full parameter tables (name / type / required / default / description), the returned fields, typical call
- sequences and degradation behavior are in **[docs/TOOLS.md](docs/TOOLS.md)**; artifact structure, the citation format
- and the JSON field tables are in **[docs/OUTPUT-FORMAT.md](docs/OUTPUT-FORMAT.md)**.
- ---
- ## How it works: the six-step pipeline
- ```mermaid
- flowchart LR
- A["① Scan<br/>scan"] --> B["② Parse<br/>parse"]
- B --> C["③ Unified IR<br/>ir"]
- C --> D["④ Dependency graph<br/>graph + flows"]
- D --> E["⑤ Retrieval<br/>chunk + embed + rag"]
- E --> F["⑥ Report<br/>report"]
- A -.- A1[".project-compass/scan.json"]
- C -.- C1[".project-compass/ir.json"]
- E -.- E1[".project-compass/index.json"]
- F -.- F1["docs/project-compass/<br/>6 artifacts"]
- E --> G["project_compass_ask<br/>citation-backed Q&A"]
- A --> H["project_compass_status"]
- ```
- | Step | What it does | Key trade-off |
- | --- | --- | --- |
- | ① Scan | Directory traversal, ignore rules, language and framework detection, entry-point and command discovery, sensitive-file registration, risk signals and engineering gaps | Only `stat` sensitive paths, never read them; conclusions come from on-disk evidence, not guesses |
- | ② Parse | Dispatch parsers by language; extract symbols / imports / calls / routes / TODOs with line numbers and ranges | Line/column scanning plus bracket / indentation balancing, no tree-sitter, staying zero-dependency; cross-file resolution is left to the IR layer |
- | ③ Unified IR | Converge the multi-language results into one shape, resolve import specifiers to fileIds, bind calls | Call binding has only four possible conclusions and must record its `resolution`; when it cannot be determined it stays `unresolved`, without guessing |
- | ④ Dependency graph and flows | Build the module / file / symbol three-level graph, compute fan-in/fan-out, cycles, reachability and risk; extract key flows from entries | Entirely deterministic algorithms: the same input necessarily yields the same output, which makes diffing and caching possible |
- | ⑤ Retrieval | Chunking + local deterministic vectors + BM25 → RRF fusion → reranking | The vectors are hashed word vectors plus character trigrams, so no model files and no network are needed — hence reproducible and offline |
- | ⑥ Report | Render the 6 artifacts: Markdown + Mermaid + evidence citations + role routes | Every conclusion carries `path:line`; unverifiable inferences are explicitly marked "unverified"; the LLM only writes narrative and must pass validation |
- **Where incrementality comes from**: every file enters the cache keyed by its content hash. `update` recomputes only
- the files whose hash changed; unchanged files reuse their parse results and index entries directly. So the cost of
- the second and later analyses is roughly proportional to "how much you changed" rather than to the size of the
- repository.
- ---
- ## Privacy and security
- | Boundary | How it is handled |
- | --- | --- |
- | **Local first** | Scanning, parsing, retrieval and Q&A all happen on your machine; the plugin itself **makes no network requests** |
- | **Sensitive files are never read** | When `.env`, private keys, credential files and the like match a sensitive rule, only a `stat` is done to register the path and kind; the contents never enter memory, cache or reports |
- | **LLM off by default** | `llm.enabled: false` is the default. Unless you turn it on explicitly, no code fragment is ever sent to a model |
- | **When the LLM is on** | Only the minimal context needed to generate narrative is sent; the response goes through the validator first (paths / line numbers / symbols must really exist), failing claims are dropped and counted, and the report states how many were dropped |
- | **Write scope** | Only the target project's `.project-compass/` (machine state) and `docs/project-compass/` (human artifacts); no business code is ever modified |
- | **Zero dependency surface** | No npm dependencies, no install scripts, no build output, so there is no supply-chain surface to introduce |
- **The machine-state directory ignores itself.** On first write the plugin drops a `.gitignore` whose rule is `*` into
- `<project>/.project-compass/`, because `scan.json` / `ir.json` / `state.json` record the **absolute project root** —
- that is, your local filesystem layout. `git add .` therefore does not commit it even if you have configured nothing.
- Delete that file if you deliberately want to version the state. It is only written when missing, so it never
- overwrites content of your own.
- The full explanation and the vulnerability reporting process are in **[SECURITY.md](SECURITY.md)**.
- ---
- ## How it integrates with DSH
- - **6 tools** are exposed to the model through Cordis tool registration, with the model-visible names uniformly
- `project_compass_*`;
- - **1 command**, `/compass`, is exposed to humans, its subcommands passing straight through to the corresponding tools;
- - **The plugin entry** has only named exports (`name` / `inject` / `apply`) and no default export;
- - **Host services** are reached only through `ctx.get(...)` (such as the session default model or the LLM service);
- when they are unavailable, the plugin degrades to deterministic output;
- - **`contextInjection`** (default `false`), when enabled, injects a brief about the analyzed project into the agent's
- system prompt, so that later answers in the same session already carry the project context; when disabled,
- everything is triggered on demand.
- ---
- ## Development and testing
- ```bash
- node --test # unit tests, must be all green
- node --test --experimental-test-coverage # coverage
- node scripts/compass-cli.mjs analyze <path/to/project> # smoke test against a real project
- ```
- Hard engineering constraints (read [docs/INTERNAL-CONTRACTS.md](docs/INTERNAL-CONTRACTS.md) before changing code):
- 1. **Zero external dependencies**: only `node:*` built-in modules are allowed;
- 2. **Pure ESM**: `"type": "module"`, and relative imports must carry the `.js` suffix;
- 3. **No default export**: the entry point may only use the named exports `name` / `inject` / `apply`;
- 4. **Fault tolerance first**: parsers, retrievers and report renderers do not throw on malformed input — they
- degrade and write `warnings`;
- 5. **Do not touch the contract**: `docs/INTERNAL-CONTRACTS.md` is the single source of truth for interfaces during
- parallel development; changing the contract means changing it first.
- Architecture, module layering and extension points are in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md); how to
- contribute is in [CONTRIBUTING.md](CONTRIBUTING.md); the change history is in [CHANGELOG.md](CHANGELOG.md).
- ---
- ## License
- [MIT](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.