@dommaker/harness 0.16.6 → 0.16.8

package/dist/cli/commands/sync-docs/index.js

@@ -0,0 +1,338 @@
+"use strict";
+/**
+ * harness sync-docs 命令（入口编排，工单 22）
+ *
+ * 自动同步项目文档：CAPABILITIES.md、CONTEXT.md 检查、CHANGELOG 辅助
+ * --check 模式输出结构化信息，供 LLM 或 CI 消费
+ *
+ * 实现拆分：
+ * - project-reader.ts       项目信息读取（package.json/config.yml/源码扫描）
+ * - capabilities-syncer.ts  CAPABILITIES.md 两种格式的对比与维护
+ * - context-syncer.ts       CONTEXT.md 模板生成/发现/过时判定
+ * - agents-syncer.ts        AGENTS.md 生成
+ * - preserve-block.ts       PRESERVE 标记块提取与组合
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.syncDocs = syncDocs;
+const chalk_1 = __importDefault(require("chalk"));
+const fs = __importStar(require("fs/promises"));
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const capabilities_parser_1 = require("../../../core/constraints/capabilities-parser");
+const detect_source_roots_1 = require("../../../utils/detect-source-roots");
+const project_reader_1 = require("./project-reader");
+const capabilities_syncer_1 = require("./capabilities-syncer");
+const context_syncer_1 = require("./context-syncer");
+const agents_syncer_1 = require("./agents-syncer");
+const preserve_block_1 = require("./preserve-block");
+/**
+ * 同步文档
+ */
+async function syncDocs(options) {
+    const projectPath = options.projectPath || process.cwd();
+    const isCheck = options.check === true;
+    const isJson = options.json === true;
+    if (!isJson) {
+        if (isCheck) {
+            console.log(chalk_1.default.blue('🔍 检查文档新鲜度...'));
+        }
+        else {
+            console.log(chalk_1.default.blue('📝 同步文档...'));
+        }
+    }
+    const result = {
+        added: [],
+        removed: [],
+        contextMissing: [],
+        contextStale: [],
+    };
+    // 1. 扫描源码模块（从 governance config 读取目录列表，默认 src/）
+    const srcDirs = await (0, project_reader_1.getSourceDirs)(projectPath);
+    let currentModules = [];
+    for (const srcDir of srcDirs) {
+        try {
+            const modules = await (0, project_reader_1.scanSourceModules)(path.join(projectPath, srcDir), projectPath);
+            currentModules.push(...modules);
+        }
+        catch {
+            if (!isJson) {
+                console.log(chalk_1.default.yellow(`⚠️  未找到 ${srcDir} 目录，跳过`));
+            }
+        }
+    }
+    // 2. 解析现有 CAPABILITIES.md，检测格式
+    const capabilitiesPath = path.join(projectPath, 'CAPABILITIES.md');
+    let existingFiles = [];
+    let capsContent = '';
+    let capsIsCapabilityListing = false;
+    try {
+        capsContent = await fs.readFile(capabilitiesPath, 'utf-8');
+        if ((0, capabilities_syncer_1.isCapabilityListingFormat)(capsContent)) {
+            capsIsCapabilityListing = true;
+        }
+        else {
+            existingFiles = await (0, capabilities_syncer_1.parseCapabilitiesFiles)(capabilitiesPath);
+        }
+    }
+    catch {
+        // CAPABILITIES.md 不存在，将创建
+    }
+    // 3. 对比差异（分两种格式）
+    let capCountMismatches = [];
+    if (capsIsCapabilityListing) {
+        // 能力清单格式：委托 FreshnessRunner 对比计数
+        const countCheck = (0, capabilities_syncer_1.checkCapabilityCounts)(projectPath);
+        capCountMismatches = countCheck.mismatches;
+        // 不填充 result.added/removed（文件级对比不适用于此格式）
+    }
+    else {
+        // 传统的文件表格格式
+        const getBasename = (f) => {
+            const clean = f.endsWith('/') ? f.slice(0, -1) : f;
+            return clean.split('/').pop();
+        };
+        const currentBasenames = currentModules.map(m => getBasename(m.file));
+        // 目录条目（如 src/、agents/）按前缀覆盖其中的文件，且不参与 removed 对比
+        // （basename 列表里永远不会有目录，直接对比会把目录行误报为「已删除的模块」）
+        const existingDirs = existingFiles.filter(f => f.endsWith('/'));
+        const existingFileNames = existingFiles.filter(f => !f.endsWith('/'));
+        result.added = currentModules
+            .filter(m => !existingDirs.some(d => m.file.startsWith(d)) &&
+            !existingFileNames.includes(getBasename(m.file)))
+            .map(m => getBasename(m.file));
+        result.removed = existingFileNames.filter(f => !currentBasenames.includes(f));
+        // 幽灵条目清扫（2026-08-08 studio CI 4 连红事故）：上方按 basename 对比，
+        // 同名碰撞时幽灵不可见（如 agent-configs/routes.ts 已删但 agents/routes.ts 仍存在，
+        // basename routes.ts 仍在扫描结果中，永远不会被判 removed）。
+        // 这里按完整路径直接判存在性（与 docs_freshness 检查器同语义：项目根 + 源码根前缀）。
+        const sourceRoots = (0, detect_source_roots_1.detectSourceRoots)(projectPath);
+        const entryExists = (entry) => (0, fs_1.existsSync)(path.join(projectPath, entry)) ||
+            sourceRoots.some(root => (0, fs_1.existsSync)(path.join(projectPath, root, entry)));
+        for (const entry of (0, capabilities_parser_1.readCapabilitiesEntries)(capabilitiesPath)) {
+            // 纯文件名条目（无路径）无法用存在性判定，交由上方 basename 对比
+            if (!entry.includes('/') || entryExists(entry))
+                continue;
+            const basename = entry.split('/').pop();
+            // basename 对比已覆盖（无碰撞场景）时不重复加入
+            if (!result.removed.includes(basename) && !result.removed.includes(entry)) {
+                result.removed.push(entry);
+            }
+        }
+    }
+    // 4. 检查 CONTEXT.md（缺失 + 过时）
+    // 4a. 配置中要求的目录：检查缺失
+    const contextDirs = await (0, project_reader_1.getRequiredContextDirs)(projectPath);
+    for (const dir of contextDirs) {
+        const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
+        try {
+            await fs.access(contextPath);
+        }
+        catch {
+            result.contextMissing.push(dir);
+        }
+    }
+    // 4b. 自动发现已有的 CONTEXT.md：检查过时
+    const existingContextFiles = await (0, context_syncer_1.findExistingContextFiles)(projectPath, srcDirs);
+    for (const dir of existingContextFiles) {
+        const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
+        try {
+            const contextStat = await fs.stat(contextPath);
+            const dirPath = path.join(projectPath, dir);
+            const latestTsMtime = await (0, context_syncer_1.getLatestTsMtime)(dirPath);
+            if (latestTsMtime && latestTsMtime > contextStat.mtimeMs) {
+                result.contextStale.push(dir);
+            }
+        }
+        catch {
+            // 目录不存在或无法访问，跳过
+        }
+    }
+    // 4c. AGENTS.md（--agents 启用）：缺失或内容漂移
+    // 漂移比对基于"生成内容 + 既有 PRESERVE 标记块"的组合结果：
+    // PRESERVE 块原样穿过，块内手改不报漂移；块外手改/仓库状态变化报漂移。
+    let agentsMdExpected = null;
+    let agentsMdExists = false;
+    let agentsMdStale = false;
+    let agentsMdMalformedPreserve = [];
+    if (options.agents) {
+        const generated = await (0, agents_syncer_1.buildAgentsMd)(projectPath, srcDirs);
+        let existing = null;
+        try {
+            existing = await fs.readFile(path.join(projectPath, 'AGENTS.md'), 'utf-8');
+            agentsMdExists = true;
+        }
+        catch {
+            // 缺失视为漂移
+        }
+        const { blocks, malformed } = existing !== null
+            ? (0, preserve_block_1.extractPreserveBlocks)(existing)
+            : { blocks: [], malformed: [] };
+        agentsMdMalformedPreserve = malformed;
+        agentsMdExpected = (0, preserve_block_1.composeAgentsMd)(generated, blocks);
+        agentsMdStale = existing !== agentsMdExpected;
+    }
+    const hasAgentsIssues = options.agents === true && agentsMdStale;
+    const hasTableIssues = result.added.length > 0 || result.removed.length > 0;
+    const hasCapIssues = capCountMismatches.length > 0;
+    const hasContextIssues = result.contextMissing.length > 0 || result.contextStale.length > 0;
+    const hasIssues = hasTableIssues || hasCapIssues || hasContextIssues || hasAgentsIssues;
+    // 5. JSON 输出模式：结构化输出供 LLM 消费
+    if (isJson) {
+        const jsonOutput = {
+            stale: hasIssues,
+            format: capsIsCapabilityListing ? 'capability-listing' : 'file-table',
+            summary: {
+                added: result.added.length,
+                removed: result.removed.length,
+                capCountMismatches: capCountMismatches.length,
+                contextMissing: result.contextMissing.length,
+                contextStale: result.contextStale.length,
+            },
+            contextMissing: result.contextMissing.map(d => ({
+                dir: d,
+                file: `${d}/CONTEXT.md`,
+            })),
+            contextStale: result.contextStale.map(d => ({
+                dir: d,
+                file: `${d}/CONTEXT.md`,
+            })),
+            resolution: [],
+        };
+        if (capsIsCapabilityListing && hasCapIssues) {
+            jsonOutput.capCountMismatches = capCountMismatches.map(m => ({ mismatch: m }));
+            jsonOutput.resolution.push({
+                action: 'sync-capability-counts',
+                command: 'harness sync-docs',
+                details: 'CAPABILITIES.md 计数与代码不一致，运行 harness sync-docs 自动更新',
+            });
+        }
+        if (!capsIsCapabilityListing && hasTableIssues) {
+            jsonOutput.added = result.added.map(f => {
+                const getBasenameLocal = (s) => s.split('/').pop();
+                return {
+                    file: f,
+                    module: currentModules.find(m => getBasenameLocal(m.file) === f),
+                };
+            });
+            jsonOutput.removed = result.removed.map(f => ({ file: f }));
+            jsonOutput.resolution.push({
+                action: 'sync-capabilities',
+                command: 'harness sync-docs',
+            });
+        }
+        if (hasContextIssues) {
+            jsonOutput.resolution.push(...(result.contextMissing.length > 0
+                ? [{ action: 'create-context-md', command: 'harness sync-docs', dirs: result.contextMissing }]
+                : []), ...(result.contextStale.length > 0
+                ? [{ action: 'update-context-md', command: 'harness sync-docs', dirs: result.contextStale }]
+                : []));
+        }
+        if (options.agents) {
+            jsonOutput.agentsMd = { file: 'AGENTS.md', exists: agentsMdExists, stale: agentsMdStale };
+            if (agentsMdStale) {
+                jsonOutput.resolution.push({
+                    action: 'sync-agents-md',
+                    command: 'harness sync-docs --agents',
+                    details: '生成/更新 AGENTS.md（agent 导读）',
+                });
+            }
+        }
+        console.log(JSON.stringify(jsonOutput, null, 2));
+        return !hasIssues;
+    }
+    // 6. 人读输出模式
+    if (capsIsCapabilityListing && hasCapIssues) {
+        console.log(chalk_1.default.yellow(`\n📊 CAPABILITIES.md 计数不一致:`));
+        capCountMismatches.forEach(m => console.log(chalk_1.default.gray(`  - ${m}`)));
+    }
+    if (result.added.length > 0) {
+        console.log(chalk_1.default.yellow(`\n📄 CAPABILITIES.md 缺少以下模块:`));
+        result.added.forEach(f => console.log(chalk_1.default.gray(`  + ${f}`)));
+    }
+    if (result.removed.length > 0) {
+        console.log(chalk_1.default.yellow(`\n📄 CAPABILITIES.md 包含已删除的模块:`));
+        result.removed.forEach(f => console.log(chalk_1.default.gray(`  - ${f}`)));
+    }
+    if (result.contextMissing.length > 0) {
+        console.log(chalk_1.default.yellow(`\n📋 缺少 CONTEXT.md:`));
+        result.contextMissing.forEach(d => console.log(chalk_1.default.gray(`  - ${d}/CONTEXT.md`)));
+    }
+    if (result.contextStale.length > 0) {
+        console.log(chalk_1.default.yellow(`\n📋 CONTEXT.md 可能过时（源码比文档新）:`));
+        result.contextStale.forEach(d => console.log(chalk_1.default.gray(`  - ${d}/CONTEXT.md`)));
+    }
+    if (hasAgentsIssues) {
+        console.log(chalk_1.default.yellow(agentsMdExists
+            ? `\n🤖 AGENTS.md 与当前项目状态不一致:`
+            : `\n🤖 缺少 AGENTS.md（agent 导读）:`));
+        console.log(chalk_1.default.gray(`  - AGENTS.md`));
+    }
+    if (agentsMdMalformedPreserve.length > 0) {
+        console.log(chalk_1.default.yellow(`\n⚠️ AGENTS.md 中 PRESERVE 标记块未闭合（不予保留，重新生成将丢弃）: ${agentsMdMalformedPreserve.join(', ')}`));
+    }
+    if (!hasIssues) {
+        console.log(chalk_1.default.green('✅ 所有文档都是最新的'));
+        return true;
+    }
+    // 7. 检查模式：只报告，不修改
+    if (isCheck) {
+        console.log(chalk_1.default.red('\n❌ 文档不是最新的，请运行 harness sync-docs 更新'));
+        return false;
+    }
+    // 8. 写入模式：更新文档
+    if (capsIsCapabilityListing && hasCapIssues) {
+        capsContent = (0, capabilities_syncer_1.updateCapabilityCounts)(capsContent, projectPath);
+        await fs.writeFile(capabilitiesPath, capsContent, 'utf-8');
+        console.log(chalk_1.default.green(`\n✅ 已更新 CAPABILITIES.md 计数`));
+    }
+    if (!capsIsCapabilityListing && hasTableIssues) {
+        await (0, capabilities_syncer_1.updateCapabilitiesFile)(capabilitiesPath, currentModules, existingFiles, result);
+        console.log(chalk_1.default.green(`\n✅ 已更新 CAPABILITIES.md`));
+    }
+    for (const dir of result.contextMissing) {
+        await (0, context_syncer_1.createContextMd)(projectPath, dir);
+        console.log(chalk_1.default.green(`✅ 已创建 ${dir}/CONTEXT.md`));
+    }
+    if (hasAgentsIssues && agentsMdExpected !== null) {
+        await fs.writeFile(path.join(projectPath, 'AGENTS.md'), agentsMdExpected, 'utf-8');
+        console.log(chalk_1.default.green(agentsMdExists ? `✅ 已更新 AGENTS.md` : `✅ 已生成 AGENTS.md`));
+    }
+    return !hasIssues;
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/commands/sync-docs/index.js.map

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

package/dist/cli/commands/sync-docs/preserve-block.d.ts

@@ -0,0 +1,24 @@
+/**
+ * AGENTS.md PRESERVE 标记块（工单 22）
+ *
+ * 使用者在 AGENTS.md 中用 `<!-- PRESERVE:名称 -->` / `<!-- /PRESERVE:名称 -->`
+ * 圈出的区段属于使用者自有内容：重新生成时原样保留（附于生成内容之后，保持相对顺序），
+ * 漂移比对对块内改动免疫。名称仅允许字母/数字/下划线/连字符，标记须独占一行。
+ */
+export interface PreserveExtraction {
+    /** 完整保留块（含首尾标记行，块间不含外部空行），保持原有相对顺序 */
+    blocks: string[];
+    /** 未闭合（缺同名结束标记）的块名——不予保留，调用方应告警 */
+    malformed: string[];
+}
+/**
+ * 从既有 AGENTS.md 提取 PRESERVE 标记块（逐行扫描，结束标记须与开始标记同名）。
+ * 块内容原样保留（含标记行）；未闭合的开始标记按普通内容处理并记入 malformed。
+ */
+export declare function extractPreserveBlocks(content: string): PreserveExtraction;
+/**
+ * 组合 AGENTS.md 最终内容：生成部分在前，PRESERVE 块按原序附在文末（空行分隔）。
+ * 无保留块时原样返回生成内容（与历史行为一致）；组合结果重跑幂等。
+ */
+export declare function composeAgentsMd(generated: string, blocks: string[]): string;
+//# sourceMappingURL=preserve-block.d.ts.map

package/dist/cli/commands/sync-docs/preserve-block.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preserve-block.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/sync-docs/preserve-block.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH,MAAM,WAAW,kBAAkB;IACjC,sCAAsC;IACtC,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,mCAAmC;IACnC,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,kBAAkB,CA0BzE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAI3E"}

package/dist/cli/commands/sync-docs/preserve-block.js

@@ -0,0 +1,55 @@
+"use strict";
+/**
+ * AGENTS.md PRESERVE 标记块（工单 22）
+ *
+ * 使用者在 AGENTS.md 中用 `<!-- PRESERVE:名称 -->` / `<!-- /PRESERVE:名称 -->`
+ * 圈出的区段属于使用者自有内容：重新生成时原样保留（附于生成内容之后，保持相对顺序），
+ * 漂移比对对块内改动免疫。名称仅允许字母/数字/下划线/连字符，标记须独占一行。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractPreserveBlocks = extractPreserveBlocks;
+exports.composeAgentsMd = composeAgentsMd;
+/** PRESERVE 开始标记：独占一行，捕获名称 */
+const PRESERVE_BEGIN_RE = /^<!-- PRESERVE:([A-Za-z0-9_-]+) -->\s*$/;
+/**
+ * 从既有 AGENTS.md 提取 PRESERVE 标记块（逐行扫描，结束标记须与开始标记同名）。
+ * 块内容原样保留（含标记行）；未闭合的开始标记按普通内容处理并记入 malformed。
+ */
+function extractPreserveBlocks(content) {
+    const blocks = [];
+    const malformed = [];
+    const lines = content.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+        const m = lines[i].match(PRESERVE_BEGIN_RE);
+        if (!m) {
+            i++;
+            continue;
+        }
+        const name = m[1];
+        const endMarker = `<!-- /PRESERVE:${name} -->`;
+        let j = i + 1;
+        while (j < lines.length && lines[j].trim() !== endMarker) {
+            j++;
+        }
+        if (j >= lines.length) {
+            malformed.push(name);
+            i++; // 未闭合：跳过开始标记行，其余行按普通内容继续扫描
+            continue;
+        }
+        blocks.push(lines.slice(i, j + 1).join('\n'));
+        i = j + 1;
+    }
+    return { blocks, malformed };
+}
+/**
+ * 组合 AGENTS.md 最终内容：生成部分在前，PRESERVE 块按原序附在文末（空行分隔）。
+ * 无保留块时原样返回生成内容（与历史行为一致）；组合结果重跑幂等。
+ */
+function composeAgentsMd(generated, blocks) {
+    if (blocks.length === 0)
+        return generated;
+    const head = generated.replace(/\s*$/, '');
+    return head + '\n\n' + blocks.join('\n\n') + '\n';
+}
+//# sourceMappingURL=preserve-block.js.map

package/dist/cli/commands/sync-docs/preserve-block.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preserve-block.js","sourceRoot":"","sources":["../../../../src/cli/commands/sync-docs/preserve-block.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;AAgBH,sDA0BC;AAMD,0CAIC;AAlDD,8BAA8B;AAC9B,MAAM,iBAAiB,GAAG,yCAAyC,CAAC;AASpE;;;GAGG;AACH,SAAgB,qBAAqB,CAAC,OAAe;IACnD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,SAAS,GAAa,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC;QAC5C,IAAI,CAAC,CAAC,EAAE,CAAC;YACP,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QACD,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QAClB,MAAM,SAAS,GAAG,kBAAkB,IAAI,MAAM,CAAC;QAC/C,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACd,OAAO,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YACzD,CAAC,EAAE,CAAC;QACN,CAAC;QACD,IAAI,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC;YACtB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACrB,CAAC,EAAE,CAAC,CAAC,2BAA2B;YAChC,SAAS;QACX,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC9C,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACZ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AAC/B,CAAC;AAED;;;GAGG;AACH,SAAgB,eAAe,CAAC,SAAiB,EAAE,MAAgB;IACjE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,SAAS,CAAC;IAC1C,MAAM,IAAI,GAAG,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IAC3C,OAAO,IAAI,GAAG,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,CAAC;AACpD,CAAC"}

package/dist/cli/commands/sync-docs/project-reader.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 项目读取器（工单 22）：package.json / config.yml / 源码结构的项目信息提取
+ */
+export interface ModuleInfo {
+    name: string;
+    file: string;
+    description: string;
+}
+export interface SyncResult {
+    added: string[];
+    removed: string[];
+    contextMissing: string[];
+    contextStale: string[];
+}
+export interface PackageJsonLite {
+    name?: string;
+    description?: string;
+    scripts?: Record<string, string>;
+}
+/** 读取 package.json（不存在或无法解析时返回 null） */
+export declare function readPackageJsonLite(dir: string): Promise<PackageJsonLite | null>;
+/** 从 .harness/config.yml 读取项目描述（package.json 无 description 时的兜底） */
+export declare function getConfigDescription(projectPath: string): Promise<string>;
+/** 检测包管理器（决定命令前缀）：pnpm workspace/lockfile → yarn lockfile → 默认 npm */
+export declare function detectPackageManager(projectPath: string): 'pnpm' | 'yarn' | 'npm';
+/** 格式化脚本调用方式（npm 的 start/test 可省略 run） */
+export declare function formatScriptCommand(pm: 'pnpm' | 'yarn' | 'npm', name: string): string;
+/**
+ * 获取需要 CONTEXT.md 的目录列表
+ */
+export declare function getRequiredContextDirs(projectPath: string): Promise<string[]>;
+/**
+ * 获取源码扫描目录列表
+ * 优先从 governance.context_files.required_dirs 读取，默认 ['src']
+ */
+export declare function getSourceDirs(projectPath: string): Promise<string[]>;
+/**
+ * 扫描源码目录，提取模块信息
+ */
+export declare function scanSourceModules(srcDir: string, projectPath: string): Promise<ModuleInfo[]>;
+//# sourceMappingURL=project-reader.d.ts.map

package/dist/cli/commands/sync-docs/project-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-reader.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/sync-docs/project-reader.ts"],"names":[],"mappings":"AAAA;;GAEG;AASH,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,wCAAwC;AACxC,wBAAsB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAMtF;AAED,oEAAoE;AACpE,wBAAsB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAO/E;AAED,sEAAsE;AACtE,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAMjF;AAED,0CAA0C;AAC1C,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAIrF;AAED;;GAEG;AACH,wBAAsB,sBAAsB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAgBnF;AAED;;;GAGG;AACH,wBAAsB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAI1E;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC,CAqClG"}