openxiangda-devkit-core 2.0.0-alpha.64 → 2.0.0-alpha.66

package/dist/app-spec.js

@@ -0,0 +1,958 @@
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import { SCHEMA_VERSIONS, } from "openxiangda-contracts";
+export const APP_SPEC_SCHEMAS = {
+    app: "openxiangda.appspec/app/v1",
+    capability: "openxiangda.appspec/capability/v1",
+    change: "openxiangda.appspec/change/v1",
+    decision: "openxiangda.appspec/decision/v1",
+    context: "openxiangda.appspec/context/v1",
+};
+export const APP_SPEC_LIMITS = {
+    maximumFiles: 128,
+    maximumFileBytes: 256 * 1024,
+    maximumTotalBytes: 2 * 1024 * 1024,
+    maximumDirectoryEntries: 256,
+    maximumHistoryDepth: 1,
+};
+const APP_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const CHANGE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const CAPABILITY_ID = /^CAP-[A-Z0-9]+(?:-[A-Z0-9]+)*$/;
+const DECISION_ID = /^ADR-[0-9]{4}(?:-[A-Z0-9]+)*$/;
+const REQUIREMENT_ID = /^REQ-[A-Z0-9]+(?:-[A-Z0-9]+)*$/;
+const ACCEPTANCE_ID = /^AC-[A-Z0-9]+(?:-[A-Z0-9]+)*$/;
+export function initializeAppSpec(input) {
+    if (!APP_ID.test(input.appCode)) {
+        throw stableError("APPSPEC_APP_CODE_INVALID", input.appCode);
+    }
+    const paths = appSpecPaths(input.root);
+    for (const directory of [
+        paths.root,
+        paths.capabilities,
+        paths.activeChanges,
+        paths.history,
+        paths.decisions,
+    ]) {
+        mkdirSync(directory, { recursive: true });
+    }
+    const created = [];
+    const existing = [];
+    if (existsSync(paths.app)) {
+        existing.push(relativePath(input.root, paths.app));
+    }
+    else {
+        exclusiveWrite(paths.app, renderApplicationSpec(input.appCode, input.appName));
+        created.push(relativePath(input.root, paths.app));
+    }
+    return {
+        schemaVersion: APP_SPEC_SCHEMAS.context,
+        enabled: true,
+        advisory: true,
+        releaseGate: false,
+        created,
+        existing,
+    };
+}
+export function createAppSpecCapability(input) {
+    initializeAppSpec(input);
+    if (!CAPABILITY_ID.test(input.id)) {
+        throw stableError("APPSPEC_CAPABILITY_ID_INVALID", input.id);
+    }
+    if (!input.title.trim())
+        throw stableError("APPSPEC_TITLE_REQUIRED", input.id);
+    const path = join(appSpecPaths(input.root).capabilities, `${fileNameForId(input.id, "CAP-")}.md`);
+    exclusiveWrite(path, renderCapabilitySpec({
+        id: input.id,
+        title: input.title.trim(),
+        resources: normalized(input.resources),
+        actions: normalized(input.actions),
+    }));
+    return {
+        schemaVersion: APP_SPEC_SCHEMAS.context,
+        enabled: true,
+        advisory: true,
+        releaseGate: false,
+        created: relativePath(input.root, path),
+    };
+}
+export function createAppSpecChange(input) {
+    initializeAppSpec(input);
+    if (!CHANGE_ID.test(input.id)) {
+        throw stableError("APPSPEC_CHANGE_ID_INVALID", input.id);
+    }
+    if (!input.title.trim())
+        throw stableError("APPSPEC_TITLE_REQUIRED", input.id);
+    const risk = input.risk || "L1";
+    if (!["L1", "L2", "L3"].includes(risk)) {
+        throw stableError("APPSPEC_RISK_INVALID", String(risk));
+    }
+    const path = join(appSpecPaths(input.root).activeChanges, `${input.id}.md`);
+    exclusiveWrite(path, renderChangeSpec({
+        id: input.id,
+        title: input.title.trim(),
+        risk,
+        summary: input.summary?.trim() || "",
+        capabilities: normalized(input.capabilities),
+        requirements: normalized(input.requirements),
+        resources: normalized(input.resources),
+        actions: normalized(input.actions),
+    }));
+    return {
+        schemaVersion: APP_SPEC_SCHEMAS.context,
+        enabled: true,
+        advisory: true,
+        releaseGate: false,
+        created: relativePath(input.root, path),
+        risk,
+        status: "draft",
+    };
+}
+export function closeAppSpecChange(input) {
+    if (!CHANGE_ID.test(input.id)) {
+        throw stableError("APPSPEC_CHANGE_ID_INVALID", input.id);
+    }
+    const paths = appSpecPaths(input.root);
+    const source = join(paths.activeChanges, `${input.id}.md`);
+    if (!existsSync(source)) {
+        throw stableError("APPSPEC_ACTIVE_CHANGE_NOT_FOUND", input.id);
+    }
+    assertRegularFile(source);
+    const year = String(new Date().getUTCFullYear());
+    const historyDirectory = join(paths.history, year);
+    const target = join(historyDirectory, `${input.id}.md`);
+    if (existsSync(target)) {
+        throw stableError("APPSPEC_HISTORY_CHANGE_EXISTS", relativePath(input.root, target));
+    }
+    mkdirSync(historyDirectory, { recursive: true });
+    const sourceContent = readFileSync(source, "utf8");
+    const document = parseAppSpecDocument(input.root, source, "change", sourceContent, []);
+    if (!document || document.id !== input.id) {
+        throw stableError("APPSPEC_ACTIVE_CHANGE_INVALID", input.id);
+    }
+    renameSync(source, target);
+    const closedAt = new Date().toISOString();
+    const updated = appendClosure(setFrontMatterValue(setFrontMatterValue(sourceContent, "status", "archived"), "closedAt", closedAt), input.summary?.trim() || "变更记录已归档；验收与发布结果以实际证据为准。", closedAt);
+    atomicReplace(target, updated);
+    return {
+        schemaVersion: APP_SPEC_SCHEMAS.context,
+        enabled: true,
+        advisory: true,
+        releaseGate: false,
+        archived: relativePath(input.root, target),
+        status: "archived",
+    };
+}
+export function inspectAppSpec(root, contract, selector) {
+    const paths = appSpecPaths(root);
+    if (!existsSync(paths.root))
+        return emptyContext(contract, selector);
+    const diagnostics = [];
+    if (!isRegularDirectory(paths.root)) {
+        diagnostics.push(issue("error", "APPSPEC_ROOT_INVALID", "appspec 必须是普通目录，不能是符号链接", "appspec"));
+        return emptyContext(contract, selector, diagnostics, true);
+    }
+    const collection = collectDocuments(root, diagnostics);
+    const application = collection.app[0] || null;
+    validateDocuments(collection, contract, diagnostics);
+    const selected = selectContext(collection, selector, diagnostics);
+    const allDocuments = [
+        ...collection.app,
+        ...collection.capabilities,
+        ...collection.activeChanges,
+        ...collection.history,
+        ...collection.decisions,
+    ];
+    const digest = allDocuments.length === 0
+        ? null
+        : createHash("sha256")
+            .update([
+            ...allDocuments
+                .sort((left, right) => left.path.localeCompare(right.path))
+                .map(document => `${document.path}\n${document.content}`),
+            contract.configDigest || "",
+            contract.contractDigest || "",
+            contract.aiCatalogDigest || "",
+        ].join("\n---\n"))
+            .digest("hex");
+    return {
+        schemaVersion: APP_SPEC_SCHEMAS.context,
+        enabled: true,
+        mode: "advisory",
+        releaseGate: false,
+        root: "appspec",
+        selector: selector || null,
+        contract,
+        application,
+        capabilities: selected.capabilities,
+        activeChanges: selected.activeChanges,
+        decisions: selected.decisions,
+        history: collection.history.map(summarize),
+        stats: {
+            files: allDocuments.length,
+            bytes: collection.bytes,
+            capabilities: collection.capabilities.length,
+            activeChanges: collection.activeChanges.length,
+            historyChanges: collection.history.length,
+            decisions: collection.decisions.length,
+            requirements: unique(collection.capabilities.flatMap(document => document.requirementIds)).length,
+            acceptanceScenarios: unique(collection.capabilities.flatMap(document => document.acceptanceIds)).length,
+        },
+        digest,
+        diagnostics,
+    };
+}
+export function advisoryAppSpecDiagnostics(diagnostics) {
+    return diagnostics.map(diagnostic => ({
+        ...diagnostic,
+        severity: diagnostic.severity === "error" ? "warning" : diagnostic.severity,
+        remediation: diagnostic.remediation ||
+            "AppSpec 是辅助层；可运行 openxiangda spec check 获取完整诊断，应用 check/deploy 不受阻断",
+    }));
+}
+export function summarizeAppSpecContext(context) {
+    return {
+        enabled: context.enabled,
+        mode: context.mode,
+        releaseGate: context.releaseGate,
+        digest: context.digest,
+        stats: context.stats,
+        diagnostics: {
+            errors: context.diagnostics.filter(item => item.severity === "error").length,
+            warnings: context.diagnostics.filter(item => item.severity === "warning").length,
+            info: context.diagnostics.filter(item => item.severity === "info").length,
+        },
+        nextCommand: context.enabled
+            ? "openxiangda spec context --json"
+            : "openxiangda spec init",
+    };
+}
+function emptyContext(contract, selector, diagnostics = [], enabled = false) {
+    return {
+        schemaVersion: APP_SPEC_SCHEMAS.context,
+        enabled,
+        mode: "advisory",
+        releaseGate: false,
+        root: "appspec",
+        selector: selector || null,
+        contract,
+        application: null,
+        capabilities: [],
+        activeChanges: [],
+        decisions: [],
+        history: [],
+        stats: {
+            files: 0,
+            bytes: 0,
+            capabilities: 0,
+            activeChanges: 0,
+            historyChanges: 0,
+            decisions: 0,
+            requirements: 0,
+            acceptanceScenarios: 0,
+        },
+        digest: null,
+        diagnostics,
+    };
+}
+function collectDocuments(root, diagnostics) {
+    const paths = appSpecPaths(root);
+    const result = {
+        app: [],
+        capabilities: [],
+        activeChanges: [],
+        history: [],
+        decisions: [],
+        bytes: 0,
+    };
+    const candidates = [];
+    if (existsSync(paths.app))
+        candidates.push({ path: paths.app, kind: "app" });
+    candidates.push(...markdownFiles(paths.capabilities, false, diagnostics, root).map(path => ({
+        path,
+        kind: "capability",
+    })), ...markdownFiles(paths.activeChanges, false, diagnostics, root).map(path => ({
+        path,
+        kind: "change",
+    })), ...markdownFiles(paths.history, true, diagnostics, root).map(path => ({
+        path,
+        kind: "change",
+        history: true,
+    })), ...markdownFiles(paths.decisions, false, diagnostics, root).map(path => ({
+        path,
+        kind: "decision",
+    })));
+    if (candidates.length > APP_SPEC_LIMITS.maximumFiles) {
+        diagnostics.push(issue("error", "APPSPEC_FILE_LIMIT_EXCEEDED", `AppSpec 文件数 ${candidates.length} 超过上限 ${APP_SPEC_LIMITS.maximumFiles}`, "appspec"));
+        candidates.splice(APP_SPEC_LIMITS.maximumFiles);
+    }
+    for (const candidate of candidates.sort((left, right) => left.path.localeCompare(right.path))) {
+        let stat;
+        try {
+            stat = lstatSync(candidate.path);
+        }
+        catch {
+            diagnostics.push(issue("error", "APPSPEC_FILE_UNREADABLE", "AppSpec 文件无法读取", relativePath(root, candidate.path)));
+            continue;
+        }
+        if (!stat.isFile() || stat.isSymbolicLink()) {
+            diagnostics.push(issue("error", "APPSPEC_FILE_INVALID", "AppSpec 只允许普通 Markdown 文件，不能使用符号链接", relativePath(root, candidate.path)));
+            continue;
+        }
+        if (stat.size > APP_SPEC_LIMITS.maximumFileBytes) {
+            diagnostics.push(issue("error", "APPSPEC_FILE_SIZE_EXCEEDED", `AppSpec 单文件超过 ${APP_SPEC_LIMITS.maximumFileBytes} 字节上限`, relativePath(root, candidate.path)));
+            continue;
+        }
+        if (result.bytes + stat.size > APP_SPEC_LIMITS.maximumTotalBytes) {
+            diagnostics.push(issue("error", "APPSPEC_TOTAL_SIZE_EXCEEDED", `AppSpec 总大小超过 ${APP_SPEC_LIMITS.maximumTotalBytes} 字节上限`, "appspec"));
+            break;
+        }
+        result.bytes += stat.size;
+        const content = readFileSync(candidate.path, "utf8");
+        const document = parseAppSpecDocument(root, candidate.path, candidate.kind, content, diagnostics);
+        if (!document)
+            continue;
+        if (candidate.kind === "app")
+            result.app.push(document);
+        else if (candidate.kind === "capability")
+            result.capabilities.push(document);
+        else if (candidate.kind === "decision")
+            result.decisions.push(document);
+        else if (candidate.history)
+            result.history.push(document);
+        else
+            result.activeChanges.push(document);
+    }
+    return result;
+}
+function validateDocuments(collection, contract, diagnostics) {
+    if (collection.app.length !== 1) {
+        diagnostics.push(issue("error", "APPSPEC_APPLICATION_REQUIRED", "启用 AppSpec 后必须且只能存在一份 appspec/app.md", "appspec/app.md"));
+    }
+    const app = collection.app[0];
+    if (app && app.id !== contract.appCode) {
+        diagnostics.push(issue("error", "APPSPEC_APP_CODE_MISMATCH", `AppSpec app=${app.id} 与工作区 ${contract.appCode} 不一致`, app.path));
+    }
+    for (const document of collection.activeChanges) {
+        if (["archived", "cancelled"].includes(document.status)) {
+            diagnostics.push(issue("error", "APPSPEC_ACTIVE_CHANGE_STATUS_INVALID", `活跃目录中的 ChangeSpec 不能使用 ${document.status} 状态`, document.path));
+        }
+    }
+    for (const document of collection.history) {
+        if (!["archived", "cancelled"].includes(document.status)) {
+            diagnostics.push(issue("error", "APPSPEC_HISTORY_CHANGE_STATUS_INVALID", `历史目录中的 ChangeSpec 必须是 archived 或 cancelled，当前为 ${document.status}`, document.path));
+        }
+    }
+    duplicateDiagnostics([...collection.capabilities, ...collection.activeChanges, ...collection.history, ...collection.decisions], document => document.id, "APPSPEC_DOCUMENT_ID_DUPLICATED", diagnostics);
+    duplicateDiagnostics(collection.capabilities.flatMap(document => document.requirementIds.map(id => ({ ...document, id }))), document => document.id, "APPSPEC_REQUIREMENT_ID_DUPLICATED", diagnostics);
+    duplicateDiagnostics(collection.capabilities.flatMap(document => document.acceptanceIds.map(id => ({ ...document, id }))), document => document.id, "APPSPEC_ACCEPTANCE_ID_DUPLICATED", diagnostics);
+    const capabilityIds = new Set(collection.capabilities.map(document => document.id));
+    const requirementIds = new Set(collection.capabilities.flatMap(document => document.requirementIds));
+    const resourceCodes = new Set(contract.resourceCodes);
+    const actionCodes = new Set(contract.actionCodes);
+    const decisionIds = new Set(collection.decisions.map(document => document.id));
+    for (const document of collection.capabilities) {
+        validateReferences(document, resourceCodes, actionCodes, "error", diagnostics);
+        for (const requirement of requirementsWithoutAcceptance(document.content)) {
+            diagnostics.push(issue("warning", "APPSPEC_REQUIREMENT_ACCEPTANCE_RECOMMENDED", `需求 ${requirement} 建议至少包含一个 #### AC-* 可证伪场景`, document.path));
+        }
+    }
+    for (const document of collection.activeChanges) {
+        const finalState = ["verified", "released"].includes(document.status);
+        const referenceSeverity = finalState ? "error" : "warning";
+        for (const id of document.references.capabilities) {
+            if (!capabilityIds.has(id)) {
+                diagnostics.push(issue(referenceSeverity, "APPSPEC_CHANGE_CAPABILITY_UNKNOWN", `ChangeSpec 引用的能力 ${id} 不存在`, document.path));
+            }
+        }
+        for (const id of document.references.requirements) {
+            if (!requirementIds.has(id)) {
+                diagnostics.push(issue(referenceSeverity, "APPSPEC_CHANGE_REQUIREMENT_UNKNOWN", `ChangeSpec 引用的需求 ${id} 尚未进入当前 CapabilitySpec`, document.path));
+            }
+        }
+        for (const id of document.references.decisions) {
+            if (!decisionIds.has(id)) {
+                diagnostics.push(issue(referenceSeverity, "APPSPEC_CHANGE_DECISION_UNKNOWN", `ChangeSpec 引用的决策 ${id} 不存在`, document.path));
+            }
+        }
+        validateReferences(document, resourceCodes, actionCodes, referenceSeverity, diagnostics);
+        validateRiskSections(document, diagnostics);
+        if (finalState && unresolvedQuestions(document.content).length > 0) {
+            diagnostics.push(issue("error", "APPSPEC_VERIFIED_CHANGE_HAS_OPEN_QUESTIONS", "verified/released ChangeSpec 仍有未勾选问题", document.path));
+        }
+    }
+    if (collection.activeChanges.length > 10) {
+        diagnostics.push(issue("warning", "APPSPEC_ACTIVE_CHANGE_COUNT_HIGH", `当前有 ${collection.activeChanges.length} 个活跃变更；建议关闭已完成记录，避免 AI 上下文膨胀`, "appspec/changes/active"));
+    }
+}
+function validateReferences(document, resourceCodes, actionCodes, severity, diagnostics) {
+    for (const code of document.references.resources) {
+        if (!resourceCodes.has(code)) {
+            diagnostics.push(issue(severity, "APPSPEC_RESOURCE_UNKNOWN", `AppSpec 引用的资源 ${code} 不在当前编译声明中`, document.path));
+        }
+    }
+    for (const code of document.references.actions) {
+        if (!actionCodes.has(code)) {
+            diagnostics.push(issue(severity, "APPSPEC_ACTION_UNKNOWN", `AppSpec 引用的动作 ${code} 不在当前编译声明中`, document.path));
+        }
+    }
+}
+function validateRiskSections(document, diagnostics) {
+    const risk = String(document.metadata.risk || "L1");
+    if (!["L1", "L2", "L3"].includes(risk)) {
+        diagnostics.push(issue("error", "APPSPEC_RISK_INVALID", `未知风险档位 ${risk}`, document.path));
+        return;
+    }
+    if (risk === "L1")
+        return;
+    const required = [
+        ["验收", "Acceptance"],
+        ["数据与权限", "Data and Permissions"],
+        ["回滚", "Rollback"],
+    ];
+    if (risk === "L3") {
+        required.push(["失败、并发与幂等", "Failure, Concurrency, and Idempotency"], ["架构决策", "Decision Records"]);
+    }
+    for (const alternatives of required) {
+        if (!hasSection(document.content, alternatives)) {
+            diagnostics.push(issue("warning", "APPSPEC_RISK_SECTION_RECOMMENDED", `${risk} ChangeSpec 建议补充“${alternatives[0]}”`, document.path));
+        }
+    }
+}
+function selectContext(collection, selector, diagnostics) {
+    if (!selector) {
+        return {
+            capabilities: collection.capabilities,
+            activeChanges: collection.activeChanges,
+            decisions: collection.decisions,
+        };
+    }
+    const change = collection.activeChanges.find(document => document.id === selector);
+    if (change) {
+        const capabilityIds = new Set(change.references.capabilities);
+        const decisionIds = new Set(change.references.decisions);
+        return {
+            capabilities: collection.capabilities.filter(document => capabilityIds.has(document.id)),
+            activeChanges: [change],
+            decisions: collection.decisions.filter(document => decisionIds.has(document.id)),
+        };
+    }
+    const capability = collection.capabilities.find(document => document.id === selector);
+    if (capability) {
+        return {
+            capabilities: [capability],
+            activeChanges: collection.activeChanges.filter(document => document.references.capabilities.includes(capability.id)),
+            decisions: collection.decisions,
+        };
+    }
+    diagnostics.push(issue("warning", "APPSPEC_SELECTOR_NOT_FOUND", `未找到 AppSpec selector ${selector}，已返回应用总纲和空的相关上下文`, "appspec"));
+    return { capabilities: [], activeChanges: [], decisions: [] };
+}
+function parseAppSpecDocument(root, path, kind, content, diagnostics) {
+    const pointer = relativePath(root, path);
+    const frontMatter = parseFrontMatter(content, pointer, diagnostics);
+    if (!frontMatter)
+        return null;
+    validateMetadata(kind, frontMatter.metadata, pointer, diagnostics);
+    const expectedSchema = APP_SPEC_SCHEMAS[kind];
+    if (frontMatter.metadata.schema !== expectedSchema) {
+        diagnostics.push(issue("error", "APPSPEC_SCHEMA_INVALID", `期望 schema=${expectedSchema}`, pointer));
+    }
+    const id = String(kind === "app" ? frontMatter.metadata.app || "" : frontMatter.metadata.id || "");
+    const pattern = kind === "app"
+        ? APP_ID
+        : kind === "capability"
+            ? CAPABILITY_ID
+            : kind === "decision"
+                ? DECISION_ID
+                : CHANGE_ID;
+    if (!pattern.test(id)) {
+        diagnostics.push(issue("error", "APPSPEC_DOCUMENT_ID_INVALID", `无效 ${kind} id: ${id}`, pointer));
+    }
+    const status = String(frontMatter.metadata.status || "draft");
+    const validStatuses = {
+        app: ["active", "retired"],
+        capability: ["draft", "active", "retired"],
+        change: ["draft", "confirmed", "implementing", "verified", "released", "archived", "cancelled"],
+        decision: ["proposed", "accepted", "superseded", "rejected"],
+    };
+    if (!validStatuses[kind].includes(status)) {
+        diagnostics.push(issue("error", "APPSPEC_STATUS_INVALID", `${kind} status=${status} 不受支持`, pointer));
+    }
+    const h1 = content.match(/^#\s+(.+)$/m)?.[1]?.trim() || "";
+    const title = String(frontMatter.metadata.title || h1 || id);
+    const requirementIds = extractIds(content, /^###\s+(REQ-[A-Z0-9-]+)\b/gm, REQUIREMENT_ID);
+    const acceptanceIds = extractIds(content, /^####\s+(AC-[A-Z0-9-]+)\b/gm, ACCEPTANCE_ID);
+    return {
+        kind,
+        id,
+        title,
+        status,
+        path: pointer,
+        metadata: frontMatter.metadata,
+        requirementIds,
+        acceptanceIds,
+        references: {
+            capabilities: metadataStrings(frontMatter.metadata, "capabilities"),
+            requirements: metadataStrings(frontMatter.metadata, "requirements"),
+            resources: metadataStrings(frontMatter.metadata, "resources"),
+            actions: metadataStrings(frontMatter.metadata, "actions"),
+            decisions: metadataStrings(frontMatter.metadata, "decisions"),
+        },
+        content,
+    };
+}
+function parseFrontMatter(content, pointer, diagnostics) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
+    if (!match) {
+        diagnostics.push(issue("error", "APPSPEC_FRONT_MATTER_REQUIRED", "AppSpec Markdown 必须以受限 YAML front matter 开头", pointer));
+        return null;
+    }
+    const metadata = {};
+    const lines = (match[1] || "").split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const raw = lines[index] || "";
+        if (!raw.trim() || raw.trimStart().startsWith("#"))
+            continue;
+        const entry = raw.match(/^([A-Za-z][A-Za-z0-9_-]*):(?:\s*(.*))?$/);
+        if (!entry) {
+            diagnostics.push(issue("error", "APPSPEC_FRONT_MATTER_INVALID", `不支持的 front matter 行: ${raw.trim()}`, pointer));
+            continue;
+        }
+        const key = entry[1] || "";
+        const rawValue = entry[2] || "";
+        if (rawValue.trim()) {
+            metadata[key] = parseMetadataValue(rawValue.trim());
+            continue;
+        }
+        const values = [];
+        while (index + 1 < lines.length) {
+            const next = lines[index + 1] || "";
+            const item = next.match(/^\s{2,}-\s+(.+)$/);
+            if (!item)
+                break;
+            values.push(String(parseMetadataValue(item[1] || "")));
+            index += 1;
+        }
+        metadata[key] = values;
+    }
+    return { metadata };
+}
+function parseMetadataValue(value) {
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (value === "[]")
+        return [];
+    if (value.startsWith("[") && value.endsWith("]")) {
+        try {
+            const parsed = JSON.parse(value);
+            if (Array.isArray(parsed))
+                return parsed.map(item => String(item));
+        }
+        catch {
+            return value
+                .slice(1, -1)
+                .split(",")
+                .map(item => unquote(item.trim()))
+                .filter(Boolean);
+        }
+    }
+    return unquote(value);
+}
+function unquote(value) {
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        if (value.startsWith('"')) {
+            try {
+                return String(JSON.parse(value));
+            }
+            catch {
+                return value.slice(1, -1);
+            }
+        }
+        return value.slice(1, -1).replaceAll("''", "'");
+    }
+    return value;
+}
+function metadataStrings(metadata, key) {
+    const value = metadata[key];
+    if (Array.isArray(value))
+        return normalized(value);
+    if (typeof value === "string" && value.trim())
+        return [value.trim()];
+    return [];
+}
+function requirementsWithoutAcceptance(content) {
+    const source = withoutHtmlComments(content);
+    const matches = [...source.matchAll(/^###\s+(REQ-[A-Z0-9-]+)\b/gm)];
+    const missing = [];
+    for (let index = 0; index < matches.length; index += 1) {
+        const start = matches[index]?.index || 0;
+        const end = matches[index + 1]?.index ?? source.length;
+        const block = source.slice(start, end);
+        if (!/^####\s+AC-[A-Z0-9-]+\b/m.test(block)) {
+            const id = matches[index]?.[1];
+            if (id)
+                missing.push(id);
+        }
+    }
+    return missing;
+}
+function unresolvedQuestions(content) {
+    const source = withoutHtmlComments(content);
+    const heading = source.match(/^##\s+(?:未确认问题|Unresolved Questions)\s*$/m);
+    if (heading?.index === undefined)
+        return [];
+    const tail = source.slice(heading.index + heading[0].length);
+    const nextHeading = tail.search(/^##\s+/m);
+    const section = nextHeading >= 0 ? tail.slice(0, nextHeading) : tail;
+    return section ? [...section.matchAll(/^- \[ \]\s+(.+)$/gm)].map(match => match[1]) : [];
+}
+function hasSection(content, alternatives) {
+    return alternatives.some(title => new RegExp(`^##\\s+${escapeRegExp(title)}\\s*$`, "m").test(content));
+}
+function duplicateDiagnostics(values, id, code, diagnostics) {
+    const seen = new Map();
+    for (const value of values) {
+        const key = id(value);
+        if (!key)
+            continue;
+        const previous = seen.get(key);
+        if (previous) {
+            diagnostics.push(issue("error", code, `稳定 ID ${key} 重复，首次出现在 ${previous}`, value.path));
+        }
+        else {
+            seen.set(key, value.path);
+        }
+    }
+}
+function markdownFiles(directory, recursive, diagnostics, root, depth = 0) {
+    if (!existsSync(directory))
+        return [];
+    if (!isRegularDirectory(directory)) {
+        diagnostics.push(issue("error", "APPSPEC_DIRECTORY_INVALID", "AppSpec 子目录必须是普通目录，不能是符号链接", relativePath(root, directory)));
+        return [];
+    }
+    const files = [];
+    const entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    if (entries.length > APP_SPEC_LIMITS.maximumDirectoryEntries) {
+        diagnostics.push(issue("error", "APPSPEC_DIRECTORY_ENTRY_LIMIT_EXCEEDED", `AppSpec 单目录条目数超过 ${APP_SPEC_LIMITS.maximumDirectoryEntries} 上限`, relativePath(root, directory)));
+        entries.splice(APP_SPEC_LIMITS.maximumDirectoryEntries);
+    }
+    for (const entry of entries) {
+        const path = join(directory, entry.name);
+        if (entry.isSymbolicLink()) {
+            diagnostics.push(issue("error", "APPSPEC_SYMLINK_FORBIDDEN", "AppSpec 不读取符号链接", relativePath(root, path)));
+            continue;
+        }
+        if (entry.isDirectory() && recursive) {
+            if (depth >= APP_SPEC_LIMITS.maximumHistoryDepth) {
+                diagnostics.push(issue("error", "APPSPEC_HISTORY_DEPTH_EXCEEDED", "AppSpec 历史目录只允许 history/<year>/*.md", relativePath(root, path)));
+            }
+            else {
+                files.push(...markdownFiles(path, true, diagnostics, root, depth + 1));
+            }
+        }
+        else if (entry.isFile() && entry.name.endsWith(".md"))
+            files.push(path);
+        else if (!entry.name.startsWith(".")) {
+            diagnostics.push(issue("warning", "APPSPEC_UNKNOWN_ENTRY_IGNORED", "AppSpec 只读取约定目录中的 Markdown 文件", relativePath(root, path)));
+        }
+    }
+    return files;
+}
+function appSpecPaths(root) {
+    const workspace = resolve(root);
+    const appSpecRoot = resolve(workspace, "appspec");
+    assertInside(workspace, appSpecRoot);
+    return {
+        root: appSpecRoot,
+        app: join(appSpecRoot, "app.md"),
+        capabilities: join(appSpecRoot, "capabilities"),
+        activeChanges: join(appSpecRoot, "changes", "active"),
+        history: join(appSpecRoot, "changes", "history"),
+        decisions: join(appSpecRoot, "decisions"),
+    };
+}
+function renderApplicationSpec(appCode, appName) {
+    return `---
+schema: ${APP_SPEC_SCHEMAS.app}
+app: ${JSON.stringify(appCode)}
+title: ${JSON.stringify(appName)}
+status: active
+---
+# ${appName}
+
+AppSpec 是可选的业务意图辅助层，不是发布门禁。资源、字段、权限和动作仍以
+\`openxiangda.config.ts\` 与实时编译合同为准。
+
+## 业务目标
+
+<!-- 用业务语言说明应用解决的问题和可观察结果。 -->
+
+## 角色
+
+<!-- 只记录业务角色及其目标；稳定 role code 在能力规格中引用。 -->
+
+## 范围
+
+### 包含
+
+### 不包含
+
+## 能力目录
+
+<!-- 复杂业务再在 capabilities/ 下增加 CAP-*；小应用可以只维护本文件。 -->
+
+## 术语
+
+## 跨能力约束
+
+## 未确认问题
+
+- 无。
+`;
+}
+function renderCapabilitySpec(input) {
+    return `---
+schema: ${APP_SPEC_SCHEMAS.capability}
+id: ${input.id}
+title: ${JSON.stringify(input.title)}
+status: draft
+resources: ${JSON.stringify(input.resources)}
+actions: ${JSON.stringify(input.actions)}
+---
+# ${input.title}
+
+## 目标与边界
+
+<!-- 描述用户可观察的业务能力，不复制字段物理 Schema 或页面实现。 -->
+
+## 角色与权限
+
+## 当前有效需求
+
+<!--
+### REQ-DOMAIN-001 规则名称
+
+当发生某个业务条件时，系统必须产生可观察结果。
+
+#### AC-DOMAIN-001-01 正向或反向场景
+
+- Given 已知前置条件
+- When 用户或系统执行动作
+- Then 观察到明确结果
+-->
+
+## 状态与异常
+
+## 非目标
+`;
+}
+function renderChangeSpec(input) {
+    const createdAt = new Date().toISOString();
+    return `---
+schema: ${APP_SPEC_SCHEMAS.change}
+id: ${input.id}
+title: ${JSON.stringify(input.title)}
+status: draft
+risk: ${input.risk}
+createdAt: ${JSON.stringify(createdAt)}
+capabilities: ${JSON.stringify(input.capabilities)}
+requirements: ${JSON.stringify(input.requirements)}
+resources: ${JSON.stringify(input.resources)}
+actions: ${JSON.stringify(input.actions)}
+decisions: []
+---
+# ${input.title}
+
+## 为什么
+
+${input.summary || "<!-- 一两句话说明问题、证据和期望结果。 -->"}
+
+## 变更
+
+- ADDED：
+- MODIFIED：
+- REMOVED：
+- 非目标：
+
+## 验收
+
+- [ ] 一个可观察的正向结果
+- [ ] 需要时补充拒绝、异常或权限反例
+
+## 数据与权限
+
+- 无，或说明资源、字段、角色和数据范围变化。
+
+## 失败、并发与幂等
+
+- L3 才需要详细维护；其他变化写“无”。
+
+## 回滚
+
+- 回退声明/代码并保持旧数据可读；如不适用请说明。
+
+## 架构决策
+
+- L3 如涉及 ADR，在 front matter 的 decisions 中引用。
+
+## 未确认问题
+
+- 无。
+`;
+}
+function appendClosure(content, summary, closedAt) {
+    return `${content.trimEnd()}\n\n## 关闭记录\n\n- 时间：${closedAt}\n- 摘要：${summary}\n- 说明：归档不等于部署或生产验收；以实际 Verification/Deployment 证据为准。\n`;
+}
+function setFrontMatterValue(content, key, value) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        throw stableError("APPSPEC_FRONT_MATTER_REQUIRED", key);
+    const encoded = JSON.stringify(value);
+    const body = match[1] || "";
+    const pattern = new RegExp(`^${escapeRegExp(key)}:.*$`, "m");
+    const nextBody = pattern.test(body)
+        ? body.replace(pattern, `${key}: ${encoded}`)
+        : `${body.trimEnd()}\n${key}: ${encoded}`;
+    return content.replace(match[0], `---\n${nextBody}\n---`);
+}
+function exclusiveWrite(path, content) {
+    mkdirSync(dirname(path), { recursive: true });
+    try {
+        writeFileSync(path, content, { encoding: "utf8", flag: "wx" });
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            throw stableError("APPSPEC_DOCUMENT_EXISTS", path);
+        }
+        throw error;
+    }
+}
+function atomicReplace(path, content) {
+    const temporary = join(dirname(path), `.${basename(path)}.${process.pid}.${Date.now()}.tmp`);
+    exclusiveWrite(temporary, content);
+    renameSync(temporary, path);
+}
+function assertRegularFile(path) {
+    const stat = lstatSync(path);
+    if (!stat.isFile() || stat.isSymbolicLink()) {
+        throw stableError("APPSPEC_FILE_INVALID", path);
+    }
+}
+function isRegularDirectory(path) {
+    try {
+        const stat = lstatSync(path);
+        return stat.isDirectory() && !stat.isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function assertInside(root, path) {
+    const base = `${resolve(root)}/`;
+    const target = `${resolve(path)}/`;
+    if (!target.startsWith(base))
+        throw stableError("APPSPEC_PATH_OUTSIDE_WORKSPACE", path);
+}
+function stableError(code, detail) {
+    return Object.assign(new Error(`${code}: ${detail}`), { code, retryable: false });
+}
+function issue(severity, code, message, path) {
+    return {
+        schemaVersion: SCHEMA_VERSIONS.diagnostic,
+        code,
+        severity,
+        message,
+        path,
+        retryable: false,
+        remediation: severity === "error"
+            ? "修正 AppSpec 后重新运行 openxiangda spec check；普通应用 check/deploy 不受阻断"
+            : "按当前变更风险决定是否补充；AppSpec 质量建议不阻断应用交付",
+    };
+}
+function summarize(document) {
+    return {
+        kind: document.kind,
+        id: document.id,
+        title: document.title,
+        status: document.status,
+        path: document.path,
+        requirementIds: document.requirementIds,
+        acceptanceIds: document.acceptanceIds,
+    };
+}
+function extractIds(content, pattern, validation) {
+    return unique([...withoutHtmlComments(content).matchAll(pattern)]
+        .map(match => match[1] || "")
+        .filter(value => validation.test(value)));
+}
+function withoutHtmlComments(content) {
+    return content.replace(/<!--[\s\S]*?-->/g, "");
+}
+function validateMetadata(kind, metadata, pointer, diagnostics) {
+    const allowed = {
+        app: new Set(["schema", "app", "title", "status"]),
+        capability: new Set([
+            "schema",
+            "id",
+            "title",
+            "status",
+            "resources",
+            "actions",
+        ]),
+        change: new Set([
+            "schema",
+            "id",
+            "title",
+            "status",
+            "risk",
+            "createdAt",
+            "closedAt",
+            "capabilities",
+            "requirements",
+            "resources",
+            "actions",
+            "decisions",
+        ]),
+        decision: new Set([
+            "schema",
+            "id",
+            "title",
+            "status",
+            "date",
+            "deciders",
+            "supersedes",
+        ]),
+    };
+    const identifierKey = kind === "app" ? "app" : "id";
+    for (const required of ["schema", identifierKey, "status"]) {
+        if (!(required in metadata)) {
+            diagnostics.push(issue("error", "APPSPEC_METADATA_REQUIRED", `${kind} front matter 缺少 ${required}`, pointer));
+        }
+    }
+    for (const key of Object.keys(metadata)) {
+        if (!allowed[kind].has(key)) {
+            diagnostics.push(issue("error", "APPSPEC_METADATA_UNKNOWN", `${kind} front matter 不支持 ${key}`, pointer));
+        }
+    }
+}
+function normalized(values) {
+    return unique((values || []).map(value => String(value).trim()).filter(Boolean));
+}
+function unique(values) {
+    return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+function fileNameForId(id, prefix) {
+    return id.slice(prefix.length).toLowerCase();
+}
+function relativePath(root, path) {
+    return relative(resolve(root), resolve(path)).replaceAll("\\", "/");
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//# sourceMappingURL=app-spec.js.map