dsh-repo-scanner 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,52 @@
+# Changelog
+
+本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/) 约定。
+
+## Unreleased
+
+- 新增 `prepublishOnly` 钩子：npm 发布前自动运行测试门禁。
+
+## 0.1.0 - 2026-09-02
+
+首个对外版本。开发过程曾自标 `1.0.0`（2026-08-23 完成度快照），因从未对外发布、且 v1.0 验收目标（arch-doc / dsh-refactor-insight 经适配层复用内核）尚未达成，按语义化版本回落为 `0.1.0` 首发。
+
+### DSH bundle 契约对齐（2026-09-02）
+
+- `package.json` 声明 `dsh.bundle.patch`（现行 harness 只激活声明该字段的包），`main` 改指 `plugin/index.js`；扫描内核经 exports 子路径 `dsh-repo-scanner/scanner` 暴露，CLI bin 不变。
+- `cordis.patch.yml` 重写为 config-tree `- insert:` 补丁格式，与 arch-doc / dsh-data-insight / dsh-refactor-insight / dsh-preset-scaffold 一致。
+- `plugin/index.js` 重写为官方 `FileSystemSkillProvider` 标准模式（providerName / includeDefaultRoots: false / customSkillDirs + dispose effect），与 arch-doc 同构。
+- `skills/repo-scanner-runbook/SKILL.md` 补充 frontmatter（`name` + `description`），满足现行技能识别规则（frontmatter 必填、name kebab-case）。
+- 新增 optional peerDependencies `@deepseek-ai/dsh-skill-filesystem`。
+- 版本统一：`package.json` 与 `TOOL_VERSION` 均为 `0.1.0`（`schema_version: 1.0` 为输出契约版本，独立于包版本，不受影响）。
+- 文档清理：移除内部路线图遗留的 v0.2 / v0.3 / v1.0 特性标记；库接口示例统一改为 `dsh-repo-scanner/scanner` 导入。
+
+### 修复（2026-08-23 完成度快照）
+
+- 修复 `src/dependencies.mjs` 编码损坏导致整个包无法加载的 SyntaxError（注释与代码被合并到同一行）。
+- `npm run check` 现在校验全部 `src/*.mjs`、`bin` 与 `plugin`，不再漏检源码模块。
+- `working_tree_clean` 语义明确：仅当提供 statusText 时判定（空输出 = 干净），其余场景为 null。
+- 修复行数统计对以换行结尾文件多算 1 行的问题；读取时剥离 UTF-8 BOM。
+- `--hash` 的 sha256 改为按原始字节计算（此前对二进制文件哈希的是 UTF-8 转码结果）。
+- 修复 tsconfig 位于子目录且 baseUrl 非根时别名解析基准目录错误的问题。
+- 修复 `normalizeDirList` 将 `..` 规整为 `.` 绕过越界检查的问题。
+- 修复 pyproject `[project]` / `[project.scripts]` 为最后一个 TOML 段时解析不到的问题。
+- CLI 补齐已实现选项的旗标：`--follow-symlinks`、`--cache`、`--cache-dir`、`--parsers`、符号查询、性能预算；`--base/--head` 记录到 `git.compare`。
+
+### 能力
+
+- 增量扫描缓存：`cache: true`（按 mtime/size 失效，sha256 结果一并缓存；只写系统临时目录）。
+- TS/JS import 别名解析增强：tsconfig `extends` 链、一个 pattern 多 target、JSONC 注释、baseUrl 裸模块名。
+- OpenAPI/GraphQL/数据库迁移文件识别并呈现到 `project.openapi_files` / `graphql_files` / `db_migration_files`。
+- 符号查询：`querySymbols` / `symbolQuery` 选项 / CLI `--symbol-name/--symbol-file/--symbol-module`。
+- 可插拔解析器接口：`registerParser` / `resolveParserChain`；内置 heuristic；`tree-sitter` 为可选依赖，缺失时自动回退并写 `E_PARSER_UNAVAILABLE` 警告。
+- 图分析模式 `--graphs`：模块级调用图 + 符号级引用图（命名导入解析到目标导出符号，带 confidence）。
+- 统一 `dsh-analysis-schema`：输出外壳携带 `analysis_schema` 标识，供多个分析插件共享报告结构。
+- 性能预算：`performance` 字段（elapsed_ms/files_indexed/bytes_read/cache 命中/budgets/budget_exceeded），默认 60000ms，超限写 `E_PERF_BUDGET_EXCEEDED` 警告。
+- 大仓库增量索引：符号结果按文件缓存，未变化文件跳过重复解析。
+- 可执行安全审计测试（`test/security.test.mjs`）：路径越界、符号链接逃逸、脱敏、内建模块白名单、无子进程/网络红线。
+- 完整事实 API：`getChangeImpactFacts`（反向依赖传播）、`getTestInsightFacts`（测试↔源码映射与模块覆盖）、`getDocSyncFacts`（文档引用与过期引用）。
+- 稳定 schema 兼容策略：已发布字段不删除，新增字段只做向后兼容增加。
+- `extractSymbols` 为 async（解析器链可能加载可选依赖）；支持 heuristic 解析 `export { a as b }` 语句。
+- fixtures：`ts-alias-app`（extends/多 target 别名）、`security-app`（脱敏）、monorepo API 契约文件、node-app README。
+- CI：`.github/workflows/ci.yml`（Node 18/20/22 × Windows/Ubuntu）。
+- 输出契约：schema 字段文档、扫描规则、示例输出与 README 同步。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 dsh-repo-scanner contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PUBLISHING.md

@@ -0,0 +1,23 @@
+# Publishing
+
+1. 运行 `npm test` 和 `npm run check`，确保全部通过。
+2. 运行 `npm pack --dry-run`，确认包含 `plugin/index.js`、`cordis.patch.yml`、`skills/`、`src/`、`bin/`、`docs/`、`examples/`、`README.md`、`CHANGELOG.md`、`LICENSE`、`PUBLISHING.md`。
+3. 发布前确认 `docs/output-schema.md` 与 `examples/sample-output.json` 与实际输出一致（`tool.version` 同步为当前版本号）。
+4. 提升 `package.json`、`src/options.mjs` 的 `TOOL_VERSION`、`CHANGELOG.md` 与 git tag 版本号，保持一致。
+
+## DSH bundle（已对齐 2026-09 现行契约）
+
+- `package.json` 声明 `dsh.bundle.patch: ./cordis.patch.yml`——harness 只激活声明该字段的包。
+- `cordis.patch.yml` 为 config-tree `- insert:` 补丁格式；harness 加载 `main`（`plugin/index.js`）。
+- `plugin/index.js` 经官方 `@deepseek-ai/dsh-skill-filesystem` 的 `FileSystemSkillProvider` 注册 `skills/` 为技能根（includeDefaultRoots: false）。
+- `skills/repo-scanner-runbook/SKILL.md` frontmatter 必填 `name`（kebab-case）+ `description`。
+- 扫描内核经 exports 子路径 `dsh-repo-scanner/scanner` 暴露；CLI bin 不变。
+
+## 发布渠道
+
+1. push `main`，确认 GitHub Actions CI 全绿（Node 18/20/22 × Windows/Ubuntu）。（2026-09-02 首推已绿）
+2. 打 tag `v0.1.0` 并推送。（已完成）
+3. （可选）`npm publish --access public`。
+4. 提交收录：awesome-dsh-plugin（`data/plugins/duyanta123__dsh-repo-scanner.yml`）与 awesome-deepseek-harness（en/zh README 条目，同一 PR）。
+
+> 注：GitHub 仓库原名 `-dsh-repo-scanner`（建仓笔误）已于 2026-09-02 更名为 `dsh-repo-scanner`，旧链接自动重定向。

package/README.md

@@ -0,0 +1,129 @@
+# dsh-repo-scanner
+
+面向 DeepSeek Harness 分析型插件（`arch-doc`、`dsh-refactor-insight`、`dsh-change-impact`、`dsh-test-insight`）的统一、可复现、只读的代码库事实扫描内核。
+
+只读：不修改目标仓库，不安装依赖，不执行项目代码。
+
+## 作为 DSH 插件安装
+
+本包按 DSH bundle 规范打包（`package.json` 声明 `dsh.bundle.patch`），安装后自动注册 `repo-scanner-runbook` 技能：
+
+```sh
+dsh plugin --profile web add "github:duyanta123/dsh-repo-scanner#main"
+```
+
+安装后重启 `dsh --profile web`，技能即可被发现；技能只在需要时加载 runbook，扫描本身通过 shell 调用 CLI 完成。上层插件（dsh-change-impact / dsh-test-insight 等）以库形式依赖本包时，经 exports 子路径 `dsh-repo-scanner/scanner` 引入扫描内核。
+
+## 快速开始
+
+```bash
+node bin/repo-scanner.mjs <repo_path> --probe
+node bin/repo-scanner.mjs <repo_path> --files
+node bin/repo-scanner.mjs <repo_path> --scan
+node bin/repo-scanner.mjs <repo_path> --deps
+node bin/repo-scanner.mjs <repo_path> --entry
+node bin/repo-scanner.mjs <repo_path> --symbols
+node bin/repo-scanner.mjs <repo_path> --graphs
+node bin/repo-scanner.mjs <repo_path> --git --diff-text-file diff.txt
+node bin/repo-scanner.mjs <repo_path> --all --json
+```
+
+库接口：
+
+```js
+import { scanRepository } from 'dsh-repo-scanner/scanner';
+
+const report = await scanRepository({
+  repoPath: '.',
+  modes: ['probe', 'modules', 'dependencies', 'entries', 'symbols', 'graphs', 'git'],
+  maxDepth: 3,
+  cache: true,                 // 增量扫描缓存
+  parsers: ['heuristic'],      // 可插拔解析器（tree-sitter 为可选依赖）
+  symbolQuery: { name: 'auth' }, // 符号查询
+  git: { diffText },
+});
+```
+
+### 事实 API
+
+```js
+import {
+  getChangeImpactFacts, // 变更影响：反向依赖传播 + 受影响模块/符号
+  getTestInsightFacts,  // 测试洞察：测试↔源码映射 + 模块覆盖
+  getDocSyncFacts,      // 文档同步：文档引用 + 过期引用
+} from 'dsh-repo-scanner/scanner';
+
+const impact = await getChangeImpactFacts({
+  repoPath: '.',
+  git: { statusText }, // 或 diffText / changedFiles
+});
+```
+
+## 输出示例
+
+```json
+{
+  "schema_version": "1.0",
+  "analysis_schema": { "name": "dsh-analysis-schema", "version": "1.0" },
+  "tool": { "name": "dsh-repo-scanner", "version": "0.1.0" },
+  "input": { "repo_path": ".", "resolved_path": "C:/work/app", "options": {} },
+  "limits": { "max_depth": 3, "max_files": 2000, "max_file_bytes": 256000, "truncated": false, "warnings": [] },
+  "project": {},
+  "files": [],
+  "modules": [],
+  "dependencies": { "internal": [], "external": [] },
+  "entry_points": [],
+  "run_methods": [],
+  "symbols": [],
+  "graphs": null,
+  "risks": [],
+  "errors": [],
+  "performance": null,
+  "git": null
+}
+```
+
+完整字段说明见 `docs/output-schema.md`；扫描规则见 `docs/scanning-rules.md`。
+
+## 参数与退出码
+
+| 参数 | 默认 | 说明 |
+| --- | --- | --- |
+| `--max-depth N` | 3 | 最大目录深度 |
+| `--max-files N` | 2000 | 最大文件数 |
+| `--max-file-bytes N` | 256000 | 单文件内容读取上限 |
+| `--include-dirs a,b` | 空 | 只扫描这些目录 |
+| `--exclude-dirs a,b` | 内置默认 | 追加排除目录 |
+| `--language LANG` | 空 | 语言过滤 |
+| `--format json\|jsonl` | json | 输出格式 |
+| `--hash` | 关 | 计算文件 sha256（按原始字节） |
+| `--strict` | 关 | 存在错误或警告时非零退出 |
+| `--follow-symlinks` | 关 | 跟随符号链接（目标必须在仓库内） |
+| `--cache` / `--cache-dir DIR` | 关 | 增量扫描缓存（只写临时目录） |
+| `--parsers a,b` | heuristic | 符号解析器链（tree-sitter 为可选依赖，缺失自动回退） |
+| `--symbol-name/file/module` | 空 | 符号查询过滤 |
+| `--perf-budget-ms N` | 60000 | 性能预算（0 关闭；超限写 warning） |
+
+退出码：`0` 成功；`1` 存在错误，或 `--strict` 下存在警告；`2` 参数错误或仓库路径无效；`3` 输出失败或契约错误。
+
+## 安全红线
+
+- 不写入目标仓库；不做 checkout/reset/clean。
+- 不安装依赖、不执行目标项目代码或脚本。
+- 路径规范化后拒绝越界；默认不跟随符号链接。
+- 不 spawn 子进程获取文件或 Git 事实（由可执行安全审计测试保障）。
+- 只把能解析到仓库内部的导入归为 internal；动态 import/require 记入 `risks`。
+- 输出对 token/密码/连接串/JWT 自动脱敏。
+
+## 与 arch-doc / dsh-refactor-insight 的关系
+
+两个插件都有各自的 `arch-profile.mjs`。本包提取其扫描逻辑，通过 npm dependency 或 CLI 被它们复用。迁移顺序与字段映射见 `docs/migration-guide.md`。
+
+## 开发
+
+```bash
+npm test    # 功能测试 + 安全审计测试
+npm run check
+```
+
+Node >=18。

package/bin/repo-scanner.mjs

@@ -0,0 +1,282 @@
+#!/usr/bin/env node
+import fs from 'node:fs';
+import { scanRepository, TOOL_NAME, TOOL_VERSION, SCHEMA_VERSION, validateReport, normalizeOptions } from '../src/index.mjs';
+import { serializeReport } from '../src/output.mjs';
+
+const USAGE = `dsh-repo-scanner ${TOOL_VERSION}
+
+Usage:
+  node bin/repo-scanner.mjs <repo_path> [mode] [options]
+
+Modes:
+  --probe      仓库探测：语言、仓库类型、技术栈、manifest
+  --files      文件索引
+  --scan       模块识别（等价 modes: scan/modules）
+  --deps       依赖关系（internal/external）
+  --entry      入口与运行方式
+  --symbols    符号索引
+  --graphs     图分析：模块调用图 + 符号引用图
+  --git        Git 事实（HEAD、分支、变更文件；可用 --diff-text-file/--status-text-file 提供只读 diff 文本）
+  --all        全部模式（默认）
+
+Options:
+  --max-depth N          最大目录深度（默认 3）
+  --max-files N          最大文件数（默认 2000）
+  --max-file-bytes N     单文件内容读取上限（默认 256000）
+  --include-dirs a,b     只扫描这些目录（root 文件始终保留）
+  --exclude-dirs a,b     追加排除目录（默认排除 .git/node_modules/dist 等）
+  --language LANG        按语言过滤文件
+  --format json|jsonl    输出格式（默认 json）
+  --hash                 计算文件 sha256
+  --strict               本应当失败的错误（输出校验、路径越界、存在错误）或警告时非零退出
+  --follow-symlinks      跟随符号链接（默认关闭，链接目标必须在仓库内）
+  --cache                启用增量扫描缓存（只写系统临时目录）
+  --cache-dir DIR        缓存目录（默认 os.tmpdir()/dsh-repo-scanner-cache）
+  --parsers a,b          符号解析器（heuristic | tree-sitter；tree-sitter 为可选依赖）
+  --symbol-name NAME     符号查询：按名称过滤（不区分大小写子串）
+  --symbol-file FILE     符号查询：按文件过滤（精确或后缀匹配）
+  --symbol-module NAME   符号查询：按模块过滤（模块路径或名称）
+  --perf-budget-ms N     性能预算毫秒数（默认 60000，超限写 warning；0 关闭）
+  --base <ref>           Git base ref（记录到 git.compare，供变更影响分析）
+  --head <ref>           Git head ref（记录到 git.compare，供变更影响分析）
+  --diff-text-file FILE  只读读取 diff 全文（供 --git）
+  --status-text-file FILE 只读读取 git status 文本（供 --git）
+  --json                 等价 --format json
+  --version              打印版本
+  --help                 打印帮助
+`;
+
+export function parseArgs(argv) {
+  const args = [...argv];
+  const positional = [];
+  const modes = [];
+  const options = {};
+  let help = false;
+  let version = false;
+
+  const readValue = (name, fallback) => {
+    if (args.length === 0) {
+      throw new Error(`missing value for ${name}`);
+    }
+    const value = args.shift();
+    return value ?? fallback;
+  };
+
+  while (args.length > 0) {
+    const arg = args.shift();
+    switch (arg) {
+      case '--probe':
+        modes.push('probe');
+        break;
+      case '--files':
+        modes.push('files');
+        break;
+      case '--scan':
+        modes.push('scan');
+        break;
+      case '--deps':
+        modes.push('deps');
+        break;
+      case '--entry':
+        modes.push('entry');
+        break;
+      case '--symbols':
+        modes.push('symbols');
+        break;
+      case '--graphs':
+        modes.push('graphs');
+        break;
+      case '--git':
+        modes.push('git');
+        break;
+      case '--all':
+        modes.push('all');
+        break;
+      case '--max-depth':
+        options.maxDepth = readValue('--max-depth');
+        break;
+      case '--max-files':
+        options.maxFiles = readValue('--max-files');
+        break;
+      case '--max-file-bytes':
+        options.maxFileBytes = readValue('--max-file-bytes');
+        break;
+      case '--include-dirs':
+        options.includeDirs = readValue('--include-dirs');
+        break;
+      case '--exclude-dirs':
+        options.excludeDirs = readValue('--exclude-dirs');
+        break;
+      case '--language':
+        options.language = readValue('--language');
+        break;
+      case '--format':
+        options.format = readValue('--format');
+        break;
+      case '--json':
+        options.format = 'json';
+        break;
+      case '--hash':
+        options.hash = true;
+        break;
+      case '--strict':
+        options.strict = true;
+        break;
+      case '--follow-symlinks':
+        options.followSymlinks = true;
+        break;
+      case '--cache':
+        options.cache = true;
+        break;
+      case '--cache-dir':
+        options.cacheDir = readValue('--cache-dir');
+        break;
+      case '--parsers':
+        options.parsers = readValue('--parsers');
+        break;
+      case '--symbol-name':
+        options.symbolQuery = options.symbolQuery || {};
+        options.symbolQuery.name = readValue('--symbol-name');
+        break;
+      case '--symbol-file':
+        options.symbolQuery = options.symbolQuery || {};
+        options.symbolQuery.file = readValue('--symbol-file');
+        break;
+      case '--symbol-module':
+        options.symbolQuery = options.symbolQuery || {};
+        options.symbolQuery.module = readValue('--symbol-module');
+        break;
+      case '--perf-budget-ms':
+        options.perfBudgetMs = readValue('--perf-budget-ms');
+        break;
+      case '--base':
+        options.git = options.git || {};
+        options.git.base = readValue('--base');
+        break;
+      case '--head':
+        options.git = options.git || {};
+        options.git.head = readValue('--head');
+        break;
+      case '--diff-text-file': {
+        const file = readValue('--diff-text-file');
+        options.git = options.git || {};
+        options.git.diffText = readOwnFile(file);
+        break;
+      }
+      case '--status-text-file': {
+        const file = readValue('--status-text-file');
+        options.git = options.git || {};
+        options.git.statusText = readOwnFile(file);
+        break;
+      }
+      case '--help':
+      case '-h':
+        help = true;
+        break;
+      case '--version':
+      case '-v':
+        version = true;
+        break;
+      default:
+        if (arg.startsWith('--') && arg.includes('=')) {
+          const [name, value] = [arg.slice(0, arg.indexOf('=')), arg.slice(arg.indexOf('=') + 1)];
+          args.unshift(value);
+          args.unshift(name);
+          continue;
+        }
+        if (arg.startsWith('-')) throw new Error(`unknown option: ${arg}`);
+        positional.push(arg);
+        break;
+    }
+  }
+
+  return { positional, modes, options, help, version };
+}
+
+function readOwnFile(filePath) {
+  try {
+    return fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    throw new Error(`cannot read file ${filePath}: ${err.code || err.message}`);
+  }
+}
+
+function printError(error, exitCode) {
+  const payload = {
+    schema_version: SCHEMA_VERSION,
+    tool: { name: TOOL_NAME, version: TOOL_VERSION },
+    error: {
+      code: error.code || 'E_SCANNER',
+      message: error.message || String(error),
+    },
+  };
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs(process.argv.slice(2));
+  } catch (err) {
+    printError(err, 2);
+    process.exit(2);
+  }
+
+  if (parsed.help) {
+    process.stdout.write(USAGE);
+    process.exit(0);
+  }
+  if (parsed.version) {
+    process.stdout.write(`${TOOL_NAME} ${TOOL_VERSION}\n`);
+    process.exit(0);
+  }
+
+  if (parsed.positional.length === 0) {
+    printError(new Error('missing <repo_path> argument'), 2);
+    process.exit(2);
+  }
+  if (parsed.positional.length > 1) {
+    printError(new Error(`unexpected extra argument: ${parsed.positional[1]}`), 2);
+    process.exit(2);
+  }
+
+  const input = {
+    repoPath: parsed.positional[0],
+    modes: parsed.modes.length > 0 ? parsed.modes : ['all'],
+    ...parsed.options,
+  };
+
+  try {
+    const report = await scanRepository(input);
+    let output;
+    try {
+      output = serializeReport(report, parsed.options.format || 'json');
+    } catch (validationErr) {
+      printError(validationErr, 3);
+      process.exit(3);
+    }
+    process.stdout.write(`${output}\n`);
+
+    const warnings = report.limits?.warnings?.length || 0;
+    const errors = report.errors?.length || 0;
+    // 仅错误始终非零退出；警告默认不影响退出码，仅在 strict 下使命令失败。
+    if (errors > 0 || (parsed.options.strict && warnings > 0)) {
+      process.exit(1);
+    }
+    process.exit(0);
+  } catch (err) {
+    const code = err?.code;
+    if (code === 'E_INVALID_REPO_PATH' || code === 'E_PATH_TRAVERSAL') {
+      printError(err, 2);
+      process.exit(2);
+    }
+    if (code === 'E_OUTPUT_VALIDATION') {
+      printError(err, 3);
+      process.exit(3);
+    }
+    printError(err, 3);
+    process.exit(3);
+  }
+}
+
+await main();

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-repo-scanner — DSH bundle patch。
+#
+# 当某个 profile 在 dsh.profile.bundles 中列出本包时（dsh plugin add 即完成
+# 此事），dsh 启动时把本补丁打入配置树：插入本包插件行，加载 package.json
+# 的 main（plugin/index.js），将自带 skills/ 注册为技能根。
+#
+# 人设与工具不在此处重复声明——宿主 profile（standard/web）已提供文件、
+# shell、计划模式、web 搜索、子代理等 runbook 引用的全部工具。
+- insert:
+    - id: dsh-repo-scanner
+      name: dsh-repo-scanner

package/docs/migration-guide.md

@@ -0,0 +1,40 @@
+# 从 arch-doc / dsh-refactor-insight 迁移
+
+两个插件当前各自维护 `arch-profile.mjs`。迁移顺序：
+
+1. 冻结旧输出字段，建立快照测试。
+2. 确认旧字段在新 schema 中的映射（见下表）。
+3. 引入 `dsh-repo-scanner` 作为 npm dependency，通过库接口或 CLI 调用。
+4. 旧命令保留兼容包装一段时间。
+5. 两侧输出稳定后删除重复实现。
+
+## 字段映射
+
+| 旧字段 | 新字段 | 备注 |
+| --- | --- | --- |
+| mainLanguage | project.language | 附 `language_evidence` |
+| repoType | project.repo_type | 附 `repo_type_evidence` |
+| files[] | files[] | 路径统一 POSIX `/` |
+| modules[] | modules[] | 不推断职责，保留 path/file_count/key_files/evidence |
+| internalDeps[] | dependencies.internal[] | 仅可解析内部路径 |
+| externalDeps[] | dependencies.external[] | 含 manifest 版本 |
+| entrypoints/frameworks | entry_points[] | type 使用 web/cli/worker/scheduler/library |
+| runCommands[] | run_methods[] | 必须标注 `source` |
+
+## 调用示例
+
+```js
+import { scanRepository } from 'dsh-repo-scanner/scanner';
+
+const report = await scanRepository({ repoPath, modes: ['probe', 'scan', 'deps'] });
+```
+
+CLI 方式：
+
+```bash
+node bin/repo-scanner.mjs <repo_path> --probe --scan --deps --json
+```
+
+## 兼容包装
+
+旧命令可以先保留，并把结果转换为旧字段形状；不要在旧包装中重新实现扫描逻辑。

package/docs/output-schema.md

@@ -0,0 +1,111 @@
+# Output Schema v1.0
+
+所有命令输出统一外壳。字段名使用 snake_case；路径使用 POSIX `/`；行号从 1 开始。
+
+## 兼容策略（v1.0）
+
+- 已发布字段不删除、不改语义；新增字段只做向后兼容增加。
+- 只有发生不兼容变化时才升级 `schema_version` 主版本。
+- `schema_version: "1.0"` 自 v0.1 起保持稳定；v1.0 新增 `analysis_schema`、`graphs`、`performance` 均为增量字段。
+
+## 外壳
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| schema_version | string | 固定 `"1.0"` |
+| analysis_schema | object | `dsh-analysis-schema` 标识（name/version），供多个分析插件共享报告结构 |
+| tool.name | string | `"dsh-repo-scanner"` |
+| tool.version | string | 包版本 |
+| input.repo_path | string | 调用方传入的原始 repo_path |
+| input.resolved_path | string | 规范化后的绝对路径 |
+| input.options | object | 当前扫描选项摘要（modes/language/hash/strict/follow_symlinks/cache/parsers/symbol_query） |
+| limits.max_depth | number | 最大目录深度 |
+| limits.max_files | number | 最大文件数 |
+| limits.max_file_bytes | number | 单文件内容读取上限 |
+| limits.truncated | boolean | 是否因上限发生截断 |
+| limits.warnings | array | 可恢复警告（含解析器回退、性能预算超限） |
+| project | object | probe 结果；无能力时可为空对象 |
+| files | array | 文件索引 |
+| modules | array | 模块识别结果 |
+| dependencies.internal | array | 仓库内依赖，必须能解析到内部路径 |
+| dependencies.external | array | 第三方依赖导入与 manifest 声明 |
+| entry_points | array | 入口分类（web/cli/worker/scheduler/library） |
+| run_methods | array | 运行命令与来源（命令经过脱敏） |
+| symbols | array | 符号索引，`parser` 字段标注实际使用的解析器 |
+| graphs | object/null | graphs 模式时输出模块调用图与符号引用图，否则为 null |
+| risks | array | 无法可靠解析的依赖等风险 |
+| errors | array | 扫描过程中无法恢复的错误（默认保持空） |
+| performance | object/null | 实测性能指标与预算（elapsed_ms/files_indexed/bytes_read/cache/budgets/budget_exceeded） |
+| git | object/null | git 模式时输出，否则为 null |
+
+## project 字段（probe）
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| name / description | string/null | 来自 manifest 或目录名 |
+| language | string/null | 主语言 |
+| repo_type | string | monolith/monorepo/library/service/cli/unknown |
+| repo_type_evidence | array | 判定证据 |
+| tech_stack | array | 技术栈标签 |
+| manifest_files | array | manifest 文件路径 |
+| openapi_files | array | OpenAPI/Swagger 契约文件 |
+| graphql_files | array | GraphQL schema 文件 |
+| db_migration_files | array | 数据库迁移文件 |
+| file_count / source_file_count | number | 文件统计 |
+| language_evidence | array | 主语言证据文件 |
+| confidence | string | high/medium |
+
+## graphs 字段
+
+```json
+{
+  "module_call_graph": {
+    "nodes": [{"name": "api", "path": "src/api", "file_count": 1}],
+    "edges": [{"source": "src/api", "target": "src/auth", "weight": 2, "imports": [{"source": "...", "target": "..."}]}]
+  },
+  "symbol_references": [
+    {"source_file": "src/api/server.ts", "target_file": "src/auth/service.ts", "symbol": "AuthService", "kind": "named-import", "line": 2, "confidence": "high"}
+  ]
+}
+```
+
+- `weight`：聚合到模块维度的导入语句数量。
+- `symbol_references.kind`：named-import / default-import / namespace-import / from-import / star-import。
+- 只输出可解析的事实边；无法确认的绑定不强行猜测。
+
+## git 字段
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| available | boolean | 是否找到 .git 目录 |
+| head_ref / branch / head_sha | string/null | 从 .git/HEAD 只读解析 |
+| working_tree_clean | boolean/null | 仅当提供 statusText 时可判定；不可判定时为 null |
+| changed_files | array | 调用方提供的 diff/status/清单解析结果 |
+| compare | object | 调用方提供的 base/head ref（供变更影响分析记录） |
+| method | string/null | changed_files 的来源方式 |
+| warnings | array | Git 相关警告 |
+
+## 事实 API 输出
+
+`getChangeImpactFacts` / `getTestInsightFacts` / `getDocSyncFacts` 返回独立外壳（含 schema_version、analysis_schema、tool），字段：
+
+- 变更影响：`changed_files`、`impacted_files`（path/via/depth，最大传播深度 3）、`impacted_modules`、`impacted_symbols`。
+- 测试洞察：`test_files`（test_file→target_file 映射）、`orphan_tests`、`module_test_coverage`（module/name/source_file_count/has_tests/tested_files）、`source_files_without_tests`。
+- 文档同步：`docs`（doc/referenced_source_files/reference_count）、`docs_with_stale_references`、`stale_references`（doc/path）、`source_files_without_doc_references`。
+
+## 空值约定
+
+- 空集合统一返回 `[]`。
+- 不存在的可选对象使用 `null`。
+- 语言无法识别时为 `null`。
+- `lines`/`sha256` 未读取时为 `null`。
+
+## 稳定路径示例
+
+```json
+{
+  "path": "src/auth/service.ts"
+}
+```
+
+禁止出现反斜杠路径；Windows 扫描必须转换为 POSIX 分隔符。