spectra-cli 4.1.1

package/dist/debt-scanner/index.js

@@ -0,0 +1,177 @@
+/**
+ * debt-scanner 模块主入口
+ *
+ * scanProjectDebt：整合代码注释扫描 + design-doc open-question 检测，
+ * 产出统一的 DebtReport。
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { scanCodeComments } from './comments/index.js';
+import { detectOpenQuestions } from './design-docs/index.js';
+import { inferOpenQuestionTopics, } from './design-docs/llm-topic-inferrer.js';
+const EMPTY_KIND_COUNTS = {
+    TODO: 0,
+    FIXME: 0,
+    HACK: 0,
+    XXX: 0,
+    NOTE: 0,
+};
+/**
+ * 扫描 projectRoot，返回完整 DebtReport。
+ */
+export async function scanProjectDebt(opts) {
+    const t0 = Date.now();
+    const projectRoot = path.resolve(opts.projectRoot);
+    // ── 1. 枚举源文件（遵守 languages 过滤）──
+    const files = opts.files ?? enumerateSourceFiles(projectRoot, opts.registry, opts.languages);
+    // ── 2. 代码注释扫描 ──
+    const codeRes = await scanCodeComments({
+        projectRoot,
+        files,
+        registry: opts.registry,
+        blame: opts.blame,
+    });
+    // ── 3. Design-doc open questions ──
+    const dd = detectOpenQuestions(projectRoot);
+    const llm = await inferOpenQuestionTopics({
+        confirmed: dd.confirmed,
+        llmCandidates: dd.llmCandidates,
+        llmClient: opts.llmClient,
+        budgetLimit: opts.budgetLimit,
+        dryRun: opts.dryRun,
+    });
+    // ── 4. 汇总 ──
+    const codeEntries = codeRes.entries;
+    const openQuestions = llm.entries;
+    const metrics = buildMetrics(codeEntries, openQuestions, codeRes.totalLoc);
+    const diagnostics = {
+        filesScanned: codeRes.filesScanned,
+        filesSkipped: codeRes.filesSkipped,
+        totalLoc: codeRes.totalLoc,
+        llmCalls: llm.llmCalls,
+        docsScanned: dd.docsScanned,
+        ruleCandidates: dd.confirmed.length,
+        llmCandidates: dd.llmCandidates.length,
+        messages: codeRes.messages,
+    };
+    return {
+        codeEntries,
+        openQuestions,
+        diagnostics,
+        metrics,
+        tokenUsage: llm.tokenUsage,
+        durationMs: Date.now() - t0,
+        llmModel: llm.llmModel,
+        fallbackReason: llm.fallbackReason,
+    };
+}
+function buildMetrics(codeEntries, openQuestions, totalLoc) {
+    const byKind = { ...EMPTY_KIND_COUNTS };
+    let oldestAgeDays = 0;
+    for (const e of codeEntries) {
+        byKind[e.kind]++;
+        if (e.ageDays > oldestAgeDays)
+            oldestAgeDays = e.ageDays;
+    }
+    const densityPerKloc = totalLoc > 0 ? (codeEntries.length / totalLoc) * 1000 : 0;
+    return {
+        totalEntries: codeEntries.length,
+        byKind,
+        densityPerKloc,
+        oldestAgeDays,
+        openQuestionsCount: openQuestions.length,
+    };
+}
+/**
+ * 枚举项目中所有受支持的源文件，跳过 defaultIgnoreDirs 与常见构建目录。
+ * 当 languageFilter 非空时，只接受这些 adapter id 支持的扩展名。
+ */
+function enumerateSourceFiles(projectRoot, registry, languageFilter) {
+    const out = [];
+    const ignoreDirs = new Set(registry.getDefaultIgnoreDirs());
+    // 通用忽略
+    for (const d of ['.git', 'node_modules', 'dist', 'build', 'out'])
+        ignoreDirs.add(d);
+    const supportedExts = resolveAllowedExtensions(registry, languageFilter);
+    function walk(dir) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.name.startsWith('.'))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (!ignoreDirs.has(entry.name))
+                    walk(full);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            const ext = path.extname(entry.name).toLowerCase();
+            if (supportedExts.has(ext))
+                out.push(full);
+        }
+    }
+    walk(projectRoot);
+    // 稳定排序
+    out.sort();
+    return out;
+}
+/**
+ * 根据 languageFilter 计算实际可接受的扩展名集合。
+ * 过滤器为空/undefined 时返回全部受支持扩展名（向后兼容）。
+ * 过滤器中 adapter id 不存在时会被静默忽略（行为与 batch language-grouper 一致）。
+ */
+function resolveAllowedExtensions(registry, languageFilter) {
+    if (!languageFilter || languageFilter.length === 0) {
+        return registry.getSupportedExtensions();
+    }
+    const allowed = new Set();
+    const adapters = registry.getAllAdapters();
+    const idSet = new Set(languageFilter);
+    for (const a of adapters) {
+        if (idSet.has(a.id)) {
+            for (const ext of a.extensions)
+                allowed.add(ext);
+        }
+    }
+    return allowed;
+}
+/**
+ * 根据 languageFilter 返回人类可读的语言标签（报告使用）。
+ * 过滤器为空时覆盖全部已注册 adapter；否则仅列出过滤集合中的 adapter。
+ */
+export function describeScannedLanguages(registry, languageFilter) {
+    const adapters = registry.getAllAdapters();
+    const idSet = languageFilter && languageFilter.length > 0 ? new Set(languageFilter) : null;
+    const labels = new Set();
+    for (const a of adapters) {
+        if (idSet && !idSet.has(a.id))
+            continue;
+        labels.add(adapterIdToLabel(a.id));
+    }
+    return Array.from(labels).sort();
+}
+function adapterIdToLabel(id) {
+    switch (id) {
+        case 'ts-js':
+            return 'typescript/javascript';
+        case 'python':
+            return 'python';
+        case 'go':
+            return 'go';
+        case 'java':
+            return 'java';
+        default:
+            return id;
+    }
+}
+export { buildDebtReportFromReport } from './aggregator/report-builder.js';
+export { patchQualityReportWithDebt, findQualityReportPath, renderDebtSection } from './aggregator/quality-report-patcher.js';
+export { indexDebtInReadme } from './aggregator/readme-indexer.js';
+//# sourceMappingURL=index.js.map

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

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

package/dist/debt-scanner/llm-clients.d.ts

@@ -0,0 +1,33 @@
+import type { SimpleLLMClient, SimpleLLMInput, SimpleLLMOutput } from './design-docs/llm-topic-inferrer.js';
+export interface AnthropicClientOptions {
+    apiKey?: string;
+    model?: string;
+    timeoutMs?: number;
+}
+/** 生产实现：直接用 Anthropic SDK */
+export declare class AnthropicLLMClient implements SimpleLLMClient {
+    readonly model: string;
+    private readonly client;
+    private readonly timeoutMs;
+    constructor(opts?: AnthropicClientOptions);
+    complete(input: SimpleLLMInput): Promise<SimpleLLMOutput>;
+    estimateTokens(text: string): number;
+}
+/**
+ * 若环境中存在 ANTHROPIC_API_KEY 且未注入显式 client，则返回默认 AnthropicLLMClient；
+ * 否则返回 undefined（调用方进入 no-llm-client 降级，仍产出规则命中的 open questions）。
+ *
+ * 目的：让 CLI/MCP 等主入口无需重复实例化；仅通过环境变量即可启用 LLM 主题推断。
+ * 对 CLI-proxy / Codex-proxy 路径（不设置 API_KEY 的用户）会降级到规则 only，这是有意保守的行为。
+ */
+export declare function tryCreateDefaultLLMClient(): SimpleLLMClient | undefined;
+/** 测试实现：按预设脚本返回响应 */
+export declare class StubLLMClient implements SimpleLLMClient {
+    private readonly responder;
+    readonly model = "stub-llm";
+    calls: SimpleLLMInput[];
+    constructor(responder: (input: SimpleLLMInput) => SimpleLLMOutput | Promise<SimpleLLMOutput>);
+    complete(input: SimpleLLMInput): Promise<SimpleLLMOutput>;
+    estimateTokens(text: string): number;
+}
+//# sourceMappingURL=llm-clients.d.ts.map

package/dist/debt-scanner/llm-clients.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-clients.d.ts","sourceRoot":"","sources":["../../src/debt-scanner/llm-clients.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAE5G,MAAM,WAAW,sBAAsB;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,6BAA6B;AAC7B,qBAAa,kBAAmB,YAAW,eAAe;IACxD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,IAAI,GAAE,sBAA2B;IAQvC,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAmB/D,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAKrC;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,IAAI,eAAe,GAAG,SAAS,CAOvE;AAED,qBAAqB;AACrB,qBAAa,aAAc,YAAW,eAAe;IAIjD,OAAO,CAAC,QAAQ,CAAC,SAAS;IAH5B,QAAQ,CAAC,KAAK,cAAc;IACrB,KAAK,EAAE,cAAc,EAAE,CAAM;gBAEjB,SAAS,EAAE,CAAC,KAAK,EAAE,cAAc,KAAK,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC;IAG7F,QAAQ,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAK/D,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM;CAGrC"}

package/dist/debt-scanner/llm-clients.js

@@ -0,0 +1,78 @@
+/**
+ * debt-scanner 的 SimpleLLMClient 适配器
+ *
+ * - AnthropicLLMClient：生产实现，直接包装 @anthropic-ai/sdk
+ * - StubLLMClient：测试用，返回预设响应
+ */
+import Anthropic from '@anthropic-ai/sdk';
+/** 生产实现：直接用 Anthropic SDK */
+export class AnthropicLLMClient {
+    model;
+    client;
+    timeoutMs;
+    constructor(opts = {}) {
+        const apiKey = opts.apiKey ?? process.env['ANTHROPIC_API_KEY'];
+        if (!apiKey)
+            throw new Error('AnthropicLLMClient 需要 ANTHROPIC_API_KEY');
+        this.model = opts.model ?? 'claude-haiku-4-5';
+        this.timeoutMs = opts.timeoutMs ?? 60_000;
+        this.client = new Anthropic({ apiKey, timeout: this.timeoutMs });
+    }
+    async complete(input) {
+        const res = await this.client.messages.create({
+            model: this.model,
+            max_tokens: input.maxOutputTokens,
+            system: input.systemPrompt,
+            messages: [{ role: 'user', content: input.userPrompt }],
+        });
+        const text = res.content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join('\n');
+        return {
+            text,
+            inputTokens: res.usage.input_tokens,
+            outputTokens: res.usage.output_tokens,
+            model: res.model,
+        };
+    }
+    estimateTokens(text) {
+        // 粗略估算：英文 ~4 char/token，中文 ~2 char/token。
+        // 对 budget 预检来说 ±20% 误差可以接受。
+        return Math.ceil(text.length / 3.5);
+    }
+}
+/**
+ * 若环境中存在 ANTHROPIC_API_KEY 且未注入显式 client，则返回默认 AnthropicLLMClient；
+ * 否则返回 undefined（调用方进入 no-llm-client 降级，仍产出规则命中的 open questions）。
+ *
+ * 目的：让 CLI/MCP 等主入口无需重复实例化；仅通过环境变量即可启用 LLM 主题推断。
+ * 对 CLI-proxy / Codex-proxy 路径（不设置 API_KEY 的用户）会降级到规则 only，这是有意保守的行为。
+ */
+export function tryCreateDefaultLLMClient() {
+    if (!process.env['ANTHROPIC_API_KEY'])
+        return undefined;
+    try {
+        return new AnthropicLLMClient();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 测试实现：按预设脚本返回响应 */
+export class StubLLMClient {
+    responder;
+    model = 'stub-llm';
+    calls = [];
+    constructor(responder) {
+        this.responder = responder;
+    }
+    async complete(input) {
+        this.calls.push(input);
+        return this.responder(input);
+    }
+    estimateTokens(text) {
+        return Math.ceil(text.length / 4);
+    }
+}
+//# sourceMappingURL=llm-clients.js.map

package/dist/debt-scanner/llm-clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-clients.js","sourceRoot":"","sources":["../../src/debt-scanner/llm-clients.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,SAAS,MAAM,mBAAmB,CAAC;AAS1C,6BAA6B;AAC7B,MAAM,OAAO,kBAAkB;IACpB,KAAK,CAAS;IACN,MAAM,CAAY;IAClB,SAAS,CAAS;IAEnC,YAAY,OAA+B,EAAE;QAC3C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACxE,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,kBAAkB,CAAC;QAC9C,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,MAAM,CAAC;QAC1C,IAAI,CAAC,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC;IACnE,CAAC;IAED,KAAK,CAAC,QAAQ,CAAC,KAAqB;QAClC,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YAC5C,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,UAAU,EAAE,KAAK,CAAC,eAAe;YACjC,MAAM,EAAE,KAAK,CAAC,YAAY;YAC1B,QAAQ,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,CAAC,UAAU,EAAE,CAAC;SACxD,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO;aACrB,MAAM,CAAC,CAAC,CAAC,EAA4B,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,MAAM,CAAC;aAC1D,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;aAClB,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,OAAO;YACL,IAAI;YACJ,WAAW,EAAE,GAAG,CAAC,KAAK,CAAC,YAAY;YACnC,YAAY,EAAE,GAAG,CAAC,KAAK,CAAC,aAAa;YACrC,KAAK,EAAE,GAAG,CAAC,KAAK;SACjB,CAAC;IACJ,CAAC;IAED,cAAc,CAAC,IAAY;QACzB,0CAA0C;QAC1C,6BAA6B;QAC7B,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC;IACtC,CAAC;CACF;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB;IACvC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC;QAAE,OAAO,SAAS,CAAC;IACxD,IAAI,CAAC;QACH,OAAO,IAAI,kBAAkB,EAAE,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC;AAED,qBAAqB;AACrB,MAAM,OAAO,aAAa;IAIL;IAHV,KAAK,GAAG,UAAU,CAAC;IACrB,KAAK,GAAqB,EAAE,CAAC;IACpC,YACmB,SAAgF;QAAhF,cAAS,GAAT,SAAS,CAAuE;IAChG,CAAC;IAEJ,KAAK,CAAC,QAAQ,CAAC,KAAqB;QAClC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAED,cAAc,CAAC,IAAY;QACzB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IACpC,CAAC;CACF"}

package/dist/debt-scanner/types.d.ts

@@ -0,0 +1,97 @@
+/**
+ * F3 Debt Intelligence — 核心类型定义
+ *
+ * 暴露于 debt-scanner 模块和 panoramic pipelines 之间的共享合同类型。
+ */
+/**
+ * LanguageAdapter.extractComments 返回的注释 region。
+ * 由各语言 adapter 使用 AST 提取（不会包含字符串字面量里的"TODO"）。
+ */
+export interface CommentRegion {
+    /** 行注释或块注释 */
+    kind: 'line' | 'block';
+    /** 已去掉注释起始/结束标记的文本；多行块注释保留内部换行 */
+    text: string;
+    /** 1-indexed 起始行 */
+    startLine: number;
+    /** 1-indexed 结束行（行注释等于 startLine） */
+    endLine: number;
+}
+/** 债务 kind 分类 */
+export type DebtKind = 'TODO' | 'FIXME' | 'HACK' | 'XXX' | 'NOTE';
+/** 严重性映射 */
+export type DebtSeverity = 'critical' | 'warning' | 'informational';
+/** 代码注释债务条目 */
+export interface CodeDebtEntry {
+    kind: DebtKind;
+    severity: DebtSeverity;
+    /** 原始注释文本（已剥离 kind 前缀） */
+    text: string;
+    /** 相对于 projectRoot 的路径 */
+    filePath: string;
+    /** 1-indexed 行号（匹配发生的那一行） */
+    line: number;
+    /** 最近的 enclosing 符号名称，无则 null */
+    symbol: string | null;
+    /** git blame 得到的作者；uncommitted 时为 "uncommitted" */
+    author: string;
+    /** commit 距今天数；uncommitted 时为 0 */
+    ageDays: number;
+}
+/** Design-doc 开放问题 */
+export interface OpenQuestionEntry {
+    /** 原文片段，最长 400 字符 */
+    snippet: string;
+    /** 相对 projectRoot 的文档路径 */
+    docPath: string;
+    /** 标题路径，如 "## Open Questions > Q1" */
+    headingPath: string;
+    /** 触发原因：规则命中或 LLM 判定 */
+    source: 'rule' | 'llm';
+    /** LLM 推断的主题，1-3 个短词；未推断时为空数组 */
+    topics: string[];
+}
+/** 扫描过程的 diagnostics */
+export interface DebtDiagnostics {
+    /** 实际 AST 扫描的源文件数 */
+    filesScanned: number;
+    /** 因未支持的语言跳过的文件数 */
+    filesSkipped: number;
+    /** AST 扫描的总行数（用于债务密度） */
+    totalLoc: number;
+    /** LLM 调用次数 */
+    llmCalls: number;
+    /** 扫描到的 design-doc 数 */
+    docsScanned: number;
+    /** 规则命中的候选数 */
+    ruleCandidates: number;
+    /** 需要 LLM 仲裁的候选数 */
+    llmCandidates: number;
+    /** 其它消息 */
+    messages: string[];
+}
+/** 汇总指标，给 quality-report patcher 使用 */
+export interface DebtMetrics {
+    totalEntries: number;
+    byKind: Record<DebtKind, number>;
+    densityPerKloc: number;
+    oldestAgeDays: number;
+    openQuestionsCount: number;
+}
+export interface TokenUsage {
+    input: number;
+    output: number;
+}
+/** 完整 debt-scanner 报告 */
+export interface DebtReport {
+    codeEntries: CodeDebtEntry[];
+    openQuestions: OpenQuestionEntry[];
+    diagnostics: DebtDiagnostics;
+    metrics: DebtMetrics;
+    tokenUsage: TokenUsage;
+    durationMs: number;
+    llmModel?: string;
+    /** 为何走降级；undefined 表示未降级 */
+    fallbackReason?: 'budget-exhausted' | 'dry-run' | 'no-llm-client';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/debt-scanner/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/debt-scanner/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,cAAc;IACd,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,oBAAoB;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,qCAAqC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,iBAAiB;AACjB,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,CAAC;AAElE,YAAY;AACZ,MAAM,MAAM,YAAY,GAAG,UAAU,GAAG,SAAS,GAAG,eAAe,CAAC;AAEpE,eAAe;AACf,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,YAAY,CAAC;IACvB,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,mDAAmD;IACnD,MAAM,EAAE,MAAM,CAAC;IACf,mCAAmC;IACnC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,sBAAsB;AACtB,MAAM,WAAW,iBAAiB;IAChC,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IACvB,iCAAiC;IACjC,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAwB;AACxB,MAAM,WAAW,eAAe;IAC9B,qBAAqB;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,oBAAoB;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,eAAe;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,wBAAwB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,oBAAoB;IACpB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW;IACX,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;IACtB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,yBAAyB;AACzB,MAAM,WAAW,UAAU;IACzB,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,4BAA4B;IAC5B,cAAc,CAAC,EAAE,kBAAkB,GAAG,SAAS,GAAG,eAAe,CAAC;CACnE"}

package/dist/debt-scanner/types.js

@@ -0,0 +1,7 @@
+/**
+ * F3 Debt Intelligence — 核心类型定义
+ *
+ * 暴露于 debt-scanner 模块和 panoramic pipelines 之间的共享合同类型。
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/debt-scanner/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/debt-scanner/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/diff/drift-orchestrator.d.ts

@@ -0,0 +1,25 @@
+import { type CodeSkeleton } from '../models/code-skeleton.js';
+import type { DriftReport } from '../models/module-spec.js';
+export interface DriftOptions {
+    /** 跳过 LLM 语义评估，仅进行结构差异检测 */
+    skipSemantic?: boolean;
+    /** 自定义输出目录（默认：drift-logs/） */
+    outputDir?: string;
+}
+/**
+ * 从现有 spec 文件内容中提取序列化的基线 CodeSkeleton
+ *
+ * @param specContent - spec 文件的原始文本内容
+ * @returns CodeSkeleton，parserUsed 指示来源
+ */
+export declare function loadBaselineSkeleton(specContent: string): CodeSkeleton;
+/**
+ * 端到端漂移检测编排器
+ *
+ * @param specPath - 现有 spec 文件路径
+ * @param sourcePath - 当前源代码文件或目录路径
+ * @param options - 漂移检测选项
+ * @returns 完整的 DriftReport
+ */
+export declare function detectDrift(specPath: string, sourcePath: string, options?: DriftOptions): Promise<DriftReport>;
+//# sourceMappingURL=drift-orchestrator.d.ts.map

package/dist/diff/drift-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift-orchestrator.d.ts","sourceRoot":"","sources":["../../src/diff/drift-orchestrator.ts"],"names":[],"mappings":"AAOA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAEnF,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAY5D,MAAM,WAAW,YAAY;IAC3B,4BAA4B;IAC5B,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,8BAA8B;IAC9B,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,YAAY,CAgBtE;AA+DD;;;;;;;GAOG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,YAAiB,GACzB,OAAO,CAAC,WAAW,CAAC,CA2FtB"}