openxiangda-devkit-core 2.63.3 → 2.65.0

package/dist/app-spec.d.ts

@@ -15,6 +15,7 @@ export declare const APP_SPEC_LIMITS: {
     readonly maximumContextBytes: number;
     readonly maximumDirectoryEntries: 256;
     readonly maximumHistoryDepth: 1;
+    readonly maximumReadbackEntries: 128;
 };
 export type AppSpecRisk = "L1" | "L2" | "L3";
 export type AppSpecCurrentSpecStatus = "pending" | "merged" | "not-applicable";
@@ -58,6 +59,14 @@ export interface AppSpecDocumentSummary {
     requirementCount: number;
     acceptanceScenarioCount: number;
 }
+export interface AppSpecDocumentReadback {
+    path: string;
+    actualBytes: number | null;
+    readBytes: number;
+    mode: 'full' | 'history-index' | 'unavailable';
+    reason: 'read' | 'file-unreadable' | 'file-invalid' | 'file-size-budget' | 'file-count-budget' | 'total-size-budget' | 'metadata-invalid' | 'changed-during-read' | 'directory-entry-budget' | 'directory-invalid';
+    maximumBytes: number | null;
+}
 export interface AppSpecContext {
     schemaVersion: typeof APP_SPEC_SCHEMAS.context;
     enabled: boolean;
@@ -89,8 +98,18 @@ export interface AppSpecContext {
     contextBudget: {
         maximumBytes: number;
         contentBytes: number;
+        requestedContentBytes: number;
+        truncated: boolean;
+        omitted: Array<AppSpecDocumentSummary & {
+            reason: 'context-budget';
+            actualBytes: number;
+        }>;
+    };
+    documentReadback: {
+        entries: AppSpecDocumentReadback[];
+        total: number;
+        unavailable: number;
         truncated: boolean;
-        omitted: AppSpecDocumentSummary[];
     };
     stats: {
         files: number;
@@ -205,8 +224,12 @@ export declare function summarizeAppSpecContext(context: AppSpecContext): {
     contextBudget: {
         maximumBytes: number;
         contentBytes: number;
+        requestedContentBytes: number;
         truncated: boolean;
-        omitted: AppSpecDocumentSummary[];
+        omitted: Array<AppSpecDocumentSummary & {
+            reason: "context-budget";
+            actualBytes: number;
+        }>;
     };
     stats: {
         files: number;

package/dist/app-spec.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-spec.d.ts","sourceRoot":"","sources":["../src/app-spec.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app-spec.d.ts","sourceRoot":"","sources":["../src/app-spec.ts"],"names":[],"mappings":"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"}

package/dist/app-spec.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { designAssetReader } from './design-assets.js';
-import { existsSync, openSync, readSync, closeSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync, } from "node:fs";
+import { existsSync, openSync, readSync, closeSync, lstatSync, fstatSync, constants, 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 = {
@@ -18,6 +18,7 @@ export const APP_SPEC_LIMITS = {
     maximumContextBytes: 256 * 1024,
     maximumDirectoryEntries: 256,
     maximumHistoryDepth: 1,
+    maximumReadbackEntries: 128,
 };
 const APP_ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const CHANGE_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -247,6 +248,7 @@ export function inspectAppSpec(root, contract, selector, historyOffset = 0) {
         designs: budgeted.designs,
         historyPage: collection.historyPage,
         contextBudget: budgeted.contextBudget,
+        documentReadback: documentReadback(collection.readback, selector),
         stats: {
             files: allDocuments.length,
             bytes: collection.bytes,
@@ -318,9 +320,11 @@ function emptyContext(contract, selector, diagnostics = [], enabled = false) {
         contextBudget: {
             maximumBytes: APP_SPEC_LIMITS.maximumContextBytes,
             contentBytes: 0,
+            requestedContentBytes: 0,
             truncated: false,
             omitted: [],
         },
+        documentReadback: { entries: [], total: 0, unavailable: 0, truncated: false },
         stats: {
             files: 0,
             bytes: 0,
@@ -396,52 +400,71 @@ function collectDocuments(root, diagnostics, selector, historyOffset = 0) {
         decisions: [],
         designs: [],
         bytes: 0,
+        readback: [],
         historyPage: { offset: historyOffset, limit: 50, total: 0, nextOffset: null },
     };
     const candidates = [];
+    const discover = (directory) => markdownFiles(directory, false, diagnostics, root, 0, (path, reason) => result.readback.push({
+        path: relativePath(root, path), actualBytes: null, readBytes: 0, mode: 'unavailable', reason, maximumBytes: null,
+    }));
     if (existsSync(paths.app))
         candidates.push({ path: paths.app, kind: "app" });
-    candidates.push(...markdownFiles(paths.capabilities, false, diagnostics, root).map(path => ({
+    candidates.push(...discover(paths.capabilities).map(path => ({
         path,
         kind: "capability",
-    })), ...markdownFiles(paths.activeChanges, false, diagnostics, root).map(path => ({
+    })), ...discover(paths.activeChanges).map(path => ({
         path,
         kind: "change",
-    })), ...markdownFiles(paths.decisions, false, diagnostics, root).map(path => ({
+    })), ...discover(paths.decisions).map(path => ({
         path,
         kind: "decision",
     })));
     for (const directory of ['product', 'experience', 'design', 'reviews']) {
-        candidates.push(...markdownFiles(join(paths.root, directory), false, diagnostics, root).map(path => ({ path, kind: 'design' })));
+        candidates.push(...discover(join(paths.root, directory)).map(path => ({ path, kind: 'design' })));
     }
     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 skipped of candidates.splice(APP_SPEC_LIMITS.maximumFiles))
+            result.readback.push({
+                path: relativePath(root, skipped.path), actualBytes: null, readBytes: 0, mode: 'unavailable', reason: 'file-count-budget', maximumBytes: null,
+            });
     }
     const history = historyCandidates(root, selector, historyOffset, diagnostics);
     result.historyPage = history.page;
     candidates.push(...history.paths.map(path => ({ path, kind: "change", history: true })));
     let historyBytes = 0;
-    for (const candidate of candidates.sort((left, right) => Number(!!left.history) - Number(!!right.history) || left.path.localeCompare(right.path))) {
+    const ordered = candidates.sort((left, right) => Number(!!left.history) - Number(!!right.history) || left.path.localeCompare(right.path));
+    for (const [candidateIndex, candidate] of ordered.entries()) {
+        const unread = (reason, actualBytes, maximumBytes = APP_SPEC_LIMITS.maximumFileBytes, bytesRead = 0) => result.readback.push({
+            path: relativePath(root, candidate.path), actualBytes, readBytes: bytesRead, mode: 'unavailable', reason, maximumBytes,
+        });
         let stat;
         try {
             stat = lstatSync(candidate.path);
         }
         catch {
+            unread('file-unreadable', null);
             diagnostics.push(issue("error", "APPSPEC_FILE_UNREADABLE", "AppSpec 文件无法读取", relativePath(root, candidate.path)));
             continue;
         }
         if (!stat.isFile() || stat.isSymbolicLink()) {
+            unread('file-invalid', null, null);
             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)));
+            unread('file-size-budget', stat.size);
+            diagnostics.push(issue("error", "APPSPEC_FILE_SIZE_EXCEEDED", `AppSpec 文件实际 ${stat.size} 字节，超过 ${APP_SPEC_LIMITS.maximumFileBytes} 字节上限；文件已发现但未读取`, relativePath(root, candidate.path), { actualBytes: stat.size, maximumBytes: APP_SPEC_LIMITS.maximumFileBytes, reason: 'file-size-budget' }));
             continue;
         }
         const indexOnly = candidate.history && basename(candidate.path) !== `${selector}.md`;
         const readBytes = indexOnly ? Math.min(stat.size, 8192) : stat.size;
         if ((candidate.history ? historyBytes : result.bytes) + readBytes > APP_SPEC_LIMITS.maximumTotalBytes) {
+            unread('total-size-budget', stat.size, APP_SPEC_LIMITS.maximumTotalBytes);
+            for (const skipped of ordered.slice(candidateIndex + 1))
+                result.readback.push({
+                    path: relativePath(root, skipped.path), actualBytes: null, readBytes: 0, mode: 'unavailable', reason: 'total-size-budget', maximumBytes: APP_SPEC_LIMITS.maximumTotalBytes,
+                });
             diagnostics.push(issue("error", "APPSPEC_TOTAL_SIZE_EXCEEDED", `AppSpec 总大小超过 ${APP_SPEC_LIMITS.maximumTotalBytes} 字节上限`, "appspec"));
             break;
         }
@@ -449,23 +472,26 @@ function collectDocuments(root, diagnostics, selector, historyOffset = 0) {
             historyBytes += readBytes;
         else
             result.bytes += readBytes;
-        let content;
-        if (indexOnly) {
-            const descriptor = openSync(candidate.path, 'r');
-            try {
-                const buffer = Buffer.alloc(readBytes);
-                const bytes = readSync(descriptor, buffer, 0, readBytes, 0);
-                content = buffer.subarray(0, bytes).toString('utf8').match(/^---\r?\n[\s\S]*?\r?\n---/)?.[0] || '';
-            }
-            finally {
-                closeSync(descriptor);
-            }
+        let content, bytesRead;
+        try {
+            const readback = readBoundedDocument(candidate.path, stat, readBytes, Boolean(indexOnly));
+            content = readback.content;
+            bytesRead = readback.bytesRead;
+        }
+        catch (error) {
+            const changed = error.code === 'APPSPEC_FILE_CHANGED';
+            const read = Number(error.bytesRead || 0);
+            unread(changed ? 'changed-during-read' : 'file-unreadable', changed ? null : stat.size, APP_SPEC_LIMITS.maximumFileBytes, Number.isSafeInteger(read) && read >= 0 ? read : 0);
+            diagnostics.push(issue('error', changed ? 'APPSPEC_FILE_CHANGED' : 'APPSPEC_FILE_UNREADABLE', changed ? 'AppSpec 文件在读取期间发生变化；保留原资料并重新读取' : 'AppSpec 文件已发现但无法完成有界读取', relativePath(root, candidate.path)));
+            continue;
         }
-        else
-            content = readFileSync(candidate.path, "utf8");
         const document = parseAppSpecDocument(root, candidate.path, candidate.kind, content, diagnostics);
-        if (!document)
+        if (!document) {
+            unread('metadata-invalid', stat.size, APP_SPEC_LIMITS.maximumFileBytes, bytesRead);
             continue;
+        }
+        result.readback.push({ path: document.path, actualBytes: stat.size, readBytes: bytesRead,
+            mode: indexOnly ? 'history-index' : 'full', reason: 'read', maximumBytes: APP_SPEC_LIMITS.maximumFileBytes });
         if (document.kind === 'design' && 'assets' in document.metadata) {
             try {
                 const assets = document.metadata.assets;
@@ -492,9 +518,44 @@ function collectDocuments(root, diagnostics, selector, historyOffset = 0) {
     }
     return result;
 }
+function readBoundedDocument(path, expected, limit, indexOnly) {
+    const descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0) | (constants.O_NONBLOCK || 0));
+    let bytesRead = 0;
+    try {
+        const before = fstatSync(descriptor);
+        if (!before.isFile() || before.size !== expected.size || before.mtimeMs !== expected.mtimeMs
+            || before.size > APP_SPEC_LIMITS.maximumFileBytes)
+            throw stableError('APPSPEC_FILE_CHANGED', path);
+        const buffer = Buffer.alloc(limit + (indexOnly ? 0 : 1));
+        while (bytesRead < buffer.length) {
+            const count = readSync(descriptor, buffer, bytesRead, buffer.length - bytesRead, bytesRead);
+            if (!count)
+                break;
+            bytesRead += count;
+        }
+        const after = fstatSync(descriptor);
+        if (after.size !== before.size || after.mtimeMs !== before.mtimeMs || (!indexOnly && bytesRead !== before.size))
+            throw stableError('APPSPEC_FILE_CHANGED', path);
+        const content = buffer.subarray(0, bytesRead).toString('utf8');
+        return { content: indexOnly ? content.match(/^---\r?\n[\s\S]*?\r?\n---/)?.[0] || '' : content, bytesRead };
+    }
+    catch (error) {
+        throw Object.assign(error, { bytesRead });
+    }
+    finally {
+        closeSync(descriptor);
+    }
+}
+function documentReadback(entries, selector) {
+    const prioritized = [...entries].sort((a, b) => Number(b.path === 'appspec/app.md' || basename(b.path, '.md') === selector)
+        - Number(a.path === 'appspec/app.md' || basename(a.path, '.md') === selector));
+    return { entries: prioritized.slice(0, APP_SPEC_LIMITS.maximumReadbackEntries), total: entries.length,
+        unavailable: entries.filter(entry => entry.mode === 'unavailable').length, truncated: entries.length > APP_SPEC_LIMITS.maximumReadbackEntries };
+}
 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 unavailable = collection.readback.some(entry => entry.path === 'appspec/app.md' && entry.mode === 'unavailable');
+        diagnostics.push(issue("error", unavailable ? "APPSPEC_APPLICATION_UNAVAILABLE" : "APPSPEC_APPLICATION_REQUIRED", unavailable ? "appspec/app.md 已发现但未成功读取；先处理读取元数据中的原因，不重建原总纲或确认" : "启用 AppSpec 后必须且只能存在一份 appspec/app.md", "appspec/app.md"));
     }
     const app = collection.app[0];
     if (app && app.id !== contract.appCode) {
@@ -530,7 +591,7 @@ function validateDocuments(collection, contract, diagnostics) {
         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));
+                diagnostics.push(issue(referenceSeverity, "APPSPEC_CHANGE_CAPABILITY_UNKNOWN", collection.readback.some(entry => entry.mode === 'unavailable') ? `ChangeSpec 引用的能力 ${id} 未能在成功读取的文档中确认；先核对 documentReadback` : `ChangeSpec 引用的能力 ${id} 不存在`, document.path));
             }
         }
         for (const id of document.references.requirements) {
@@ -540,7 +601,7 @@ function validateDocuments(collection, contract, diagnostics) {
         }
         for (const id of document.references.decisions) {
             if (!decisionIds.has(id)) {
-                diagnostics.push(issue(referenceSeverity, "APPSPEC_CHANGE_DECISION_UNKNOWN", `ChangeSpec 引用的决策 ${id} 不存在`, document.path));
+                diagnostics.push(issue(referenceSeverity, "APPSPEC_CHANGE_DECISION_UNKNOWN", collection.readback.some(entry => entry.mode === 'unavailable') ? `ChangeSpec 引用的决策 ${id} 未能在成功读取的文档中确认；先核对 documentReadback` : `ChangeSpec 引用的决策 ${id} 不存在`, document.path));
             }
         }
         validateReferences(document, resourceCodes, actionCodes, referenceSeverity, diagnostics);
@@ -737,7 +798,8 @@ function selectBaseContext(collection, selector, diagnostics) {
             decisions: [decision],
         };
     }
-    diagnostics.push(issue("warning", "APPSPEC_SELECTOR_NOT_FOUND", `未找到 AppSpec selector ${selector}，已返回应用总纲和空的相关上下文`, "appspec"));
+    const unavailable = collection.readback.filter(entry => entry.mode === 'unavailable');
+    diagnostics.push(issue("warning", unavailable.length ? "APPSPEC_SELECTOR_UNRESOLVED" : "APPSPEC_SELECTOR_NOT_FOUND", unavailable.length ? `AppSpec selector ${selector} 未能在成功读取的记录中解析；${unavailable.length} 份文件不可用，先核对 documentReadback 的路径和实际原因` : `未找到 AppSpec selector ${selector}，已返回应用总纲和空的相关上下文`, "appspec"));
     return {
         primary: null,
         capabilities: [],
@@ -769,7 +831,7 @@ function selectContext(collection, selector, diagnostics) {
         for (const id of document.references.documents) {
             const target = available.find(item => item.id === id);
             if (!target)
-                diagnostics.push(issue('error', 'APPSPEC_DESIGN_REFERENCE_UNKNOWN', `设计引用 ${id} 不存在；先恢复资料或修正引用`, document.path));
+                diagnostics.push(issue('error', 'APPSPEC_DESIGN_REFERENCE_UNKNOWN', collection.readback.some(entry => entry.mode === 'unavailable') ? `设计引用 ${id} 未能在成功读取的文档中确认；先核对 documentReadback 中的实际原因` : `设计引用 ${id} 不存在；先恢复资料或修正引用`, document.path));
             else if (!seen.has(id))
                 queue.push(target);
         }
@@ -802,6 +864,7 @@ function applyContextBudget(application, selected) {
     const included = new Set();
     const omitted = [];
     let contentBytes = 0;
+    const requestedContentBytes = prioritized.reduce((sum, document) => sum + Buffer.byteLength(document.content, 'utf8'), 0);
     for (const document of prioritized) {
         const bytes = Buffer.byteLength(document.content, "utf8");
         if (contentBytes + bytes > APP_SPEC_LIMITS.maximumContextBytes) {
@@ -822,8 +885,9 @@ function applyContextBudget(application, selected) {
         contextBudget: {
             maximumBytes: APP_SPEC_LIMITS.maximumContextBytes,
             contentBytes,
+            requestedContentBytes,
             truncated: omitted.length > 0,
-            omitted: omitted.map(summarize),
+            omitted: omitted.map(document => ({ ...summarize(document), reason: 'context-budget', actualBytes: Buffer.byteLength(document.content, 'utf8') })),
         },
     };
 }
@@ -1077,10 +1141,11 @@ function duplicateDiagnostics(values, id, code, diagnostics) {
         }
     }
 }
-function markdownFiles(directory, recursive, diagnostics, root, depth = 0) {
+function markdownFiles(directory, recursive, diagnostics, root, depth = 0, onUnavailable) {
     if (!existsSync(directory))
         return [];
     if (!isRegularDirectory(directory)) {
+        onUnavailable?.(directory, 'directory-invalid');
         diagnostics.push(issue("error", "APPSPEC_DIRECTORY_INVALID", "AppSpec 子目录必须是普通目录，不能是符号链接", relativePath(root, directory)));
         return [];
     }
@@ -1088,11 +1153,15 @@ function markdownFiles(directory, recursive, diagnostics, root, depth = 0) {
     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 skipped of entries.splice(APP_SPEC_LIMITS.maximumDirectoryEntries)) {
+            if (skipped.name.endsWith('.md'))
+                onUnavailable?.(join(directory, skipped.name), 'directory-entry-budget');
+        }
     }
     for (const entry of entries) {
         const path = join(directory, entry.name);
         if (entry.isSymbolicLink()) {
+            onUnavailable?.(path, entry.name.endsWith('.md') ? 'file-invalid' : 'directory-invalid');
             diagnostics.push(issue("error", "APPSPEC_SYMLINK_FORBIDDEN", "AppSpec 不读取符号链接", relativePath(root, path)));
             continue;
         }
@@ -1101,7 +1170,7 @@ function markdownFiles(directory, recursive, diagnostics, root, depth = 0) {
                 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));
+                files.push(...markdownFiles(path, true, diagnostics, root, depth + 1, onUnavailable));
             }
         }
         else if (entry.isFile() && entry.name.endsWith(".md"))
@@ -1360,13 +1429,14 @@ function assertInside(root, path) {
 function stableError(code, detail) {
     return Object.assign(new Error(`${code}: ${detail}`), { code, retryable: false });
 }
-function issue(severity, code, message, path) {
+function issue(severity, code, message, path, details) {
     return {
         schemaVersion: SCHEMA_VERSIONS.diagnostic,
         code,
         severity,
         message,
         path,
+        ...(details ? { details } : {}),
         retryable: false,
         remediation: severity === "error"
             ? "修正记录后运行 openxiangda spec check；普通 check 可继续，正式发布按阶段核对"