@yss123/cage-cli 0.0.0-stage → 0.2.0

package/dist/graph-command.js

@@ -0,0 +1,67 @@
+// CLI 负责参数和输出；查询函数本身可组合，Web 和其他工具无需再解析终端文本。
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { abs } from './config.js';
+import { errorsOnly } from './findings.js';
+import { collectGraph } from './graph.js';
+import { kindLabels } from './graph-model.js';
+import { searchGraph, inspectGraph, findGraphPath, formatGraphQuery } from './graph-query.js';
+import { buildContext, formatContext } from './context.js';
+function integerOption(name, raw, fallback, minimum) {
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!raw.trim() || !Number.isSafeInteger(value) || value < minimum)
+        throw new Error(`--${name} 必须是大于等于 ${minimum} 的整数`);
+    return value;
+}
+export async function graphCommand(cfg, action, targets, options) {
+    const count = action === 'path' ? 2 : 1;
+    if (targets.length !== count || targets.some((target) => !target.trim()))
+        throw new Error(action === 'path'
+            ? 'graph path 需要两个节点：cage graph path <起点> <终点>'
+            : `${action} 需要一个关键词或节点；含空格的需求请用引号包住`);
+    if (options.format && !['md', 'json'].includes(options.format))
+        throw new Error('--format 只能是 md 或 json');
+    if (options.kind && !Object.hasOwn(kindLabels, options.kind))
+        throw new Error(`未知节点类型 ${options.kind}`);
+    if (options.direction && !['out', 'both'].includes(options.direction))
+        throw new Error('--direction 只能是 out 或 both');
+    const optionActions = {
+        kind: ['search'],
+        direction: ['path'],
+        depth: ['context', 'path'],
+        limit: ['context', 'search'],
+    };
+    for (const [option, actions] of Object.entries(optionActions))
+        if (options[option] !== undefined && !actions.includes(action))
+            throw new Error(`--${option} 只用于 ${actions.join(' / ')} 查询`);
+    const depth = integerOption('depth', options.depth, action === 'path' ? 6 : 3, 0);
+    const limit = integerOption('limit', options.limit, action === 'search' ? 10 : 40, 1);
+    const snapshot = await collectGraph(cfg.root);
+    const report = action === 'context'
+        ? buildContext(cfg, snapshot, targets[0], { depth, limit })
+        : action === 'search'
+            ? searchGraph(snapshot, targets[0], { limit, kind: options.kind })
+            : action === 'inspect'
+                ? inspectGraph(snapshot, targets[0])
+                : findGraphPath(snapshot, targets[0], targets[1], {
+                    depth,
+                    direction: options.direction,
+                });
+    const output = options.format === 'json'
+        ? JSON.stringify(report, null, 2)
+        : report.operation === 'context'
+            ? formatContext(report)
+            : formatGraphQuery(report);
+    if (options.out) {
+        const file = abs(cfg, options.out);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, output + '\n');
+    }
+    else
+        console.log(output);
+    // 图规则失败时仍交付上下文帮助定位，但不能用成功退出码掩盖错误。
+    return report.status === 'ok' && errorsOnly(report.findings).length === 0 ? 0 : 1;
+}
+//# sourceMappingURL=graph-command.js.map

package/dist/graph-command.js.map

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

package/dist/graph-model.d.ts

@@ -0,0 +1,21 @@
+import type { NodeKind, OntEdge, OntNode, Ontology } from './ontology.js';
+export declare const kindLabels: Record<NodeKind | 'entry', string>;
+export declare const edgeLabels: Record<string, string>;
+export interface ViewNode extends Omit<OntNode, 'kind'> {
+    key: string;
+    kind: NodeKind | 'entry';
+}
+export interface ViewEdge extends Omit<OntEdge, 'kind'> {
+    key: string;
+    kind: OntEdge['kind'] | 'ownership';
+    derived: boolean;
+}
+export interface GraphModel {
+    nodes: ViewNode[];
+    edges: ViewEdge[];
+}
+/** graph.labels 的显示覆盖不参与本体哈希；声明内的 description 仍由抽取器
+ * 按该声明的含义处理。中文展示不会替换路由、权限或数据表使用的稳定标识。 */
+export declare function nodeLabel(node: ViewNode, labels?: Record<string, string>): string;
+export declare function projectGraph(graph: Ontology): GraphModel;
+export declare function neighborhood(model: GraphModel, key: string): Set<string>;

package/dist/graph-model.js

@@ -0,0 +1,101 @@
+export const kindLabels = {
+    aggregate: '业务对象',
+    command: '命令',
+    event: '事件',
+    reaction: '反应',
+    query: '查询',
+    approval: '审批',
+    route: '审批路由',
+    job: '定时任务',
+    connector: '连接器',
+    outbound: '出站映射',
+    inbound: '入站回调',
+    field: '字段',
+    state: '状态',
+    capability: '能力点',
+    entry: '新建入口',
+};
+export const edgeLabels = {
+    transition: '状态迁移',
+    reads: '读取',
+    emits: '发出',
+    uses: '使用字段',
+    triggers: '触发',
+    cancels: '取消审批',
+    targets: '调用目标',
+    queries: '查询',
+    refs: '引用',
+    calls: '调用',
+    binds: '审批绑定',
+    field: '声明字段',
+    ownership: '归属（标识推导）',
+};
+/** graph.labels 的显示覆盖不参与本体哈希；声明内的 description 仍由抽取器
+ * 按该声明的含义处理。中文展示不会替换路由、权限或数据表使用的稳定标识。 */
+export function nodeLabel(node, labels = {}) {
+    if (node.kind === 'entry')
+        return '新建入口';
+    return labels[node.key] || String(node.attrs.description || node.id);
+}
+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']],
+    };
+    for (const edge of graph.edges) {
+        const [fromKinds, toKinds] = endpoints[edge.kind];
+        let from = find(edge.from, fromKinds);
+        const to = find(edge.to, 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 };
+}
+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,11 @@
+import type { Registry } from '@yss123/cage-kernel';
+import type { CageConfig } from './config.js';
+export interface GraphPresentation {
+    title: string;
+    labels: Record<string, string>;
+    /** 配置可覆盖短标题，检索仍保留声明原描述，避免丢失业务关键词。 */
+    descriptions?: Record<string, string>;
+}
+/** 图谱、CLI 检索和 AI 上下文复用同一套中文名称。graph.labels 的显示覆盖
+ * 与语义图分开，不被 impact 当成业务变化；配置短标题优先于声明的长描述。 */
+export declare function graphPresentation(cfg: CageConfig, registry: Registry): GraphPresentation;

package/dist/graph-presentation.js

@@ -0,0 +1,25 @@
+/** 图谱、CLI 检索和 AI 上下文复用同一套中文名称。graph.labels 的显示覆盖
+ * 与语义图分开，不被 impact 当成业务变化；配置短标题优先于声明的长描述。 */
+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 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":"AAUA;6CAC6C;AAC7C,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;QAAE,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IAClF,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,171 @@
+import type { GraphSnapshot } from './graph-snapshot.js';
+import { type ViewEdge, type ViewNode } from './graph-model.js';
+import { type GraphSearchHit } from './graph-search.js';
+export interface SourceReference {
+    file: string;
+    line?: number;
+    precision: 'declaration' | 'aggregate';
+}
+export interface GraphNodeInfo {
+    key: string;
+    id: string;
+    kind: ViewNode['kind'];
+    kindLabel: string;
+    label: string;
+    hash: string;
+    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;
+    status: 'ok' | 'ambiguous' | 'not-found';
+    candidates: GraphSearchHit[];
+}
+export declare const graphLimits: string[];
+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;
+};
+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[];
+};
+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[];
+};
+export interface GraphPathStep {
+    from: string;
+    to: string;
+    traversal: 'forward' | 'reverse';
+    relation: GraphRelationInfo;
+}
+/** 默认沿箭头找最短关系链；双向探索要显式选择 both，每一步保留原箭头。
+ * 归属虚线只用于整理对象，不能借它制造“任意两个命令都会互相调用”的短路。 */
+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[];
+};
+export declare const sourceText: (source: SourceReference | null) => string;
+export declare const evidenceLabels: {
+    declared: string;
+    inferred: string;
+    'text-match': string;
+};
+export declare function relationMarkdown(relation: GraphRelationInfo): string[];
+export declare function reportHeader(report: ReturnType<typeof graphReader>['meta'], title: string): string[];
+export declare function reportFooter(report: ReturnType<typeof graphReader>['meta']): string[];
+type QueryReport = ReturnType<typeof searchGraph> | ReturnType<typeof inspectGraph> | ReturnType<typeof findGraphPath>;
+export declare function formatGraphQuery(report: QueryReport): string;
+export {};

package/dist/graph-query.js

@@ -0,0 +1,242 @@
+// 本体查询只消费一次抽取快照。CLI 每次重新抽取；Web 使用页面显示的快照，
+// 报告明确记录时间与来源，不能把常驻页面里的旧图伪装成刚分析的代码。
+import { createHash } from 'node:crypto';
+import { kindLabels, nodeLabel, projectGraph } from './graph-model.js';
+import { explainEdge } from './graph-relations.js';
+import { searchGraphNodes } from './graph-search.js';
+export const graphLimits = [
+    '图描述业务声明及可抽取的依赖；条件分支、计算和 map 返回 null 等行为仍须阅读源码。',
+    '名称检索与测试匹配是候选线索；未覆盖全部前端依赖，也不证明业务正确性或测试已通过。',
+    'source.precision=aggregate 表示只定位到所属聚合声明；source=null 表示当前项目索引没有源码位置。',
+];
+export function graphReader(snapshot, freshness = 'fresh-extraction') {
+    const model = projectGraph(snapshot.graph);
+    const byKey = new Map(model.nodes.map((node) => [node.key, node]));
+    const labels = snapshot.presentation.labels;
+    const sourceOf = (node) => {
+        if (node.file)
+            return { file: node.file, line: node.line, precision: 'declaration' };
+        if (['field', 'state', 'capability', 'entry'].includes(node.kind)) {
+            const owner = byKey.get(`aggregate:${node.id.split('.')[0]}`);
+            if (owner?.file)
+                return { file: owner.file, line: owner.line, precision: 'aggregate' };
+        }
+        return null;
+    };
+    const nodeInfo = (node) => ({
+        key: node.key,
+        id: node.id,
+        kind: node.kind,
+        kindLabel: kindLabels[node.kind],
+        label: nodeLabel(node, labels),
+        hash: node.hash,
+        source: sourceOf(node),
+        attrs: node.attrs,
+    });
+    const relationInfo = (edge) => {
+        const explanation = explainEdge(edge, model, labels);
+        return {
+            ...edge,
+            label: explanation.label,
+            why: explanation.why,
+            purpose: explanation.purpose,
+            direction: explanation.direction,
+            evidence: {
+                basis: explanation.basis,
+                entries: explanation.evidence,
+                source: sourceOf(explanation.source),
+            },
+        };
+    };
+    const search = (query, kind) => searchGraphNodes(model, query, labels, { kind, descriptions: snapshot.presentation.descriptions });
+    const resolve = (selector) => {
+        const query = selector.normalize('NFKC').trim().toLowerCase();
+        // 先匹配带类型的完整身份，再匹配裸 ID / 中文全称。歧义时返回候选，不偷选第一项。
+        const keyed = model.nodes.filter((n) => n.key.normalize('NFKC').toLowerCase() === query);
+        const exact = keyed.length
+            ? keyed
+            : model.nodes.filter((n) => n.id.normalize('NFKC').toLowerCase() === query);
+        const named = exact.length
+            ? exact
+            : model.nodes.filter((n) => nodeLabel(n, labels).normalize('NFKC').toLowerCase() === query);
+        const hits = search(selector);
+        const candidates = named.length
+            ? named.map((n) => hits.find((hit) => hit.key === n.key))
+            : hits.slice(0, 8);
+        return {
+            selector,
+            status: named.length === 1 ? 'ok' : named.length > 1 ? 'ambiguous' : 'not-found',
+            candidates,
+        };
+    };
+    const meta = {
+        schemaVersion: 1,
+        project: snapshot.project,
+        domain: snapshot.domain,
+        extractedAt: snapshot.generatedAt,
+        freshness,
+        graphHash: createHash('sha256').update(JSON.stringify(snapshot.graph)).digest('hex').slice(0, 16),
+        findings: snapshot.findings,
+        limitations: graphLimits,
+    };
+    return { model, byKey, meta, sourceOf, nodeInfo, relationInfo, search, resolve };
+}
+export function searchGraph(snapshot, query, options = {}) {
+    const reader = graphReader(snapshot);
+    const hits = reader.search(query, options.kind);
+    const limit = options.limit ?? 10;
+    return {
+        ...reader.meta,
+        operation: 'search',
+        status: hits.length ? 'ok' : 'not-found',
+        query,
+        total: hits.length,
+        truncated: hits.length > limit,
+        hits: hits
+            .slice(0, limit)
+            .map((hit) => ({ ...hit, source: reader.sourceOf(reader.byKey.get(hit.key)) })),
+    };
+}
+export function inspectGraph(snapshot, selector) {
+    const reader = graphReader(snapshot);
+    const resolution = reader.resolve(selector);
+    const node = resolution.status === 'ok' ? reader.byKey.get(resolution.candidates[0].key) : undefined;
+    return {
+        ...reader.meta,
+        operation: 'inspect',
+        status: resolution.status,
+        resolution,
+        node: node ? reader.nodeInfo(node) : null,
+        relations: node
+            ? reader.model.edges
+                .filter((edge) => edge.from === node.key ||
+                edge.to === node.key ||
+                (edge.kind === 'transition' && edge.via === node.id && node.kind === 'command'))
+                .map(reader.relationInfo)
+            : [],
+    };
+}
+/** 默认沿箭头找最短关系链；双向探索要显式选择 both，每一步保留原箭头。
+ * 归属虚线只用于整理对象，不能借它制造“任意两个命令都会互相调用”的短路。 */
+export function findGraphPath(snapshot, from, to, options = {}) {
+    const reader = graphReader(snapshot);
+    const start = reader.resolve(from), end = reader.resolve(to);
+    const direction = options.direction ?? 'out', depth = options.depth ?? 6;
+    const base = { ...reader.meta, operation: 'path', from: start, to: end, direction, depth };
+    const nodes = [], steps = [];
+    if (start.status !== 'ok' || end.status !== 'ok')
+        return {
+            ...base,
+            status: start.status === 'ambiguous' || end.status === 'ambiguous'
+                ? 'ambiguous'
+                : 'not-found',
+            nodes,
+            steps,
+        };
+    const first = start.candidates[0].key, last = end.candidates[0].key;
+    const queue = [{ key: first, steps: [] }];
+    const visited = new Set([first]);
+    for (const current of queue) {
+        if (current.key === last) {
+            steps.push(...current.steps);
+            nodes.push(...[first, ...steps.map((s) => s.to)].map((key) => reader.nodeInfo(reader.byKey.get(key))));
+            return { ...base, status: 'ok', nodes, steps };
+        }
+        if (current.steps.length >= depth)
+            continue;
+        for (const edge of reader.model.edges) {
+            if (edge.derived)
+                continue;
+            const forward = edge.from === current.key;
+            const next = forward
+                ? edge.to
+                : direction === 'both' && edge.to === current.key
+                    ? edge.from
+                    : undefined;
+            if (!next || visited.has(next))
+                continue;
+            visited.add(next);
+            queue.push({
+                key: next,
+                steps: [
+                    ...current.steps,
+                    {
+                        from: current.key,
+                        to: next,
+                        traversal: forward ? 'forward' : 'reverse',
+                        relation: reader.relationInfo(edge),
+                    },
+                ],
+            });
+        }
+    }
+    return { ...base, status: 'not-found-within-depth', nodes, steps };
+}
+export const sourceText = (source) => source
+    ? `${source.file}${source.line ? `:${source.line}` : ''}${source.precision === 'aggregate' ? '（所属聚合）' : ''}`
+    : '当前工程无源码定位，查对应依赖的公开 API';
+export const evidenceLabels = { declared: '显式声明', inferred: '规则推导', 'text-match': '文本匹配线索' };
+export function relationMarkdown(relation) {
+    return [
+        `- ${relation.from} → ${relation.to}：${relation.label}${relation.via ? `；经 ${relation.via}` : ''}`,
+        `  - 原因：${relation.why}`,
+        `  - 用途：${relation.purpose}`,
+        `  - 依据：${evidenceLabels[relation.evidence.basis]}；${relation.evidence.entries.join('；')}`,
+        `  - 源码：${sourceText(relation.evidence.source)}`,
+    ];
+}
+export function reportHeader(report, title) {
+    return [
+        `# ${title}`,
+        '',
+        `项目：${report.project}；抽取时间：${report.extractedAt}；图指纹：${report.graphHash}`,
+        `来源：${report.freshness === 'fresh-extraction' ? '本次重新抽取' : '页面当前快照，修改代码后需重新抽取'}。`,
+        '',
+    ];
+}
+export function reportFooter(report) {
+    return [
+        '',
+        '## 当前规则问题',
+        '',
+        ...(report.findings.length
+            ? report.findings.map((f) => `- [${f.code}] ${f.at ?? ''} ${f.reason}；修复：${f.fix}`)
+            : ['当前抽取未发现规则问题；未执行测试。']),
+        '',
+        '## 使用边界',
+        '',
+        ...report.limitations.map((note) => `- ${note}`),
+    ];
+}
+export function formatGraphQuery(report) {
+    const lines = reportHeader(report, `Cage 本体${report.operation === 'search' ? '检索' : report.operation === 'inspect' ? '节点详情' : '关系路径'}`);
+    if (report.operation === 'search') {
+        lines.push(`关键词：${report.query}；命中 ${report.total} 项${report.truncated ? '，结果已截断，可提高 --limit 或缩小关键词' : ''}。`, '');
+        for (const hit of report.hits)
+            lines.push(`- **${hit.label}** \`${hit.key}\`（${kindLabels[hit.kind]}，得分 ${hit.score}）`, `  - 命中：${hit.matches.map((m) => `${m.field}=${m.value}（${m.terms.join('、')}）`).join('；')}`, `  - 源码：${sourceText(hit.source)}`);
+    }
+    else if (report.operation === 'inspect') {
+        if (report.node)
+            lines.push(`## ${report.node.label} · ${report.node.key}`, '', `源码：${sourceText(report.node.source)}`, '', '```json', JSON.stringify(report.node.attrs, null, 2), '```', '', '## 关联原因与用途', '', ...report.relations.flatMap(relationMarkdown));
+        else
+            lines.push(`节点定位：${report.status}；请从候选中复制完整 key 再执行 inspect。`, '', ...report.resolution.candidates.map((hit) => `- ${hit.label} \`${hit.key}\``));
+    }
+    else {
+        lines.push(`路径状态：${report.status}；方向：${report.direction}；深度上限：${report.depth}。`, '');
+        if (report.status === 'ok') {
+            lines.push(report.nodes.map((n) => `${n.label}（${n.key}）`).join(' → '), '');
+            for (const step of report.steps)
+                lines.push(`遍历：${step.from} → ${step.to}${step.traversal === 'reverse' ? '（逆向查看依赖，不表示执行方向）' : ''}`, ...relationMarkdown(step.relation), '');
+        }
+        else {
+            lines.push('未得到路径；未命中时缩小到完整 key，有歧义时从以下候选选择。已定位两端时可提高 --depth，或使用 --direction both 探索反向依赖。', '', ...[report.from, report.to].flatMap((r) => [
+                `${r.selector}：${r.status}`,
+                ...r.candidates.map((hit) => `- ${hit.label} \`${hit.key}\``),
+            ]));
+        }
+    }
+    if (report.status === 'not-found')
+        lines.push('', '未命中精确节点；检索基于已注册声明和名称，尝试更短的中文词或代码标识。');
+    return [...lines, ...reportFooter(report)].join('\n');
+}
+//# sourceMappingURL=graph-query.js.map