@yss123/cage-cli 0.2.0 → 0.3.1

package/dist/derive.d.ts

@@ -1,14 +1,37 @@
 import { type CageConfig } from './config.js';
 import type { Ontology } from './ontology.js';
+/**
+ * 生成性质测试的目录索引，供影响分析按主体挑选候选；不是测试执行结果。
+ */
 export interface DerivedTest {
+    /** 派生测试相对 generated/tests 目录的文件名，调用者结合配置解析完整路径。 */
     file: string;
+    /** 验证类别与主体组合的测试名，用于报告及候选选择。 */
     name: string;
     /** 这个测试守护的本体节点（影响分析据此挑选要运行的测试） */
     subject: string;
 }
+/**
+ * 按本体生成通用性质用例文本及 subject 索引。
+ * @param cfg 决定生成目录和领域导入相对路径。
+ * @param g 当前本体，提供用户调用能力、状态、范围和不变量。
+ * @returns 待写文件内容与用例索引；不写盘、不执行测试，skip 处理留在生成用例里。
+ */
 export declare function deriveTests(cfg: CageConfig, g: Ontology): {
     files: Record<string, string>;
     tests: DerivedTest[];
 };
+/**
+ * 写入本轮派生测试，先清理当前生成器拥有的固定文件名。
+ * @param cfg 决定 generated/tests 位置。
+ * @param files deriveTests 产生的文件映射。
+ * @returns 测试目录绝对路径；用户额外文件不会被递归删除，IO 失败直接抛出。
+ */
 export declare function writeDerived(cfg: CageConfig, files: Record<string, string>): string;
+/**
+ * 生成用于本次测试进程的 Vitest 配置字符串。
+ * @param cfg 应用根与派生测试位置。
+ * @param only derived 仅派生、project 仅项目，省略时两者都包含。
+ * @returns 使用 testkit 全局准备的配置源码；超时单位为毫秒，不在此处启动测试。
+ */
 export declare function vitestConfig(cfg: CageConfig, only?: 'derived' | 'project'): string;

package/dist/derive.js

@@ -1,9 +1,22 @@
+/**
+ * 从本体声明生成通用性质测试及 Vitest 配置，由 cage test 和 verify 驱动。
+ * 按能力、状态、范围、审计、幂等、掩码和不变量生成代码，真实执行委托 cage-testkit。
+ * 生成器不能推断所有合法业务夹具；生成用例允许显式 skip，生成数量不等于已覆盖业务需求。
+ */
 // 派生测试生成器：遍历本体图，按固定模板为每个能力点、每个范围组合子、每条非法迁移生成测试。
 // 生成到 generated/tests，不入库，每次运行前重新生成。
 import { existsSync, mkdirSync, readdirSync, writeFileSync, unlinkSync } from 'node:fs';
 import { join, relative } from 'node:path';
 import { abs } from './config.js';
+/**
+ * 把主体和测试名称编码成合法 TS 字符串字面量，不将业务文案作为生成代码拼接执行。
+ */
 const q = (s) => JSON.stringify(s);
+/**
+ * 生成每个测试文件的共享 setup/teardown 代码，使用领域入口建立 testkit 环境。
+ * @param domainImport 生成目录到 domain 的导入路径。
+ * @returns 源码行数组；仅拼接文本，不初始化数据库。
+ */
 function header(domainImport) {
     return [
         '// 生成物：派生测试（cage test 每次运行前重新生成，不要手改）',
@@ -17,9 +30,24 @@ function header(domainImport) {
         '',
     ];
 }
+/**
+ * 筛选当前本体中的命令节点，作为派生验证的主体集合。
+ */
 const commands = (g) => g.nodes.filter((n) => n.kind === 'command');
+/**
+ * 只为声明允许 user 的命令生成用户能力验证，内部流程命令不补造用户入口。
+ */
 const userInvokable = (c) => c.attrs.invokedBy.includes('user');
+/**
+ * 从命令能力标识取得聚合前缀，与抽取器使用的 Aggregate.command 命名约定一致。
+ */
 const aggOf = (c) => c.id.split('.')[0];
+/**
+ * 按本体生成通用性质用例文本及 subject 索引。
+ * @param cfg 决定生成目录和领域导入相对路径。
+ * @param g 当前本体，提供用户调用能力、状态、范围和不变量。
+ * @returns 待写文件内容与用例索引；不写盘、不执行测试，skip 处理留在生成用例里。
+ */
 export function deriveTests(cfg, g) {
     const dir = abs(cfg, join(cfg.generated, 'tests'));
     const domainImport = relative(dir, abs(cfg, cfg.domain))
@@ -126,6 +154,12 @@ export function deriveTests(cfg, g) {
     }
     return { files, tests };
 }
+/**
+ * 写入本轮派生测试，先清理当前生成器拥有的固定文件名。
+ * @param cfg 决定 generated/tests 位置。
+ * @param files deriveTests 产生的文件映射。
+ * @returns 测试目录绝对路径；用户额外文件不会被递归删除，IO 失败直接抛出。
+ */
 export function writeDerived(cfg, files) {
     const dir = abs(cfg, join(cfg.generated, 'tests'));
     // 只清理本生成器拥有的测试文件，不递归删除配置指向的整个目录。
@@ -139,6 +173,12 @@ export function writeDerived(cfg, files) {
         writeFileSync(join(dir, name), content);
     return dir;
 }
+/**
+ * 生成用于本次测试进程的 Vitest 配置字符串。
+ * @param cfg 应用根与派生测试位置。
+ * @param only derived 仅派生、project 仅项目，省略时两者都包含。
+ * @returns 使用 testkit 全局准备的配置源码；超时单位为毫秒，不在此处启动测试。
+ */
 export function vitestConfig(cfg, only) {
     const include = only === 'derived'
         ? [`${cfg.generated}/tests/**/*.test.ts`]

package/dist/derive.js.map

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

package/dist/dev.d.ts

@@ -1,2 +1,8 @@
 import { type CageConfig } from './config.js';
+/**
+ * 启动并持有本地开发进程，等待退出后完成资源清理。
+ * @param cfg API、worker、Web 和 domain 的应用布局。
+ * @returns 正常中止返回零，生成或子进程异常返回失败码/抛错；完成前回收本次子进程。
+ * 运行态移除管理员、迁移和测试连接，只传业务与读连接；热生成串行化不等于数据库迁移。
+ */
 export declare function dev(cfg: CageConfig): Promise<number>;

package/dist/dev.js

@@ -1,3 +1,8 @@
+/**
+ * 本地开发进程编排入口，连接应用已配置数据库并启动 API、worker 与 Vite。
+ * 首次生成声明产物，随后用 tsx watch 重启服务，并串行处理领域变更触发的生成任务。
+ * 不安装或创建数据库、不执行迁移；退出时关闭 watcher 和本次子进程，Windows 通过进程树回收 watch 子进程。
+ */
 // 本地开发只编排 API、worker 和 Vite，数据库由使用方提供。
 // 缺少连接配置就报错，不自动启动数据库；表结构迁移由开发者审查后单独执行。
 import { watch } from 'node:fs';
@@ -8,6 +13,12 @@ import { execFile } from 'node:child_process';
 import { urlsFromEnv } from '@yss123/cage-kernel';
 import { abs } from './config.js';
 import { binPath, launch, run } from './process.js';
+/**
+ * 启动并持有本地开发进程，等待退出后完成资源清理。
+ * @param cfg API、worker、Web 和 domain 的应用布局。
+ * @returns 正常中止返回零，生成或子进程异常返回失败码/抛错；完成前回收本次子进程。
+ * 运行态移除管理员、迁移和测试连接，只传业务与读连接；热生成串行化不等于数据库迁移。
+ */
 export async function dev(cfg) {
     const cli = fileURLToPath(new URL('../bin/cage.js', import.meta.url));
     const env = {

package/dist/dev.js.map

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

package/dist/doctor.d.ts

@@ -0,0 +1,98 @@
+import { type CageConfig } from './config.js';
+import { type Finding } from './findings.js';
+/**
+ * 单项诊断证据：pass 有支持证据，fail 已发现不一致，unknown 表示未检查或事实不足。
+ * 下一步是建议，不会被 doctor 自动执行；detail 只包含本项用于解释的附加数据。
+ */
+export interface Diagnostic {
+    id: string; /** pass 有证据支持，fail 已发现问题，unknown 表示事实不足。 */
+    status: 'pass' | 'fail' | 'unknown'; /** 证据来源命令、文件或运行接口说明。 */
+    source: string; /** 本次诊断采集时间，ISO 8601 字符串，不代表代码最后修改时间。 */
+    observedAt: string; /** 当前状态及其依据的中文解释。 */
+    reason: string; /** 建议后续动作；doctor 不执行这些命令。 */
+    next: string[]; /** 可选原始解释数据，缺省表示本项没有额外明细。 */
+    detail?: unknown;
+}
+/**
+ * 运行服务返回的可选事实形状；缺少字段代表证据不足，不用磁盘状态补造。
+ */
+export interface RuntimeEvidence {
+    /** 实际 API 进程报告的框架版本；缺失时无法比较。 */
+    version?: string; /** 运行进程加载注册表的指纹，不使用源码指纹冒充。 */
+    registryHash?: string; /** 运行进程报告的注册加载时间。 */
+    loadedAt?: string; /** 服务自报的运行角色，用于附加诊断。 */
+    role?: string;
+    /** worker 的版本、注册指纹及就绪/心跳事实；缺失不能解释为未启动。 */
+    worker?: {
+        version?: string;
+        registryHash?: string;
+        ready?: boolean;
+        lastHeartbeatAt?: string;
+    };
+    /** 实例报告的已配置能力点集合，不代表当前主体可执行任意命令。 */
+    authorization?: {
+        configuredCapabilities?: string[];
+    };
+    /** 实例报告的已执行迁移名称，用于与源码要求比较。 */
+    migrations?: {
+        applied?: string[];
+    };
+}
+/**
+ * 收集源码、生成物、构建与可选实际进程状态。
+ * @param cfg 应用配置，源与编译入口按标准 src→dist 布局对应。
+ * @param options 可提供运行地址、受控 Cookie 文件和测试用 fetch；省略地址只做离线检查。
+ * @returns checks、注册链、路由和历史验证；ok 允许 unknown，complete 才要求无 unknown。
+ * 运行态连接异常降为 unknown，源码分析或本地文件异常仍可抛出；不修改业务或运行状态。
+ */
+export declare function doctor(cfg: CageConfig, options?: {
+    runtimeUrl?: string;
+    cookieFile?: string;
+    fetch?: typeof fetch;
+}): Promise<{
+    schemaVersion: number;
+    cliVersion: string;
+    observedAt: string;
+    project: string;
+    registryHash: string | undefined;
+    sourceHash: string | undefined;
+    registryHashSource: string | null;
+    ok: boolean;
+    complete: boolean;
+    checks: Diagnostic[];
+    findings: Finding[];
+    registration: {
+        declaration: {
+            name: string;
+            kind: string;
+            file: string;
+            line: number;
+        };
+        domainEntry: string;
+        exports: {
+            name: string;
+            file: string;
+            line: number;
+            exportedAs: string[];
+            chain: string[];
+        } | undefined;
+        registered: boolean;
+        nodes: {
+            key: string;
+            attrs: {
+                event: unknown;
+                command: unknown;
+                tx: unknown;
+                order: unknown;
+                collection: unknown;
+            } | undefined;
+        }[];
+    }[];
+    routes: {
+        method: string;
+        url: string;
+        capability: string;
+    }[];
+    previousVerification: any;
+    limitations: string[];
+}>;

package/dist/doctor.js

@@ -0,0 +1,93 @@
+/**
+ * 把源码、生成物、编译产物与可选运行证据汇总为只读状态诊断。
+ * 离线阶段重新分析声明并比较生成物；提供 runtimeUrl 时通过受权限保护的 HTTP 接口获取实际进程事实。
+ * pass、fail、unknown 明确区分证据结论；本模块不迁移、不授权、不重启服务，也不把历史 verify 报告当成当前验证。
+ */
+// Status is evidence, not a replacement for verify. Offline inspection never grants access or applies migrations.
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { readMigrations, SYSTEM_MIGRATIONS } from '@yss123/cage-kernel/db';
+import * as kernel from '@yss123/cage-kernel';
+import { abs } from './config.js';
+import { analyze } from './analyze.js';
+import { generate, routes } from './gen/index.js';
+import { errorsOnly } from './findings.js';
+import { VERSION } from './version.js';
+import { loadRegistry } from './load.js';
+import { runtimeDiagnostic } from './runtime-diagnostics.js';
+/**
+ * 收集源码、生成物、构建与可选实际进程状态。
+ * @param cfg 应用配置，源与编译入口按标准 src→dist 布局对应。
+ * @param options 可提供运行地址、受控 Cookie 文件和测试用 fetch；省略地址只做离线检查。
+ * @returns checks、注册链、路由和历史验证；ok 允许 unknown，complete 才要求无 unknown。
+ * 运行态连接异常降为 unknown，源码分析或本地文件异常仍可抛出；不修改业务或运行状态。
+ */
+export async function doctor(cfg, options = {}) {
+    const observedAt = new Date().toISOString();
+    const checks = [];
+    const add = (id, status, source, reason, next, detail) => checks.push({ id, status, source, observedAt, reason, next, detail });
+    const result = await analyze(cfg, { registration: true });
+    const findings = [...result.findings];
+    add('registered', result.registry && !errorsOnly(result.findings).length ? 'pass' : 'fail', 'analyze/check', '静态声明、导出、注册与图规则', ['cage check'], result.findings);
+    let generated = [];
+    if (result.registry && result.graph) {
+        generated = generate(cfg, result.registry, result.graph, result.source.sites, { check: true }).findings;
+        findings.push(...generated);
+        add('generated', errorsOnly(generated).length ? 'fail' : 'pass', 'gen --check', '契约及迁移草稿与声明的一致性', ['cage gen --check', 'cage gen，然后审查差异'], generated);
+    }
+    else
+        add('generated', 'unknown', 'gen --check', '声明失败，无法比较生成物', ['cage check']);
+    const sourceHash = result.registry ? kernel.registryFingerprint(result.registry) : undefined;
+    const compiledEntry = /([\\/])src([\\/])/.test(cfg.domain) ? cfg.domain.replace(/([\\/])src([\\/])/, '$1dist$2').replace(/\.tsx?$/, '.js') : '';
+    const compiledExists = !!compiledEntry && existsSync(abs(cfg, compiledEntry));
+    const stale = result.source.files.filter(file => {
+        const compiled = file.replace(/([\\/])src([\\/])/, '$1dist$2').replace(/\.tsx?$/, '.js');
+        return compiled !== file && (!existsSync(abs(cfg, compiled)) || statSync(abs(cfg, file)).mtimeMs > statSync(abs(cfg, compiled)).mtimeMs);
+    });
+    let registryHash;
+    if (compiledExists)
+        registryHash = kernel.registryFingerprint((await loadRegistry(abs(cfg, compiledEntry))).registry);
+    else if (/\.js$/.test(cfg.domain))
+        registryHash = sourceHash;
+    add('build', compiledExists ? stale.length ? 'fail' : 'pass' : 'unknown', compiledEntry || 'not-inspected', compiledExists ? '源码与对应编译产物的新鲜度；运行指纹使用实际编译产物' : '缺少标准 src→dist 编译入口；非标准布局不猜测输出目录', ['构建 domain、API 与 worker 后重启进程'], { stale });
+    let runtime;
+    let runtimeReason = '未提供 --runtime-url，未检查运行进程或数据库';
+    if (options.runtimeUrl) {
+        try {
+            const response = await runtimeDiagnostic(cfg, options, '/api/sys/diagnostics');
+            if (!response.ok)
+                runtimeReason = `运行证据不可读取（HTTP ${response.status}），需要 Sys.ops.read`;
+            else
+                runtime = response.data;
+        }
+        catch {
+            runtimeReason = '运行证据不可读取；检查服务、地址和受控凭证文件';
+        }
+    }
+    const source = options.runtimeUrl ? 'GET /api/sys/diagnostics' : 'not-inspected';
+    const extensions = result.registry?.systemDdl.map((sql, index) => `cage:ext_${createHash('sha256').update(sql).digest('hex').slice(0, 16)}_${index}`) ?? [];
+    const migrations = [...SYSTEM_MIGRATIONS.map(m => m.name), ...extensions, ...(result.registry?.systemMigrations.map(m => m.name) ?? []), ...readMigrations(abs(cfg, cfg.migrations)).map(m => m.name)];
+    const applied = runtime?.migrations?.applied;
+    const pending = applied ? migrations.filter(name => !applied.includes(name)) : undefined;
+    add('migration', pending ? pending.length ? 'fail' : 'pass' : 'unknown', source, pending ? `${pending.length} 个未执行项目迁移` : runtimeReason, ['审查迁移后显式 cage migrate'], { files: migrations, pending });
+    const configured = runtime?.authorization?.configuredCapabilities;
+    const roleRequired = result.registry ? new Set([
+        ...result.registry.commands.filter(c => c.cmd.invokedBy.includes('user')).map(c => c.capability),
+        ...result.registry.aggregates.map(a => `${a.name}.read`),
+        ...result.registry.approvals.flatMap(({ a }) => [result.registry.capabilityOf(a.onApproved), result.registry.capabilityOf(a.onRejected), ...(a.onReturned ? [result.registry.capabilityOf(a.onReturned)] : [])]),
+    ]) : undefined;
+    const missing = configured && roleRequired ? [...roleRequired].filter(c => !configured.includes(c)) : undefined;
+    add('authorization', missing ? missing.length ? 'fail' : 'pass' : 'unknown', source, missing ? '检查用户入口、读取和审批结论是否配置角色；内部任务命令不要求授予用户' : runtimeReason, ['管理员按角色、范围与额度显式配置业务授权'], { unconfigured: missing, optionalUnconfigured: configured && result.registry?.capabilityCatalog().filter(c => !roleRequired?.has(c.capability) && !configured.includes(c.capability)).map(c => c.capability) });
+    const matching = (version, hash) => version && hash && registryHash ? version === VERSION && hash === registryHash ? 'pass' : 'fail' : 'unknown';
+    add('api', matching(runtime?.version, runtime?.registryHash), source, runtime ? '比较实际 API 版本与注册指纹' : runtimeReason, ['构建并重启 API/worker，重新获取运行证据'], runtime && { version: runtime.version, registryHash: runtime.registryHash, loadedAt: runtime.loadedAt });
+    add('worker', runtime?.worker?.ready === false ? 'fail' : matching(runtime?.worker?.version, runtime?.worker?.registryHash), source, runtime?.worker ? '比较 worker 就绪、版本与注册指纹' : runtimeReason, ['检查 worker 心跳、消费者就绪与实际加载版本'], runtime?.worker);
+    const registration = result.source.sites.map(site => ({ declaration: { name: site.exportName, kind: site.primitive, file: site.file, line: site.line }, domainEntry: cfg.domain,
+        exports: result.registration?.find(entry => entry.name === site.exportName && entry.file === site.file),
+        registered: !result.findings.some(f => f.code === 'CAGE-DECL-002' && f.at === `${site.file}:${site.line}`),
+        nodes: result.graph?.nodes.filter(n => n.file === site.file && n.line === site.line).map(n => ({ key: `${n.kind}:${n.id}`, attrs: n.kind === 'reaction' ? { event: n.attrs.event, command: n.attrs.command, tx: n.attrs.tx, order: n.attrs.order, collection: n.attrs.collection } : undefined })) ?? [] }));
+    const verifyFile = abs(cfg, '.cage/verify.json');
+    return { schemaVersion: 1, cliVersion: VERSION, observedAt, project: cfg.name, registryHash, sourceHash, registryHashSource: compiledExists ? compiledEntry : /\.js$/.test(cfg.domain) ? cfg.domain : null, ok: checks.every(c => c.status !== 'fail'), complete: checks.every(c => c.status !== 'unknown'), checks, findings, registration,
+        routes: result.registry ? routes(result.registry) : [], previousVerification: existsSync(verifyFile) ? JSON.parse(readFileSync(verifyFile, 'utf8')) : null,
+        limitations: ['已有 verify 报告只代表过去一次执行，不证明当前代码已验证。', '未检查的依赖标为 unknown。doctor 不执行迁移、测试、授权或重启进程。'] };
+}
+//# sourceMappingURL=doctor.js.map

package/dist/doctor.js.map

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

package/dist/env.d.ts

@@ -1 +1,7 @@
+/**
+ * 将本地配置补入指定环境对象，已有同名值优先。
+ * @param root 应用根目录，只读取其 .env。
+ * @param env 要原地补充的环境对象，默认 process.env。
+ * 文件缺失时无副作用；不会输出值，读取或解析失败向上抛出。
+ */
 export declare function loadProjectEnv(root: string, env?: NodeJS.ProcessEnv): void;

package/dist/env.js

@@ -1,8 +1,19 @@
+/**
+ * 供需要运行环境的 CLI 子命令加载应用 .env，统一使用 Node 的 dotenv 解析规则。
+ * 只补充目标环境对象中尚未定义的键，已有部署变量及空字符串均保持原值。
+ * 读取内容不做 shell 展开、不打印秘密；缺少文件是无操作，解析或文件读取异常交给命令入口处理。
+ */
 // CLI 从项目根目录读取本地连接配置。显式传入的环境变量优先，CI/部署可以覆盖本地值。
 // 使用 Node 自带的 dotenv 解析器，不展开 shell 表达式，也不打印文件中的凭证。
 import { existsSync, readFileSync } from 'node:fs';
 import { parseEnv } from 'node:util';
 import { join } from 'node:path';
+/**
+ * 将本地配置补入指定环境对象，已有同名值优先。
+ * @param root 应用根目录，只读取其 .env。
+ * @param env 要原地补充的环境对象，默认 process.env。
+ * 文件缺失时无副作用；不会输出值，读取或解析失败向上抛出。
+ */
 export function loadProjectEnv(root, env = process.env) {
     const file = join(root, '.env');
     if (!existsSync(file))

package/dist/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAC/C,mDAAmD;AACnD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,MAAyB,OAAO,CAAC,GAAG;IAC/E,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO;IAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACjF,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACjD,CAAC;AACH,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../src/env.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,+CAA+C;AAC/C,mDAAmD;AACnD,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,MAAyB,OAAO,CAAC,GAAG;IAC/E,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO;IAC9B,KAAK,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QACjF,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;IACjD,CAAC;AACH,CAAC"}

package/dist/findings.d.ts

@@ -1,11 +1,38 @@
+/**
+ * 静态分析与门禁共享的诊断数据和终端格式化工具。
+ * 规则产生 code、位置、原因与可选修复建议，再由这里关联本地错误码册。
+ * 格式化是纯文本转换；severity 省略时按错误处理，只有明确 warning 才不阻止门禁。
+ */
+/**
+ * 静态检查和门禁的一条诊断，按 code 链接逐码说明，支持可选源码位置与修复方向。severity 缺省按错误处理。
+ */
 export interface Finding {
+    /** 稳定 CAGE 错误码，链接到统一错误码册。 */
     code: string;
     /** 文件:行 */
     at?: string;
+    /** 具体失败原因，不仅是错误类别标题。 */
     reason: string;
+    /** 可选可执行修复建议；不存在时由上层补通用定位信息。 */
     fix?: string;
+    /** warning 不阻断 errorsOnly；缺省按 error 处理。 */
     severity?: 'error' | 'warning';
 }
+/**
+ * 生成单条人类可读诊断及本地错误码册路径。
+ * @param f 原始诊断，缺位置或 fix 时对应行按实现省略。
+ * @returns 多行文本；不读取或验证目标文档。
+ */
 export declare function formatFinding(f: Finding): string;
+/**
+ * 按输入顺序拼接诊断，空列表返回空字符串。
+ * @param list 不会被修改的诊断数组。
+ * @returns 条目间空行分隔的终端文本。
+ */
 export declare function formatFindings(list: Finding[]): string;
+/**
+ * 筛选阻止门禁的诊断，只有显式 warning 被排除。
+ * @param list 原始列表，不会被修改。
+ * @returns severity 缺省或为 error 的条目。
+ */
 export declare const errorsOnly: (list: Finding[]) => Finding[];

package/dist/findings.js

@@ -1,4 +1,14 @@
+/**
+ * 静态分析与门禁共享的诊断数据和终端格式化工具。
+ * 规则产生 code、位置、原因与可选修复建议，再由这里关联本地错误码册。
+ * 格式化是纯文本转换；severity 省略时按错误处理，只有明确 warning 才不阻止门禁。
+ */
 // 门禁报错：每条都有错误码、位置、原因、修复方法，末尾附错误码册路径，agent 可以直接打开。
+/**
+ * 生成单条人类可读诊断及本地错误码册路径。
+ * @param f 原始诊断，缺位置或 fix 时对应行按实现省略。
+ * @returns 多行文本；不读取或验证目标文档。
+ */
 export function formatFinding(f) {
     const lines = [`  [${f.code}] ${f.at ?? ''}`.trimEnd(), `  原因：${f.reason}`];
     if (f.fix)
@@ -6,8 +16,18 @@ export function formatFinding(f) {
     lines.push(`  详见：docs/errors/${f.code}.md`);
     return lines.join('\n');
 }
+/**
+ * 按输入顺序拼接诊断，空列表返回空字符串。
+ * @param list 不会被修改的诊断数组。
+ * @returns 条目间空行分隔的终端文本。
+ */
 export function formatFindings(list) {
     return list.map(formatFinding).join('\n\n');
 }
+/**
+ * 筛选阻止门禁的诊断，只有显式 warning 被排除。
+ * @param list 原始列表，不会被修改。
+ * @returns severity 缺省或为 error 的条目。
+ */
 export const errorsOnly = (list) => list.filter((f) => f.severity !== 'warning');
 //# sourceMappingURL=findings.js.map

package/dist/findings.js.map

@@ -1 +1 @@
-{"version":3,"file":"findings.js","sourceRoot":"","sources":["../src/findings.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAWlD,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,IAAI,CAAC,CAAC,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC;IAC5C,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,IAAe;IAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAe,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC"}
+{"version":3,"file":"findings.js","sourceRoot":"","sources":["../src/findings.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,kDAAkD;AAkBlD;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,IAAI,CAAC,CAAC,GAAG;QAAE,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IACvC,KAAK,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC;IAC5C,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,IAAe;IAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,aAAa,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC9C,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,IAAe,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC"}

package/dist/gen/contracts.d.ts

@@ -1,6 +1,34 @@
+/**
+ * 将注册表转换为浏览器可用的契约源码字符串，由 generate 统一写盘。
+ * 按聚合组织读侧 schema、用户命令方法和 hooks，再生成查询与根公共入口。
+ * 不把 domain 或运行时导入浏览器；仅开放 user 命令，客户端校验保留可表达部分，服务端始终负责权威校验与授权。
+ */
 import { type AnyAggregate, type Registry } from '@yss123/cage-kernel';
 import type { DeclSite } from '../static-check.js';
+/**
+ * 生成单个聚合的浏览器契约文件文本。
+ * @param reg 注册表，用于筛选允许 user 调用的命令和关系目标。
+ * @param a 当前聚合。
+ * @param sites 静态位置，用于提取业务错误码。
+ * @returns schema、方法、hooks 与缓存键源码；不写盘、不发网络请求。
+ */
 export declare function aggregateFile(reg: Registry, a: AnyAggregate, sites: DeclSite[]): string;
+/**
+ * 生成所有显式查询的输入 schema、请求方法和 hooks。
+ * @param reg 已注册查询清单。
+ * @returns 源码文本；查询响应仍为通用记录数组，实际范围由服务器执行。
+ */
 export declare function queriesFile(reg: Registry): string;
+/**
+ * 生成契约根公共入口及能力名类型、客户端转导出。
+ * @param reg 当前注册表。
+ * @returns 根 index 源码，can/useCan 仅用于前端显示，不产生授权。
+ */
 export declare function indexFile(reg: Registry): string;
+/**
+ * 按稳定聚合名组织所有待生成契约，后端模块移动不改变契约公开入口。
+ * @param reg 注册表。
+ * @param sites 声明位置与业务错误码线索。
+ * @returns 相对路径到源码字符串的映射；实际写入由 generate 负责。
+ */
 export declare function contractsFiles(reg: Registry, sites: DeclSite[]): Record<string, string>;