@mycodemap/mycodemap 2.0.0 → 2.7.0

package/docs/GETTING-STARTED.md

@@ -0,0 +1,114 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Getting Started
+
+## Prerequisites
+
+- Node.js `>= 20.0.0`
+- npm, pnpm, or yarn
+- A repository with source files to analyze
+
+The tool can run without native build toolchains. When native dependencies are unavailable, the runtime falls back to WASM paths.
+
+## Installation
+
+### Install from npm (recommended for users)
+
+```bash
+npm install -g @mycodemap/mycodemap
+```
+
+`mycodemap` is the primary binary. `codemap` is kept as an alias.
+
+### Build from source (for contributors)
+
+```bash
+git clone https://github.com/yuanyuanyuan/mycodemap.git
+cd mycodemap
+npm install
+npm run build
+```
+
+After building, run the CLI locally via `node dist/cli/index.js` or link it:
+
+```bash
+npm link
+mycodemap --help
+```
+
+## First Run
+
+```bash
+mycodemap init
+```
+
+By default, `init` prints a reconciliation preview. Use `--yes` to apply the plan immediately.
+
+If the repository has a recognizable project marker, `init` can auto-detect a profile. Use `--profile <name>` to override that detection.
+
+Next:
+
+```bash
+mycodemap generate
+mycodemap doctor
+```
+
+`generate` writes analysis artifacts to `.mycodemap/`. `doctor` checks the runtime, workspace, and agent integrations.
+
+## What Gets Written
+
+- `.mycodemap/config.json` as the canonical config file
+- `.mycodemap/codemap.json` as the persisted graph data
+- `.mycodemap/logs/` for runtime logs when enabled
+- additional generated reports depending on the command you run
+
+## Minimal Workflow
+
+1. Install the package.
+2. Run `mycodemap init` or `mycodemap init --yes`.
+3. Run `mycodemap generate`.
+4. Inspect the output in `.mycodemap/`.
+5. Run `mycodemap doctor` if something looks off.
+
+## Common Setup Issues
+
+### Command not found after global install
+
+If `mycodemap` is not recognized after `npm install -g`, refresh the shell hash or use `npx`:
+
+```bash
+hash -r
+npx mycodemap --help
+```
+
+### Native dependency build failures
+
+Packages like `tree-sitter` and `better-sqlite3` may require a C++ compiler on your system. If the install fails:
+
+```bash
+# Ubuntu/Debian
+sudo apt-get install build-essential
+
+# macOS
+xcode-select --install
+```
+
+When native modules are unavailable, CodeMap falls back to WASM equivalents automatically.
+
+### Node.js version mismatch
+
+CodeMap requires Node.js `>= 20.0.0`. If you see an engine-unsupported error, upgrade Node.js or use a version manager such as `nvm`.
+
+## Common Follow-Up Commands
+
+- `mycodemap query` to search symbols and modules
+- `mycodemap deps` to inspect dependencies
+- `mycodemap impact -f <file>` to estimate change impact
+- `mycodemap benchmark` to compare native and WASM startup paths
+- `mycodemap --schema` to inspect the CLI contract
+
+## Next Steps
+
+- See [DEVELOPMENT.md](DEVELOPMENT.md) for local development setup, build commands, and contribution workflow.
+- See [TESTING.md](TESTING.md) for how to run the test suite and write new tests.
+- See [CONFIGURATION.md](CONFIGURATION.md) for the full config file format, environment variables, and per-environment overrides.

package/docs/SETUP_GUIDE.md

@@ -96,6 +96,55 @@ mycodemap init -y
 
 `init` 会同步 `.mycodemap/hooks/` 与 `.mycodemap/rules/`，但不会自动改写 `CLAUDE.md` / `AGENTS.md`；相关引用片段会通过 receipt 提示你手动加入。
 
+#### 理解 Init 收据
+
+`mycodemap init` 完成后会输出一份收据，分为两个部分：
+
+**Main Agent（主 Agent 上下文）**
+- 报告已生成的上下文文件路径（如 `claude-context.md`、`agents-context.md`）
+- 指导你将相关内容手动合并到项目根目录的 `CLAUDE.md` / `AGENTS.md`
+- 检测已同步状态：如果 `CLAUDE.md` 已包含 `.mycodemap/` 引用，标记为 `already-synced`
+
+**Subagent（子 Agent 配置）**
+- 报告平台配置示例文件（如 `claude-hook-example.json`、`codex-agent-example.toml`）
+- 指导你将配置复制到对应平台设置目录
+
+收据还会显示**个性化下一步**，基于实际安装的资产生成，而非固定的三步欢迎信息。
+
+> 注意：`init` 不会自动改写 `CLAUDE.md`、`AGENTS.md` 等团队共管文件。所有需要手动操作的步骤都会在收据中明确标注。
+
+#### 环境契约（Environment Contract）
+
+`mycodemap init` 还会生成 `.mycodemap/env-contract.json`，这是一个结构化的项目规则索引，包含：
+
+- **执行规则**：shell 命令包装（rtk）、测试入口命令（vitest run）
+- **提交规则**：commit message 格式（`[TAG] scope: message`）、有效标签列表
+- **验证规则**：真实场景验证要求、代码质量标准
+- **来源追踪**：每条规则的源文件和 hash，用于漂移检测
+
+子代理（Claude Code / Codex CLI 的委托代理）通过以下方式检索契约：
+
+```bash
+# CLI 检索（按代理类型过滤）
+mycodemap env-contract --for worker --json
+mycodemap env-contract --for explore --json
+
+# MCP 检索
+codemap_env_contract(agentType="worker")
+```
+
+检查契约一致性和源文件漂移：
+
+```bash
+# 检查契约是否过期或缺失关键项
+mycodemap env-contract --check
+
+# 全面健康诊断（包含 env-contract 状态）
+mycodemap doctor
+```
+
+> 冲突（如 hook 要求大写标签但文档示例写小写）会被报告为警告，不会阻断。源文件漂移会导致 `--check` 返回非零退出码，需要运行 `mycodemap env-contract --update` 重新生成。
+
 生成的 canonical 配置文件 `.mycodemap/config.json`：
 
 ```json

package/docs/TESTING.md

@@ -0,0 +1,81 @@
+<!-- generated-by: gsd-doc-writer -->
+
+# Testing
+
+## Test Stack
+
+CodeMap uses Vitest (`^1.1.0`) for unit, integration, and workflow tests. Coverage reporting is provided by `@vitest/coverage-v8` (`^1.6.1`).
+
+The default configuration (`vitest.config.ts`) runs tests in `src/**/*.test.ts` with a Node environment, `globals: true`, and a `threads` pool (max 2 threads). The E2E suite uses a separate configuration (`vitest.e2e.config.ts`) that runs `tests/e2e/**/*.test.ts` with up to 4 threads. Both configs enforce a 10-second timeout per test and hook.
+
+No global setup file is required; install dependencies with `npm ci` (or `npm install`) and run tests directly.
+
+## Main Test Commands
+
+| Command | Purpose |
+|---|---|
+| `npm test` | Run the default Vitest suite (all `src/**/*.test.ts` files) |
+| `npm run test:e2e` | Run the end-to-end workflow suite (`tests/e2e/**/*.test.ts`) |
+| `npx vitest` | Start Vitest in watch mode |
+| `npm run benchmark` | Run benchmark validation |
+| `npm run test:all` | Run tests followed by benchmarks |
+| `npm run check:all` | Run typecheck, lint, tests, and docs validation |
+
+## What the Tests Cover
+
+- CLI command behavior and output formatting
+- parser and analyzer logic
+- storage backends and fallback behavior
+- HTTP API route handling
+- MCP and env-contract plumbing
+- release, workflow, and guardrail commands
+
+## Practical Guidance
+
+- Prefer real filesystem and subprocess behavior for workflow and integration tests.
+- Use mocks for small units, but do not substitute mocks for end-to-end behavior that the repository already exercises with real I/O.
+- When a test changes command output, update the docs if the user-facing behavior changed.
+
+## Running a Single File
+
+```bash
+npx vitest run src/core/__tests__/analyzer.test.ts
+```
+
+## Writing New Tests
+
+Unit and integration tests live next to source code in `src/**/__tests__/*.test.ts`. End-to-end tests live in `tests/e2e/*.e2e.test.ts`. There is no dedicated global setup or shared helper file; tests import Vitest's `describe`, `it`, and `expect` directly.
+
+When adding a new test:
+- Place unit tests in `src/<module>/__tests__/<name>.test.ts`
+- Place E2E tests in `tests/e2e/<name>.e2e.test.ts`
+- Use `tests/fixtures/` for sample project data and `tests/golden/` for expected output snapshots
+
+## Coverage Requirements
+
+No minimum coverage threshold is configured in `vitest.config.ts`. Coverage is generated on demand with:
+
+```bash
+npx vitest run --coverage
+```
+
+The default reporter outputs text, lcov, and HTML to `./coverage`.
+
+## CI Integration
+
+Tests run in the **CI Gateway** workflow (`.github/workflows/ci-gateway.yml`), which triggers on pushes and pull requests to `main` and `develop`.
+
+Relevant CI steps:
+1. `npm test` — runs the default Vitest suite
+2. `npm run test:e2e` — runs the E2E workflow guardrail
+
+The same workflow also runs typecheck, lint, docs validation, contract gate checks, and CLI guardrails before considering the build green.
+
+## Before Release
+
+Run the validation gates that protect the repo:
+
+```bash
+npm run docs:check
+npm run docs:check:pre-release
+```

package/docs/ai-guide/OUTPUT.md

@@ -166,11 +166,22 @@ interface CodeMap {
   graphStatus?: "complete" | "partial";
   failedFileCount?: number;
   parseFailureFiles?: string[];
-  actualMode?: "fast" | "smart";
   pluginReport?: PluginExecutionReport;
 }
 ```
 
+### parser 模式收敛说明
+
+- 运行时主路径已收敛到 registry-backed tree-sitter parser。
+- `fast` / `smart` / `hybrid` 不再表示健康的运行模式；显式传入时应返回 `DEPRECATED_PARSER_MODE`，并附带 remediation 与 `nextCommand`。
+- `CodeMap` 输出不再暴露 `actualMode`，因为运行时不再做 hybrid 自动切换。
+
+### storage 持久化收敛说明
+
+- 持久化后端已收敛到 SQLite family；健康配置只应使用 `storage.type = "sqlite"`，或使用 `auto` 作为 SQLite-family alias。
+- `memory` 仍可用于测试或临时运行，但不属于持久化 truth。
+- 显式请求 `filesystem` / `kuzudb` 必须失败，并返回 `UNSUPPORTED_STORAGE_TYPE`、`remediationPlan` 与 `nextCommand`，而不是静默降级继续运行。
+
 ### graph integrity 语义
 
 | 字段 | 含义 | 何时出现 |
@@ -232,6 +243,35 @@ CLI-as-MCP Automatic Gateway 的核心机制：
 
 > 注意：tool 定义是自动生成的。如果你看到某个命令在 CLI 可用但在 MCP 不可见，检查该命令是否已注册到 `Interface Contract Schema`。
 
+### Phase 61 直连收敛
+
+- `query` / `deps` / `analyze` 已不再把 MCP 成功响应编码为 `cli_redirect`。
+- 这三个工具现在共享 `src/execution/contract-tools/` 下的 transport-free executor，CLI wrapper 与 MCP handler 都只负责参数归一化、渲染和 transport。
+- MCP 的外层 envelope 统一为：
+
+```typescript
+interface ContractToolExecutionResult<TResult> {
+  status: "ok" | "error";
+  result?: TResult;
+  error?: {
+    code: string;
+    message: string;
+    remediation?: string;
+    details?: Record<string, unknown>;
+  };
+  diagnostics: {
+    tool: "query" | "deps" | "analyze";
+    rootDir: string;
+    dataPath?: string;
+    durationMs?: number;
+    cacheHit?: boolean;
+    notes?: string[];
+  };
+}
+```
+
+- `codemap_query` 现在承载的是 CLI `query` 的 direct-execution truth；symbol graph 专用查询保留在 `codemap_impact` 这类 native tool 中，而不再和 `query` 形成双真相。
+
 ```typescript
 type McpToolStatus = "ok" | "not_found" | "ambiguous" | "unavailable";
 type McpToolConfidence = "high" | "ambiguous" | "unavailable";
@@ -297,16 +337,19 @@ interface McpImpactResult {
 
 ```typescript
 interface CodemapQueryInput {
-  symbol: string;
-  filePath?: string;
+  symbol?: string;
+  module?: string;
+  deps?: string;
+  search?: string;
+  limit?: number;
+  structured?: boolean;
 }
 ```
 
 语义：
-- `status = "ok"`：返回 `symbol`、`callers`、`callees`
-- `status = "unavailable"` + `GRAPH_NOT_FOUND`：还没生成 symbol-level 图
-- `status = "not_found"` + `SYMBOL_NOT_FOUND`：目标符号不存在
-- `status = "ambiguous"` + `AMBIGUOUS_EDGE`：同名符号无法仅靠 `symbol` / `filePath` 消歧
+- `status = "ok"`：`result` 内返回 CLI `query` 的原生命令负载（`type/query/count/results/metrics`）
+- `status = "error"`：`error.code` 明确标识失败原因，例如 `MISSING_QUERY_TYPE`、`INDEX_NOT_FOUND`
+- `diagnostics` 持续暴露 tool 名称、根目录、耗时与缓存信息，方便 host / agent 做自动化判断
 
 ### `codemap_impact`
 
@@ -434,7 +477,7 @@ interface DoctorOutput {
       "summary": { "pass": 1, "warn": 1, "fail": 0, "skip": 0 },
       "checks": [
         { "name": "config_file", "status": "pass", "message": "mycodemap.config.json 存在" },
-        { "name": "storage_type", "status": "warn", "message": "storage.type 未显式设置，使用 auto", "remediation": "建议显式设置为 sqlite 或 filesystem" }
+        { "name": "storage_type", "status": "warn", "message": "storage.type 未显式设置，使用 auto", "remediation": "建议显式设置为 sqlite，或保留 auto 作为 SQLite-family alias" }
       ]
     },
     {