@yss123/cage-cli 0.1.0 → 0.3.0

package/dist/graph-model.js

@@ -0,0 +1,134 @@
+/**
+ * 节点类型的固定中文词汇，CLI 报告和浏览器共用；只影响呈现，不改变本体 kind。
+ */
+export const kindLabels = {
+    aggregate: '业务对象',
+    command: '命令',
+    event: '事件',
+    reaction: '反应',
+    query: '查询',
+    approval: '审批',
+    route: '审批路由',
+    job: '定时任务',
+    connector: '连接器',
+    outbound: '出站映射',
+    inbound: '入站回调',
+    field: '字段',
+    state: '状态',
+    capability: '能力点',
+    entry: '新建入口',
+    process: '业务流程',
+    stage: '业务阶段',
+};
+/**
+ * 本体及展示归属边的中文短名，未知扩展关系由具体解释层处理。
+ */
+export const edgeLabels = {
+    transition: '状态迁移',
+    reads: '读取',
+    emits: '发出',
+    uses: '使用字段',
+    triggers: '触发',
+    cancels: '取消审批',
+    targets: '调用目标',
+    queries: '查询',
+    refs: '引用',
+    calls: '调用',
+    binds: '审批绑定',
+    field: '声明字段',
+    ownership: '归属（标识推导）',
+    contains: '包含业务阶段',
+    implements: '阶段实现',
+    follows: '业务下一步',
+    relates: '关联业务对象',
+};
+/** graph.labels 的显示覆盖不参与本体哈希；声明内的 description 仍由抽取器
+ * 按该声明的含义处理。中文展示不会替换路由、权限或数据表使用的稳定标识。 */
+/**
+ * 按显示覆盖、标题、description、原 ID 的顺序选择文案。
+ * @param node 展示节点，虚拟 entry 固定使用新建入口文案。
+ * @param labels 仅用于显示的中文映射。
+ * @returns 展示名称，不修改节点或业务标识。
+ */
+export function nodeLabel(node, labels = {}) {
+    if (node.kind === 'entry')
+        return '新建入口';
+    return labels[node.key] || String(node.attrs.title || node.attrs.description || node.id);
+}
+/**
+ * 将本体 ID 按关系端点类型转成唯一 key，并补新建入口及归属边。
+ * @param graph 原始本体，不会被修改。
+ * @returns 新展示模型；无法匹配两端的关系不输出，派生 ownership 不代表调用。
+ */
+export function projectGraph(graph) {
+    const nodes = graph.nodes.map((n) => ({ ...n, key: `${n.kind}:${n.id}` }));
+    const edges = [];
+    const find = (id, kinds) => nodes.find((n) => n.id === id && kinds.includes(n.kind));
+    // 原始边以业务 ID 存端点；投影时按关系类型恢复端点身份，不能猜成同名的状态或能力点。
+    const endpoints = {
+        transition: [['state', 'entry'], ['state']],
+        field: [['aggregate'], ['field']],
+        refs: [['field'], ['aggregate']],
+        reads: [['command'], ['aggregate']],
+        queries: [['query', 'job'], ['aggregate']],
+        emits: [['command'], ['event']],
+        triggers: [['event'], ['reaction', 'approval', 'outbound']],
+        cancels: [['event'], ['approval']],
+        targets: [
+            ['reaction', 'outbound', 'inbound'],
+            ['command', 'connector'],
+        ],
+        calls: [['job'], ['command']],
+        binds: [
+            ['route', 'approval'],
+            ['approval', 'command'],
+        ],
+        uses: [['command', 'event', 'query', 'approval', 'route', 'outbound'], ['field']],
+        contains: [['process'], ['stage']],
+        implements: [['stage'], ['command', 'event', 'reaction', 'query', 'approval', 'job', 'inbound', 'outbound']],
+        follows: [['stage'], ['stage']],
+        relates: [['process', 'stage'], ['aggregate']],
+    };
+    for (const edge of graph.edges) {
+        const [fromKinds, toKinds] = endpoints[edge.kind];
+        let from = find(edge.from, edge.fromKind ? [edge.fromKind] : fromKinds);
+        const to = find(edge.to, edge.toKind ? [edge.toKind] : toKinds);
+        if (!from && edge.kind === 'transition' && edge.from.endsWith('.[new]')) {
+            from = { key: `entry:${edge.from}`, id: edge.from, kind: 'entry', hash: '', attrs: {} };
+            nodes.push(from);
+        }
+        if (from && to)
+            edges.push({ ...edge, from: from.key, to: to.key, key: `edge:${edges.length}`, derived: false });
+    }
+    for (const node of nodes) {
+        if (!['command', 'state', 'capability', 'entry'].includes(node.kind))
+            continue;
+        const owner = nodes.find((n) => n.kind === 'aggregate' && node.id.startsWith(`${n.id}.`));
+        if (owner)
+            edges.push({
+                key: `owner:${node.key}`,
+                kind: 'ownership',
+                from: owner.key,
+                to: node.key,
+                derived: true,
+            });
+    }
+    return { nodes, edges };
+}
+/**
+ * 计算节点的一跳无向邻域，供画布高亮。
+ * @param model 展示图。
+ * @param key 完整节点身份。
+ * @returns 包含自身和直接邻居的集合；不继续传递，不区分执行方向。
+ */
+export function neighborhood(model, key) {
+    const connected = new Set([key]);
+    for (const edge of model.edges) {
+        if (edge.from === key)
+            connected.add(edge.to);
+        if (edge.to === key)
+            connected.add(edge.from);
+    }
+    return connected;
+}
+//# sourceMappingURL=graph-model.js.map

package/dist/graph-model.js.map

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

package/dist/graph-presentation.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 为 CLI 查询与浏览器图谱装配中文名称和标题，输入为配置与已构建注册表。
+ * 先收集声明 description 和状态标签，再用 graph.labels 覆盖短标题，同时保留原描述用于检索。
+ * 展示元数据与本体语义哈希分离，不改变能力点、数据表或实际路由，也不执行任何 IO。
+ */
+import type { Registry } from '@yss123/cage-kernel';
+import type { CageConfig } from './config.js';
+/**
+ * 独立于本体的展示标题、覆盖标签和原始描述，用于名称检索及中文呈现。
+ */
+export interface GraphPresentation {
+    /** 图谱页面与报告的项目标题。 */
+    title: string;
+    /** 以完整节点 key、模块或角色身份为键的显示覆盖。 */
+    labels: Record<string, string>;
+    /** 配置可覆盖短标题，检索仍保留声明原描述，避免丢失业务关键词。 */
+    descriptions?: Record<string, string>;
+}
+/** 图谱、CLI 检索和 AI 上下文复用同一套中文名称。graph.labels 的显示覆盖
+ * 与语义图分开，不被 impact 当成业务变化；配置短标题优先于声明的长描述。 */
+/**
+ * 收集声明文案并合并应用配置覆盖。
+ * @param cfg graph.title/labels 的来源。
+ * @param registry 已校验注册表。
+ * @returns labels 用于展示，descriptions 保留声明原文；不修改本体哈希。
+ */
+export declare function graphPresentation(cfg: CageConfig, registry: Registry): GraphPresentation;

package/dist/graph-presentation.js

@@ -0,0 +1,34 @@
+/** 图谱、CLI 检索和 AI 上下文复用同一套中文名称。graph.labels 的显示覆盖
+ * 与语义图分开，不被 impact 当成业务变化；配置短标题优先于声明的长描述。 */
+/**
+ * 收集声明文案并合并应用配置覆盖。
+ * @param cfg graph.title/labels 的来源。
+ * @param registry 已校验注册表。
+ * @returns labels 用于展示，descriptions 保留声明原文；不修改本体哈希。
+ */
+export function graphPresentation(cfg, registry) {
+    const labels = {};
+    const remember = (kind, id, description) => {
+        if (description)
+            labels[`${kind}:${id}`] = description;
+    };
+    for (const a of registry.aggregates) {
+        remember('aggregate', a.name, a.description);
+        for (const [state, label] of Object.entries(a.states.labels))
+            remember('state', `${a.name}.${state}`, label);
+    }
+    for (const c of registry.commands)
+        remember('command', c.capability, c.cmd.description);
+    for (const e of registry.events)
+        remember('event', e.name, e.description);
+    for (const q of registry.queries)
+        remember('query', q.name, q.description);
+    for (const j of registry.jobs)
+        remember('job', j.name, j.description);
+    return {
+        title: cfg.graph?.title ?? cfg.name,
+        labels: { ...labels, ...cfg.graph?.labels },
+        descriptions: labels,
+    };
+}
+//# sourceMappingURL=graph-presentation.js.map

package/dist/graph-presentation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-presentation.js","sourceRoot":"","sources":["../src/graph-presentation.ts"],"names":[],"mappings":"AAoBA;6CAC6C;AAC7C;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAe,EAAE,QAAkB;IACnE,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,MAAM,QAAQ,GAAG,CAAC,IAAY,EAAE,EAAU,EAAE,WAAoB,EAAE,EAAE;QAClE,IAAI,WAAW;YAAE,MAAM,CAAC,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC,GAAG,WAAW,CAAC;IACzD,CAAC,CAAC;IACF,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,UAAU,EAAE,CAAC;QACpC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;QAC7C,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC;YAAE,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,IAAI,IAAI,KAAK,EAAE,EAAE,KAAK,CAAC,CAAC;IAC/G,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,QAAQ;QAAE,QAAQ,CAAC,SAAS,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IACxF,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,MAAM;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IAC1E,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,OAAO;QAAE,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IAC3E,KAAK,MAAM,CAAC,IAAI,QAAQ,CAAC,IAAI;QAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IACtE,OAAO;QACL,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,KAAK,IAAI,GAAG,CAAC,IAAI;QACnC,MAAM,EAAE,EAAE,GAAG,MAAM,EAAE,GAAG,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE;QAC3C,YAAY,EAAE,MAAM;KACrB,CAAC;AACJ,CAAC"}

package/dist/graph-query.d.ts

@@ -0,0 +1,266 @@
+import type { GraphSnapshot } from './graph-snapshot.js';
+import { type ViewEdge, type ViewNode } from './graph-model.js';
+import { type GraphSearchHit } from './graph-search.js';
+/**
+ * 源码定位证据，precision 区分声明本身与只能定位到所属聚合；不伪造字段行号。
+ */
+export interface SourceReference {
+    /** 项目相对源码路径，不能当作任意文件读取授权。 */
+    file: string;
+    /** 可选 1 起始行号，未知时不补造。 */
+    line?: number;
+    /** declaration 精确到声明，aggregate 仅定位到所属聚合。 */
+    precision: 'declaration' | 'aggregate';
+}
+/**
+ * 查询报告中的节点事实，保留稳定身份、展示名、内容指纹和可空源码位置。
+ */
+export interface GraphNodeInfo {
+    /** 带节点种类的稳定唯一身份。 */
+    key: string;
+    /** 领域原始标识，用于理解声明与能力名称。 */
+    id: string;
+    /** 展示节点类型，允许虚拟 entry。 */
+    kind: ViewNode['kind'];
+    /** kind 的固定中文名称。 */
+    kindLabel: string;
+    /** 按图谱展示规则选择的可读名称。 */
+    label: string;
+    /** 节点内容指纹；虚拟入口可为空字符串。 */
+    hash: string;
+    /** 源码位置证据，null 表示索引无法定位。 */
+    source: SourceReference | null;
+    /** 抽取的声明属性，不包含业务记录数据。 */
+    attrs: Record<string, unknown>;
+}
+/**
+ * 带中文解释和来源强度的关系；方向仍按原声明，不随路径逆向遍历改变。
+ */
+export interface GraphRelationInfo extends ViewEdge {
+    /** 关系短标题，便于画布和报告阅读。 */
+    label: string;
+    /** 这条关系由哪些声明内容产生。 */
+    why: string;
+    /** 关系对业务阅读或维护的用途说明。 */
+    purpose: string;
+    /** 按照声明方向阅读的中文说明，不随查询反向遍历更改。 */
+    direction: string;
+    /** 声明、标识推导或文本匹配的来源强度及定位。 */
+    evidence: {
+        basis: 'declared' | 'inferred' | 'text-match';
+        entries: string[];
+        source: SourceReference | null;
+    };
+}
+/**
+ * 精确选择器解析结果，歧义或未命中时返回候选供调用方明确选择。
+ */
+export interface NodeResolution {
+    /** 调用方原始选择器，用于报告回显。 */
+    selector: string;
+    /** ok 唯一命中，ambiguous 需要消歧，not-found 只有候选或无结果。 */
+    status: 'ok' | 'ambiguous' | 'not-found';
+    /** 精确匹配或相近检索候选，不能在歧义时偷偷选第一项。 */
+    candidates: GraphSearchHit[];
+}
+/**
+ * 所有图查询共用的能力边界说明，必须随报告交付以免把静态关系解释成运行结果。
+ */
+export declare const graphLimits: string[];
+/**
+ * 建立单次快照的索引和解释函数，不再次抽取或读取源码。
+ * @param snapshot 当前图及展示信息。
+ * @param freshness 区分新进程抽取与页面已显示快照。
+ * @returns 节点/关系访问器、精确解析、搜索和带时间指纹的公共元数据。
+ */
+export declare function graphReader(snapshot: GraphSnapshot, freshness?: 'fresh-extraction' | 'displayed-snapshot'): {
+    model: import("./graph-model.js").GraphModel;
+    byKey: Map<string, ViewNode>;
+    meta: {
+        schemaVersion: 1;
+        project: string;
+        domain: string;
+        extractedAt: string;
+        freshness: "fresh-extraction" | "displayed-snapshot";
+        graphHash: string;
+        findings: import("./findings.js").Finding[];
+        limitations: string[];
+    };
+    sourceOf: (node: ViewNode) => SourceReference | null;
+    nodeInfo: (node: ViewNode) => GraphNodeInfo;
+    relationInfo: (edge: ViewEdge) => GraphRelationInfo;
+    search: (query: string, kind?: ViewNode["kind"]) => GraphSearchHit[];
+    resolve: (selector: string) => NodeResolution;
+};
+/**
+ * 查询关键词并附源码位置，截断时仍报告完整命中总数。
+ * @param snapshot 单次快照。
+ * @param query 查询词。
+ * @param options limit 默认 10，kind 可限制类型。
+ * @returns 候选报告；没有命中返回 not-found，不表示框架不支持需求。
+ */
+export declare function searchGraph(snapshot: GraphSnapshot, query: string, options?: {
+    limit?: number;
+    kind?: ViewNode['kind'];
+}): {
+    operation: "search";
+    status: "ok" | "not-found";
+    query: string;
+    total: number;
+    truncated: boolean;
+    hits: {
+        source: SourceReference | null;
+        key: string;
+        id: string;
+        kind: ViewNode["kind"];
+        label: string;
+        score: number;
+        matches: import("./graph-search.js").SearchMatch[];
+    }[];
+    schemaVersion: 1;
+    project: string;
+    domain: string;
+    extractedAt: string;
+    freshness: "fresh-extraction" | "displayed-snapshot";
+    graphHash: string;
+    findings: import("./findings.js").Finding[];
+    limitations: string[];
+};
+/**
+ * 精确检查唯一节点及直接关联，不以模糊候选替代选择。
+ * @param snapshot 单次快照。
+ * @param selector 完整 key、唯一 ID 或唯一中文全称。
+ * @returns 节点/关联及解析状态；歧义时 node=null，并保留候选。
+ */
+export declare function inspectGraph(snapshot: GraphSnapshot, selector: string): {
+    operation: "inspect";
+    status: "ok" | "ambiguous" | "not-found";
+    resolution: NodeResolution;
+    node: GraphNodeInfo | null;
+    relations: GraphRelationInfo[];
+    schemaVersion: 1;
+    project: string;
+    domain: string;
+    extractedAt: string;
+    freshness: "fresh-extraction" | "displayed-snapshot";
+    graphHash: string;
+    findings: import("./findings.js").Finding[];
+    limitations: string[];
+};
+/**
+ * 最短路径的一跳，traversal 表示查看方向，relation 保持原箭头及证据。
+ */
+export interface GraphPathStep {
+    /** 本次遍历的起点 key。 */
+    from: string;
+    /** 本次遍历的终点 key。 */
+    to: string;
+    /** forward 顺声明方向，reverse 反向查询但不表示反向执行。 */
+    traversal: 'forward' | 'reverse';
+    /** 保留原方向及证据的完整关系。 */
+    relation: GraphRelationInfo;
+}
+/** 默认沿箭头找最短关系链；双向探索要显式选择 both，每一步保留原箭头。
+ * 归属虚线只用于整理对象，不能借它制造“任意两个命令都会互相调用”的短路。 */
+/**
+ * 广度优先寻找深度内最短声明关系链，排除派生归属边。
+ * @param snapshot 单次快照。
+ * @param from 起点选择器。
+ * @param to 终点选择器。
+ * @param options 默认 out 沿箭头、深度 6，both 允许明确标记的逆向遍历。
+ * @returns 路径或定位/深度内未找到状态；不证明实际执行先后。
+ */
+export declare function findGraphPath(snapshot: GraphSnapshot, from: string, to: string, options?: {
+    direction?: 'out' | 'both';
+    depth?: number;
+}): {
+    status: "ambiguous" | "not-found";
+    nodes: GraphNodeInfo[];
+    steps: GraphPathStep[];
+    operation: "path";
+    from: NodeResolution;
+    to: NodeResolution;
+    direction: "out" | "both";
+    depth: number;
+    schemaVersion: 1;
+    project: string;
+    domain: string;
+    extractedAt: string;
+    freshness: "fresh-extraction" | "displayed-snapshot";
+    graphHash: string;
+    findings: import("./findings.js").Finding[];
+    limitations: string[];
+} | {
+    status: "ok";
+    nodes: GraphNodeInfo[];
+    steps: GraphPathStep[];
+    operation: "path";
+    from: NodeResolution;
+    to: NodeResolution;
+    direction: "out" | "both";
+    depth: number;
+    schemaVersion: 1;
+    project: string;
+    domain: string;
+    extractedAt: string;
+    freshness: "fresh-extraction" | "displayed-snapshot";
+    graphHash: string;
+    findings: import("./findings.js").Finding[];
+    limitations: string[];
+} | {
+    status: "not-found-within-depth";
+    nodes: GraphNodeInfo[];
+    steps: GraphPathStep[];
+    operation: "path";
+    from: NodeResolution;
+    to: NodeResolution;
+    direction: "out" | "both";
+    depth: number;
+    schemaVersion: 1;
+    project: string;
+    domain: string;
+    extractedAt: string;
+    freshness: "fresh-extraction" | "displayed-snapshot";
+    graphHash: string;
+    findings: import("./findings.js").Finding[];
+    limitations: string[];
+};
+/**
+ * 格式化可空源码位置，聚合精度额外标记；没有位置时引导查公开 API，不伪造文件名。
+ */
+export declare const sourceText: (source: SourceReference | null) => string;
+/**
+ * 报告使用的证据强度中文名称，显式、推导、文本匹配不能互相替代。
+ */
+export declare const evidenceLabels: {
+    declared: string;
+    inferred: string;
+    'text-match': string;
+};
+/**
+ * 把关系解释转换为 Markdown 条目，保留原因、用途与源码。
+ * @param relation 完整关系证据。
+ * @returns 文本行数组，不执行连线所指操作。
+ */
+export declare function relationMarkdown(relation: GraphRelationInfo): string[];
+/**
+ * 输出项目、抽取时间、指纹及新鲜度说明。
+ * @param report 查询公共元数据。
+ * @param title 报告标题。
+ * @returns Markdown 头部行数组，不访问文件。
+ */
+export declare function reportHeader(report: ReturnType<typeof graphReader>['meta'], title: string): string[];
+/**
+ * 输出当前规则问题及共同边界，规则无问题也不声称测试已运行。
+ * @param report 查询元数据与 findings。
+ * @returns Markdown 尾部行数组。
+ */
+export declare function reportFooter(report: ReturnType<typeof graphReader>['meta']): string[];
+type QueryReport = ReturnType<typeof searchGraph> | ReturnType<typeof inspectGraph> | ReturnType<typeof findGraphPath>;
+/**
+ * 按 search、inspect、path 分支渲染报告，保留歧义、截断和逆向解释。
+ * @param report 查询结果联合。
+ * @returns Markdown 字符串；写盘和退出码由 graphCommand 决定。
+ */
+export declare function formatGraphQuery(report: QueryReport): string;
+export {};