spectra-cli 4.1.1

package/dist/debt-scanner/aggregator/report-builder.d.ts

@@ -0,0 +1,25 @@
+/**
+ * technical-debt.md 生成器
+ *
+ * 接收 DebtReport，产出满足 AC-3.1/AC-3.2/AC-3.3 的 Markdown 文本。
+ */
+import type { CodeDebtEntry, DebtDiagnostics, DebtMetrics, DebtReport, OpenQuestionEntry, TokenUsage } from '../types.js';
+export interface BuildReportOptions {
+    codeEntries: CodeDebtEntry[];
+    openQuestions: OpenQuestionEntry[];
+    diagnostics: DebtDiagnostics;
+    metrics: DebtMetrics;
+    tokenUsage: TokenUsage;
+    durationMs: number;
+    llmModel?: string;
+    fallbackReason?: string;
+    /** 扫描的语言集合，用于文档描述 */
+    languages: string[];
+}
+/**
+ * 生成 technical-debt.md 内容。
+ */
+export declare function buildDebtReportMarkdown(opts: BuildReportOptions): string;
+/** 从 DebtReport 直接构建 markdown（便利 wrapper） */
+export declare function buildDebtReportFromReport(report: DebtReport, languages: string[]): string;
+//# sourceMappingURL=report-builder.d.ts.map

package/dist/debt-scanner/aggregator/report-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-builder.d.ts","sourceRoot":"","sources":["../../../src/debt-scanner/aggregator/report-builder.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAEf,WAAW,EACX,UAAU,EACV,iBAAiB,EACjB,UAAU,EACX,MAAM,aAAa,CAAC;AAErB,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,aAAa,EAAE,iBAAiB,EAAE,CAAC;IACnC,WAAW,EAAE,eAAe,CAAC;IAC7B,OAAO,EAAE,WAAW,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,qBAAqB;IACrB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,kBAAkB,GAAG,MAAM,CAgExE;AA+FD,6CAA6C;AAC7C,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,UAAU,EAClB,SAAS,EAAE,MAAM,EAAE,GAClB,MAAM,CAYR"}

package/dist/debt-scanner/aggregator/report-builder.js

@@ -0,0 +1,162 @@
+/**
+ * 生成 technical-debt.md 内容。
+ */
+export function buildDebtReportMarkdown(opts) {
+    const { codeEntries, openQuestions, diagnostics, metrics, tokenUsage, durationMs, llmModel, fallbackReason } = opts;
+    const isEmpty = codeEntries.length === 0 && openQuestions.length === 0;
+    const frontmatter = [
+        '---',
+        'generated: true',
+        `tokenUsage: {input: ${tokenUsage.input}, output: ${tokenUsage.output}}`,
+        `durationMs: ${durationMs}`,
+        `llmModel: ${llmModel ?? 'null'}`,
+        `fallbackReason: ${fallbackReason ?? 'null'}`,
+        '---',
+        '',
+    ].join('\n');
+    const scanLine = '> 由 Spectra debt-intelligence pipeline 生成。本次扫描范围：' +
+        `${diagnostics.filesScanned} 个源文件（${opts.languages.length ? opts.languages.join(', ') : 'n/a'}），` +
+        `${diagnostics.docsScanned} 个 design-doc。`;
+    const body = [];
+    if (isEmpty) {
+        body.push('# 技术债清单\n');
+        body.push(scanLine + '\n');
+        body.push('**项目当前未识别出技术债。**\n');
+        body.push('- 代码注释债务：0 条');
+        body.push('- Design-doc 开放问题：0 条\n');
+        return frontmatter + body.join('\n') + '\n';
+    }
+    body.push('# 技术债清单\n');
+    body.push(scanLine + '\n');
+    // 概要
+    body.push('## 概要\n');
+    body.push(renderSummary(metrics, codeEntries));
+    body.push('');
+    // 代码注释债务
+    body.push('## 代码注释债务\n');
+    if (codeEntries.length === 0) {
+        body.push('项目当前未识别出代码注释债务。\n');
+    }
+    else {
+        body.push(renderCodeTable(codeEntries));
+        body.push('');
+    }
+    // Design-doc 开放问题
+    body.push('## Design-doc 开放问题\n');
+    if (openQuestions.length === 0) {
+        body.push('未识别出开放问题。\n');
+    }
+    else {
+        body.push(renderOpenQuestionsByDoc(openQuestions));
+        body.push('');
+    }
+    // 引用清单
+    body.push('## 引用清单\n');
+    body.push(renderReferences(codeEntries));
+    body.push('');
+    return frontmatter + body.join('\n') + '\n';
+}
+function renderSummary(metrics, entries) {
+    const ageBuckets = { '<30': 0, '30-90': 0, '90-180': 0, '>180': 0 };
+    for (const e of entries) {
+        if (e.ageDays < 30)
+            ageBuckets['<30']++;
+        else if (e.ageDays < 90)
+            ageBuckets['30-90']++;
+        else if (e.ageDays < 180)
+            ageBuckets['90-180']++;
+        else
+            ageBuckets['>180']++;
+    }
+    const oldest = [...entries].sort((a, b) => b.ageDays - a.ageDays).slice(0, 5);
+    const oldestLines = oldest.length > 0
+        ? oldest
+            .map((e) => `- ${e.kind} @ \`${e.filePath}:${e.line}\`（${e.ageDays} 天）— ${escapeText(e.text)}`)
+            .join('\n')
+        : '- （无）';
+    const kindLine = Object.keys(metrics.byKind)
+        .map((k) => `${k} ${metrics.byKind[k]}`)
+        .join('，');
+    return [
+        `- **代码注释债务**：${metrics.totalEntries} 条（${kindLine}）`,
+        `- **Design-doc 开放问题**：${metrics.openQuestionsCount} 条`,
+        `- **年龄分布**：< 30 天 ${ageBuckets['<30']} | 30-90 天 ${ageBuckets['30-90']} | 90-180 天 ${ageBuckets['90-180']} | > 180 天 ${ageBuckets['>180']}`,
+        `- **代码债务密度**：${metrics.densityPerKloc.toFixed(2)} 条/kLOC`,
+        `- **最老条目年龄**：${metrics.oldestAgeDays} 天`,
+        '',
+        '### 最老 5 条',
+        '',
+        oldestLines,
+    ].join('\n');
+}
+function renderCodeTable(entries) {
+    const header = '| # | Kind | 文件 | 行 | 符号 | 作者 | 年龄(天) | 描述 |';
+    const sep = '|---|------|------|-----|------|------|----------|------|';
+    const rows = entries.map((e, i) => `| ${i + 1} | ${e.kind} | \`${e.filePath}\` | ${e.line} | ${e.symbol ?? '—'} | ${e.author} | ${e.ageDays} | ${escapeText(e.text)} |`);
+    return [header, sep, ...rows].join('\n');
+}
+function renderOpenQuestionsByDoc(questions) {
+    const byDoc = new Map();
+    for (const q of questions) {
+        let list = byDoc.get(q.docPath);
+        if (!list) {
+            list = [];
+            byDoc.set(q.docPath, list);
+        }
+        list.push(q);
+    }
+    const blocks = [];
+    const sortedDocs = [...byDoc.keys()].sort();
+    for (const doc of sortedDocs) {
+        blocks.push(`### ${doc}\n`);
+        for (const q of byDoc.get(doc)) {
+            const topics = q.topics.length ? ` _[主题: ${q.topics.join(', ')}]_` : '';
+            const src = q.source === 'rule' ? '(规则命中)' : '(LLM 判定)';
+            blocks.push(`- **${q.headingPath}** ${src}${topics}`);
+            blocks.push(`  > ${escapeText(q.snippet)}`);
+        }
+        blocks.push('');
+    }
+    return blocks.join('\n');
+}
+function renderReferences(entries) {
+    if (entries.length === 0)
+        return '（无代码注释债务引用）';
+    const byFile = new Map();
+    for (const e of entries) {
+        let arr = byFile.get(e.filePath);
+        if (!arr) {
+            arr = [];
+            byFile.set(e.filePath, arr);
+        }
+        arr.push(e);
+    }
+    const out = [];
+    for (const file of [...byFile.keys()].sort()) {
+        out.push(`- \`${file}\``);
+        for (const e of byFile.get(file)) {
+            out.push(`  - 第 ${e.line} 行 — ${e.kind}: ${escapeText(e.text)}`);
+        }
+    }
+    return out.join('\n');
+}
+/** 表格与 blockquote 兼容：移除换行，限长 200 字符 */
+function escapeText(raw) {
+    const s = raw.replace(/\s+/g, ' ').replace(/\|/g, '\\|');
+    return s.length <= 200 ? s : s.slice(0, 199) + '…';
+}
+/** 从 DebtReport 直接构建 markdown（便利 wrapper） */
+export function buildDebtReportFromReport(report, languages) {
+    return buildDebtReportMarkdown({
+        codeEntries: report.codeEntries,
+        openQuestions: report.openQuestions,
+        diagnostics: report.diagnostics,
+        metrics: report.metrics,
+        tokenUsage: report.tokenUsage,
+        durationMs: report.durationMs,
+        llmModel: report.llmModel,
+        fallbackReason: report.fallbackReason,
+        languages,
+    });
+}
+//# sourceMappingURL=report-builder.js.map

package/dist/debt-scanner/aggregator/report-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-builder.js","sourceRoot":"","sources":["../../../src/debt-scanner/aggregator/report-builder.ts"],"names":[],"mappings":"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"}

package/dist/debt-scanner/comments/debt-classifier.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 债务注释分类器
+ *
+ * 接收 CommentRegion 列表（已由 AST 保证不包含字符串字面量），
+ * 在注释文本内部进行 TODO/FIXME/HACK/XXX/NOTE 的正则匹配。
+ *
+ * 每一行可能独立匹配（支持块注释内多个 TODO 各自独立成条）。
+ */
+import type { CommentRegion, DebtKind, DebtSeverity } from '../types.js';
+/** kind → severity 映射 */
+export declare const SEVERITY_MAP: Readonly<Record<DebtKind, DebtSeverity>>;
+/** 排序权重：critical=0, warning=1, informational=2 */
+export declare const SEVERITY_ORDER: Readonly<Record<DebtSeverity, number>>;
+export interface ClassifiedDebt {
+    kind: DebtKind;
+    severity: DebtSeverity;
+    /** 剩余描述（已剥离 kind 前缀和可选 owner） */
+    text: string;
+    /** 可选 owner（括号或 @ 语法里的人名） */
+    owner: string | null;
+    /** 匹配发生在 region 内的第几行（0-indexed） */
+    lineOffset: number;
+}
+/**
+ * 对单个 CommentRegion 逐行匹配。
+ */
+export declare function classifyCommentRegion(region: CommentRegion): ClassifiedDebt[];
+//# sourceMappingURL=debt-classifier.d.ts.map

package/dist/debt-scanner/comments/debt-classifier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debt-classifier.d.ts","sourceRoot":"","sources":["../../../src/debt-scanner/comments/debt-classifier.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEzE,yBAAyB;AACzB,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,QAAQ,EAAE,YAAY,CAAC,CAMhE,CAAC;AAEH,kDAAkD;AAClD,eAAO,MAAM,cAAc,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAIhE,CAAC;AAcH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,6BAA6B;IAC7B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,EAAE,CAmB7E"}

package/dist/debt-scanner/comments/debt-classifier.js

@@ -0,0 +1,50 @@
+/** kind → severity 映射 */
+export const SEVERITY_MAP = Object.freeze({
+    FIXME: 'critical',
+    HACK: 'critical',
+    TODO: 'warning',
+    XXX: 'informational',
+    NOTE: 'informational',
+});
+/** 排序权重：critical=0, warning=1, informational=2 */
+export const SEVERITY_ORDER = Object.freeze({
+    critical: 0,
+    warning: 1,
+    informational: 2,
+});
+/**
+ * 在一段注释内部查找所有债务标记。
+ *
+ * 正则设计：
+ * - 每行独立匹配（多行块注释会产生多条）
+ * - 允许前导的 `*`、`#`、`//`、空白
+ * - 支持 TODO / FIXME / HACK / XXX / NOTE，大小写不敏感
+ * - 支持 `TODO(connor):` 或 `TODO@user:` 风格的可选括号 /@ 标注
+ * - 冒号可选
+ */
+const DEBT_REGEX = /^[\s*/#]*\b(TODO|FIXME|HACK|XXX|NOTE)(?:\(([\w@.\-]+)\)|@([\w.\-]+))?\s*:?\s*(.*)$/i;
+/**
+ * 对单个 CommentRegion 逐行匹配。
+ */
+export function classifyCommentRegion(region) {
+    const out = [];
+    const lines = region.text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const m = DEBT_REGEX.exec(line);
+        if (!m)
+            continue;
+        const kind = m[1].toUpperCase();
+        const owner = (m[2] ?? m[3]) ?? null;
+        const text = (m[4] ?? '').trim();
+        out.push({
+            kind,
+            severity: SEVERITY_MAP[kind],
+            text,
+            owner,
+            lineOffset: i,
+        });
+    }
+    return out;
+}
+//# sourceMappingURL=debt-classifier.js.map

package/dist/debt-scanner/comments/debt-classifier.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debt-classifier.js","sourceRoot":"","sources":["../../../src/debt-scanner/comments/debt-classifier.ts"],"names":[],"mappings":"AAUA,yBAAyB;AACzB,MAAM,CAAC,MAAM,YAAY,GAA6C,MAAM,CAAC,MAAM,CAAC;IAClF,KAAK,EAAE,UAAU;IACjB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,SAAS;IACf,GAAG,EAAE,eAAe;IACpB,IAAI,EAAE,eAAe;CACtB,CAAC,CAAC;AAEH,kDAAkD;AAClD,MAAM,CAAC,MAAM,cAAc,GAA2C,MAAM,CAAC,MAAM,CAAC;IAClF,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,aAAa,EAAE,CAAC;CACjB,CAAC,CAAC;AAEH;;;;;;;;;GASG;AACH,MAAM,UAAU,GAAG,qFAAqF,CAAC;AAazG;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAqB;IACzD,MAAM,GAAG,GAAqB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACtC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACvB,MAAM,CAAC,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAChC,IAAI,CAAC,CAAC;YAAE,SAAS;QACjB,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,EAAc,CAAC;QAC7C,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC;QACrC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QACjC,GAAG,CAAC,IAAI,CAAC;YACP,IAAI;YACJ,QAAQ,EAAE,YAAY,CAAC,IAAI,CAAC;YAC5B,IAAI;YACJ,KAAK;YACL,UAAU,EAAE,CAAC;SACd,CAAC,CAAC;IACL,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/debt-scanner/comments/index.d.ts

@@ -0,0 +1,32 @@
+import type { LanguageAdapterRegistry } from '../../adapters/language-adapter-registry.js';
+import type { CodeDebtEntry } from '../types.js';
+export interface ScanCodeCommentsOptions {
+    /** 项目根，用于把绝对路径转为相对路径 */
+    projectRoot: string;
+    /** 将要扫描的源文件绝对路径列表 */
+    files: string[];
+    /** 语言适配器注册中心 */
+    registry: LanguageAdapterRegistry;
+    /** 可选：自定义 blame 实现，测试时可注入 */
+    blame?: (filePath: string, line: number) => Promise<{
+        author: string;
+        ageDays: number;
+    }>;
+    /** 可选：日志回调 */
+    logger?: {
+        debug?: (msg: string) => void;
+        warn?: (msg: string) => void;
+    };
+}
+export interface ScanCodeCommentsResult {
+    entries: CodeDebtEntry[];
+    filesScanned: number;
+    filesSkipped: number;
+    totalLoc: number;
+    messages: string[];
+}
+/**
+ * 扫描代码注释，产生 CodeDebtEntry 列表。
+ */
+export declare function scanCodeComments(opts: ScanCodeCommentsOptions): Promise<ScanCodeCommentsResult>;
+//# sourceMappingURL=index.d.ts.map

package/dist/debt-scanner/comments/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/debt-scanner/comments/index.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,6CAA6C,CAAC;AAG3F,OAAO,KAAK,EAAE,aAAa,EAAiB,MAAM,aAAa,CAAC;AAIhE,MAAM,WAAW,uBAAuB;IACtC,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,qBAAqB;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,gBAAgB;IAChB,QAAQ,EAAE,uBAAuB,CAAC;IAClC,6BAA6B;IAC7B,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACzF,cAAc;IACd,MAAM,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;KAAE,CAAC;CAC1E;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,aAAa,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,uBAAuB,GAC5B,OAAO,CAAC,sBAAsB,CAAC,CAyFjC"}

package/dist/debt-scanner/comments/index.js

@@ -0,0 +1,103 @@
+/**
+ * 代码注释债务扫描主入口
+ *
+ * 遍历源文件 → 调用 adapter.extractComments → debt-classifier 分类 →
+ * symbol-resolver 定位符号 → git-blame 获取作者与年龄 → 产生 CodeDebtEntry。
+ */
+import * as path from 'node:path';
+import { getLineBlame } from '../../utils/git-blame.js';
+import { classifyCommentRegion, SEVERITY_ORDER } from './debt-classifier.js';
+import { resolveEnclosingSymbol } from './symbol-resolver.js';
+/**
+ * 扫描代码注释，产生 CodeDebtEntry 列表。
+ */
+export async function scanCodeComments(opts) {
+    const messages = [];
+    let filesScanned = 0;
+    let filesSkipped = 0;
+    let totalLoc = 0;
+    const entries = [];
+    const blameFn = opts.blame ?? (async (f, l) => {
+        const info = await getLineBlame(f, l);
+        return { author: info.author, ageDays: info.ageDays };
+    });
+    for (const file of opts.files) {
+        const adapter = opts.registry.getAdapter(file);
+        if (!adapter) {
+            filesSkipped++;
+            continue;
+        }
+        if (typeof adapter.extractComments !== 'function') {
+            filesSkipped++;
+            messages.push(`adapter ${adapter.id} 未实现 extractComments，跳过 ${path.relative(opts.projectRoot, file)}`);
+            continue;
+        }
+        let regions;
+        try {
+            regions = await adapter.extractComments(file);
+        }
+        catch (err) {
+            filesSkipped++;
+            messages.push(`extractComments 失败 (${adapter.id}) ${path.relative(opts.projectRoot, file)}: ${err.message}`);
+            continue;
+        }
+        filesScanned++;
+        // 统计 LOC（尽量不重新 analyze 避免性能代价；用文件实际行数近似）
+        try {
+            const fs = await import('node:fs');
+            const text = fs.readFileSync(file, 'utf-8');
+            totalLoc += Math.max(1, text.split('\n').length);
+        }
+        catch {
+            // 读文件失败忽略
+        }
+        // 解析符号需要 skeleton —— 懒加载：仅当该文件确实有 debt 时才跑 analyzeFile
+        let skeleton = null;
+        let skeletonAttempted = false;
+        for (const region of regions) {
+            const classified = classifyCommentRegion(region);
+            if (classified.length === 0)
+                continue;
+            if (!skeletonAttempted) {
+                skeletonAttempted = true;
+                try {
+                    skeleton = await adapter.analyzeFile(file);
+                }
+                catch {
+                    skeleton = null;
+                }
+            }
+            for (const c of classified) {
+                const line = region.startLine + c.lineOffset;
+                const blame = await blameFn(file, line);
+                const relPath = toPosix(path.relative(opts.projectRoot, file));
+                entries.push({
+                    kind: c.kind,
+                    severity: c.severity,
+                    text: c.text,
+                    filePath: relPath,
+                    line,
+                    symbol: resolveEnclosingSymbol(skeleton, line),
+                    author: blame.author,
+                    ageDays: blame.ageDays,
+                });
+            }
+        }
+    }
+    // NFR-2 稳定排序：severity asc, age desc, file, line
+    entries.sort((a, b) => {
+        const s = SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];
+        if (s !== 0)
+            return s;
+        if (b.ageDays !== a.ageDays)
+            return b.ageDays - a.ageDays;
+        if (a.filePath !== b.filePath)
+            return a.filePath < b.filePath ? -1 : 1;
+        return a.line - b.line;
+    });
+    return { entries, filesScanned, filesSkipped, totalLoc, messages };
+}
+function toPosix(p) {
+    return p.split(path.sep).join('/');
+}
+//# sourceMappingURL=index.js.map

package/dist/debt-scanner/comments/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/debt-scanner/comments/index.ts"],"names":[],"mappings":"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"}

package/dist/debt-scanner/comments/symbol-resolver.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 根据行号定位最近的 enclosing 符号名称。
+ *
+ * 输入：CodeSkeleton（特别是 exports 列表，每项含 startLine/endLine）
+ * 输出：最近包含该行的符号名称，无则 null
+ *
+ * 解析策略：
+ * 1. 在 exports 列表里找所有 [startLine, endLine] 包含 line 的条目
+ * 2. 若多个嵌套（如 class > method），选择范围最小的那个（更具体）
+ * 3. 对于 class：如果 members 有精确的行号（部分 mapper 可能未填），优先选用
+ *    当前实现仅基于顶层 exports，足以满足 "最近符号" 的合理近似。
+ */
+import type { CodeSkeleton } from '../../models/code-skeleton.js';
+/**
+ * 返回最近包围 line 的 export 符号名称。
+ */
+export declare function resolveEnclosingSymbol(skeleton: CodeSkeleton | null, line: number): string | null;
+//# sourceMappingURL=symbol-resolver.d.ts.map

package/dist/debt-scanner/comments/symbol-resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-resolver.d.ts","sourceRoot":"","sources":["../../../src/debt-scanner/comments/symbol-resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,YAAY,EAAgB,MAAM,+BAA+B,CAAC;AAEhF;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,YAAY,GAAG,IAAI,EAC7B,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAYf"}

package/dist/debt-scanner/comments/symbol-resolver.js

@@ -0,0 +1,18 @@
+/**
+ * 返回最近包围 line 的 export 符号名称。
+ */
+export function resolveEnclosingSymbol(skeleton, line) {
+    if (!skeleton)
+        return null;
+    let best = null;
+    for (const exp of skeleton.exports) {
+        if (line >= exp.startLine && line <= exp.endLine) {
+            // 选择行范围最小的（最内层嵌套）
+            if (!best || exp.endLine - exp.startLine < best.endLine - best.startLine) {
+                best = exp;
+            }
+        }
+    }
+    return best ? best.name : null;
+}
+//# sourceMappingURL=symbol-resolver.js.map

package/dist/debt-scanner/comments/symbol-resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"symbol-resolver.js","sourceRoot":"","sources":["../../../src/debt-scanner/comments/symbol-resolver.ts"],"names":[],"mappings":"AAcA;;GAEG;AACH,MAAM,UAAU,sBAAsB,CACpC,QAA6B,EAC7B,IAAY;IAEZ,IAAI,CAAC,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3B,IAAI,IAAI,GAAwB,IAAI,CAAC;IACrC,KAAK,MAAM,GAAG,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACnC,IAAI,IAAI,IAAI,GAAG,CAAC,SAAS,IAAI,IAAI,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC;YACjD,kBAAkB;YAClB,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,OAAO,GAAG,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,CAAC,SAAS,EAAE,CAAC;gBACzE,IAAI,GAAG,GAAG,CAAC;YACb,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;AACjC,CAAC"}

package/dist/debt-scanner/design-docs/doc-discoverer.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 扫描 projectRoot 及一级子目录下的 design-doc。
+ * 返回绝对路径列表（已稳定排序）。
+ */
+export declare function discoverDesignDocs(projectRoot: string): string[];
+//# sourceMappingURL=doc-discoverer.d.ts.map

package/dist/debt-scanner/design-docs/doc-discoverer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-discoverer.d.ts","sourceRoot":"","sources":["../../../src/debt-scanner/design-docs/doc-discoverer.ts"],"names":[],"mappings":"AAYA;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CAchE"}

package/dist/debt-scanner/design-docs/doc-discoverer.js

@@ -0,0 +1,62 @@
+/**
+ * Design-doc 发现
+ *
+ * 扫描 projectRoot 及其一级子目录，找出文件名匹配
+ * README.md / architecture.md / notes.md / design.md（大小写不敏感）的文档。
+ * AC-2.1。
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+const CANDIDATE_BASENAMES = new Set(['readme', 'architecture', 'notes', 'design']);
+/**
+ * 扫描 projectRoot 及一级子目录下的 design-doc。
+ * 返回绝对路径列表（已稳定排序）。
+ */
+export function discoverDesignDocs(projectRoot) {
+    const abs = path.resolve(projectRoot);
+    const out = [];
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory())
+        return out;
+    collectInDir(abs, out);
+    for (const entry of safeReaddir(abs)) {
+        const child = path.join(abs, entry.name);
+        if (entry.isDirectory() && !shouldSkipDir(entry.name)) {
+            collectInDir(child, out);
+        }
+    }
+    out.sort();
+    return out;
+}
+function collectInDir(dir, out) {
+    for (const entry of safeReaddir(dir)) {
+        if (!entry.isFile())
+            continue;
+        const name = entry.name.toLowerCase();
+        if (!name.endsWith('.md'))
+            continue;
+        const base = name.slice(0, -3); // 去掉 .md
+        if (CANDIDATE_BASENAMES.has(base)) {
+            out.push(path.join(dir, entry.name));
+        }
+    }
+}
+function safeReaddir(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+}
+function shouldSkipDir(name) {
+    if (name.startsWith('.'))
+        return true;
+    return (name === 'node_modules' ||
+        name === 'dist' ||
+        name === 'build' ||
+        name === 'out' ||
+        name === 'target' ||
+        name === 'vendor' ||
+        name === '__pycache__');
+}
+//# sourceMappingURL=doc-discoverer.js.map

package/dist/debt-scanner/design-docs/doc-discoverer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doc-discoverer.js","sourceRoot":"","sources":["../../../src/debt-scanner/design-docs/doc-discoverer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAElC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEnF;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,WAAmB;IACpD,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;IACtC,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,WAAW,EAAE;QAAE,OAAO,GAAG,CAAC;IAEvE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IACvB,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,MAAM,KAAK,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QACzC,IAAI,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACtD,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,GAAG,CAAC,IAAI,EAAE,CAAC;IACX,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,YAAY,CAAC,GAAW,EAAE,GAAa;IAC9C,KAAK,MAAM,KAAK,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;QACrC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE;YAAE,SAAS;QAC9B,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;QACtC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,SAAS;QACpC,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS;QACzC,IAAI,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,GAAW;IAC9B,IAAI,CAAC;QACH,OAAO,EAAE,CAAC,WAAW,CAAC,GAAG,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;IACtD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,IAAY;IACjC,IAAI,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,CACL,IAAI,KAAK,cAAc;QACvB,IAAI,KAAK,MAAM;QACf,IAAI,KAAK,OAAO;QAChB,IAAI,KAAK,KAAK;QACd,IAAI,KAAK,QAAQ;QACjB,IAAI,KAAK,QAAQ;QACjB,IAAI,KAAK,aAAa,CACvB,CAAC;AACJ,CAAC"}

package/dist/debt-scanner/design-docs/index.d.ts

@@ -0,0 +1,28 @@
+import type { OpenQuestionEntry } from '../types.js';
+import { discoverDesignDocs } from './doc-discoverer.js';
+import { parseMarkdownSections, type Section } from './markdown-sections.js';
+export interface OpenQuestionCandidate {
+    /** 来源文档绝对路径 */
+    absPath: string;
+    /** 相对 projectRoot 的路径 */
+    docPath: string;
+    /** heading path */
+    headingPath: string;
+    /** 原文片段 */
+    snippet: string;
+}
+export interface DetectOpenQuestionsResult {
+    /** 规则命中的 confirmed 条目 */
+    confirmed: OpenQuestionEntry[];
+    /** 疑问句命中的 LLM 待仲裁候选 */
+    llmCandidates: OpenQuestionCandidate[];
+    /** 扫描的文档数 */
+    docsScanned: number;
+}
+/**
+ * 扫描 projectRoot 的 design-doc，提取 open question 候选。
+ */
+export declare function detectOpenQuestions(projectRoot: string): DetectOpenQuestionsResult;
+export { discoverDesignDocs, parseMarkdownSections };
+export type { Section };
+//# sourceMappingURL=index.d.ts.map

package/dist/debt-scanner/design-docs/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/debt-scanner/design-docs/index.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,qBAAqB,EAAE,KAAK,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAG7E,MAAM,WAAW,qBAAqB;IACpC,eAAe;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,mBAAmB;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW;IACX,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,yBAAyB;IACxC,yBAAyB;IACzB,SAAS,EAAE,iBAAiB,EAAE,CAAC;IAC/B,uBAAuB;IACvB,aAAa,EAAE,qBAAqB,EAAE,CAAC;IACvC,aAAa;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,GAAG,yBAAyB,CAwClF;AAMD,OAAO,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,CAAC;AACrD,YAAY,EAAE,OAAO,EAAE,CAAC"}