@yss123/cage-cli 0.1.0 → 0.2.0

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

package/dist/graph-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-query.js","sourceRoot":"","sources":["../src/graph-query.ts"],"names":[],"mappings":"AAAA,0CAA0C;AAC1C,oCAAoC;AACpC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAgC,MAAM,kBAAkB,CAAC;AACrG,OAAO,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAuB,MAAM,mBAAmB,CAAC;AAkC1E,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,gDAAgD;IAChD,2CAA2C;IAC3C,qEAAqE;CACtE,CAAC;AAEF,MAAM,UAAU,WAAW,CACzB,QAAuB,EACvB,YAAuD,kBAAkB;IAEzE,MAAM,KAAK,GAAG,YAAY,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;IACnE,MAAM,MAAM,GAAG,QAAQ,CAAC,YAAY,CAAC,MAAM,CAAC;IAC5C,MAAM,QAAQ,GAAG,CAAC,IAAc,EAA0B,EAAE;QAC1D,IAAI,IAAI,CAAC,IAAI;YAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;QACrF,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;YAClE,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,aAAa,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;YAC9D,IAAI,KAAK,EAAE,IAAI;gBAAE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;QACzF,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;IACF,MAAM,QAAQ,GAAG,CAAC,IAAc,EAAiB,EAAE,CAAC,CAAC;QACnD,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,EAAE,EAAE,IAAI,CAAC,EAAE;QACX,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;QAChC,KAAK,EAAE,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC;QAC9B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,MAAM,EAAE,QAAQ,CAAC,IAAI,CAAC;QACtB,KAAK,EAAE,IAAI,CAAC,KAAK;KAClB,CAAC,CAAC;IACH,MAAM,YAAY,GAAG,CAAC,IAAc,EAAqB,EAAE;QACzD,MAAM,WAAW,GAAG,WAAW,CAAC,IAAI,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC;QACrD,OAAO;YACL,GAAG,IAAI;YACP,KAAK,EAAE,WAAW,CAAC,KAAK;YACxB,GAAG,EAAE,WAAW,CAAC,GAAG;YACpB,OAAO,EAAE,WAAW,CAAC,OAAO;YAC5B,SAAS,EAAE,WAAW,CAAC,SAAS;YAChC,QAAQ,EAAE;gBACR,KAAK,EAAE,WAAW,CAAC,KAAK;gBACxB,OAAO,EAAE,WAAW,CAAC,QAAQ;gBAC7B,MAAM,EAAE,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC;aACrC;SACF,CAAC;IACJ,CAAC,CAAC;IACF,MAAM,MAAM,GAAG,CAAC,KAAa,EAAE,IAAuB,EAAE,EAAE,CACxD,gBAAgB,CAAC,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAC,YAAY,EAAE,CAAC,CAAC;IACrG,MAAM,OAAO,GAAG,CAAC,QAAgB,EAAkB,EAAE;QACnD,MAAM,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC9D,6CAA6C;QAC7C,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,CAAC;QACzF,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM;YACxB,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,CAAC;QAC9E,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM;YACxB,CAAC,CAAC,KAAK;YACP,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,CAAC;QAC9F,MAAM,IAAI,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC9B,MAAM,UAAU,GAAG,KAAK,CAAC,MAAM;YAC7B,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,GAAG,CAAE,CAAC;YAC1D,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO;YACL,QAAQ;YACR,MAAM,EAAE,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,WAAW;YAChF,UAAU;SACX,CAAC;IACJ,CAAC,CAAC;IACF,MAAM,IAAI,GAAG;QACX,aAAa,EAAE,CAAU;QACzB,OAAO,EAAE,QAAQ,CAAC,OAAO;QACzB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,WAAW,EAAE,QAAQ,CAAC,WAAW;QACjC,SAAS;QACT,SAAS,EAAE,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC;QACjG,QAAQ,EAAE,QAAQ,CAAC,QAAQ;QAC3B,WAAW,EAAE,WAAW;KACzB,CAAC;IACF,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC;AACnF,CAAC;AAED,MAAM,UAAU,WAAW,CACzB,QAAuB,EACvB,KAAa,EACb,UAAuD,EAAE;IAEzD,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC;IAClC,OAAO;QACL,GAAG,MAAM,CAAC,IAAI;QACd,SAAS,EAAE,QAAiB;QAC5B,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAE,IAAc,CAAC,CAAC,CAAE,WAAqB;QAC9D,KAAK;QACL,KAAK,EAAE,IAAI,CAAC,MAAM;QAClB,SAAS,EAAE,IAAI,CAAC,MAAM,GAAG,KAAK;QAC9B,IAAI,EAAE,IAAI;aACP,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;aACf,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,EAAE,CAAC,CAAC;KACnF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,QAAuB,EAAE,QAAgB;IACpE,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,KAAK,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACtG,OAAO;QACL,GAAG,MAAM,CAAC,IAAI;QACd,SAAS,EAAE,SAAkB;QAC7B,MAAM,EAAE,UAAU,CAAC,MAAM;QACzB,UAAU;QACV,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI;QACzC,SAAS,EAAE,IAAI;YACb,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK;iBACf,MAAM,CACL,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,GAAG;gBACtB,IAAI,CAAC,EAAE,KAAK,IAAI,CAAC,GAAG;gBACpB,CAAC,IAAI,CAAC,IAAI,KAAK,YAAY,IAAI,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS,CAAC,CAClF;iBACA,GAAG,CAAC,MAAM,CAAC,YAAY,CAAC;YAC7B,CAAC,CAAC,EAAE;KACP,CAAC;AACJ,CAAC;AASD;0CAC0C;AAC1C,MAAM,UAAU,aAAa,CAC3B,QAAuB,EACvB,IAAY,EACZ,EAAU,EACV,UAA0D,EAAE;IAE5D,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAChC,GAAG,GAAG,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC3B,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,KAAK,EAC1C,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,MAAe,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpG,MAAM,KAAK,GAAoB,EAAE,EAC/B,KAAK,GAAoB,EAAE,CAAC;IAC9B,IAAI,KAAK,CAAC,MAAM,KAAK,IAAI,IAAI,GAAG,CAAC,MAAM,KAAK,IAAI;QAC9C,OAAO;YACL,GAAG,IAAI;YACP,MAAM,EACJ,KAAK,CAAC,MAAM,KAAK,WAAW,IAAI,GAAG,CAAC,MAAM,KAAK,WAAW;gBACxD,CAAC,CAAE,WAAqB;gBACxB,CAAC,CAAE,WAAqB;YAC5B,KAAK;YACL,KAAK;SACN,CAAC;IACJ,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,EACnC,IAAI,GAAG,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC/B,MAAM,KAAK,GAAG,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,EAAqB,EAAE,CAAC,CAAC;IAC7D,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IACjC,KAAK,MAAM,OAAO,IAAI,KAAK,EAAE,CAAC;QAC5B,IAAI,OAAO,CAAC,GAAG,KAAK,IAAI,EAAE,CAAC;YACzB,KAAK,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC,CAAC,CAAC,CAAC;YACxG,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAa,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;QAC1D,CAAC;QACD,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK;YAAE,SAAS;QAC5C,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,IAAI,CAAC,OAAO;gBAAE,SAAS;YAC3B,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,KAAK,OAAO,CAAC,GAAG,CAAC;YAC1C,MAAM,IAAI,GAAG,OAAO;gBAClB,CAAC,CAAC,IAAI,CAAC,EAAE;gBACT,CAAC,CAAC,SAAS,KAAK,MAAM,IAAI,IAAI,CAAC,EAAE,KAAK,OAAO,CAAC,GAAG;oBAC/C,CAAC,CAAC,IAAI,CAAC,IAAI;oBACX,CAAC,CAAC,SAAS,CAAC;YAChB,IAAI,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,SAAS;YACzC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC;gBACT,GAAG,EAAE,IAAI;gBACT,KAAK,EAAE;oBACL,GAAG,OAAO,CAAC,KAAK;oBAChB;wBACE,IAAI,EAAE,OAAO,CAAC,GAAG;wBACjB,EAAE,EAAE,IAAI;wBACR,SAAS,EAAE,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS;wBAC1C,QAAQ,EAAE,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC;qBACpC;iBACF;aACF,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IACD,OAAO,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,wBAAiC,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;AAC9E,CAAC;AAED,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAA8B,EAAE,EAAE,CAC3D,MAAM;IACJ,CAAC,CAAC,GAAG,MAAM,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,SAAS,KAAK,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,EAAE;IAC5G,CAAC,CAAC,wBAAwB,CAAC;AAC/B,MAAM,CAAC,MAAM,cAAc,GAAG,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,QAAQ,EAAE,CAAC;AAE7F,MAAM,UAAU,gBAAgB,CAAC,QAA2B;IAC1D,OAAO;QACL,KAAK,QAAQ,CAAC,IAAI,MAAM,QAAQ,CAAC,EAAE,IAAI,QAAQ,CAAC,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE;QAClG,UAAU,QAAQ,CAAC,GAAG,EAAE;QACxB,UAAU,QAAQ,CAAC,OAAO,EAAE;QAC5B,UAAU,cAAc,CAAC,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE;QAC1F,UAAU,UAAU,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE;KACjD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAA8C,EAAE,KAAa;IACxF,OAAO;QACL,KAAK,KAAK,EAAE;QACZ,EAAE;QACF,MAAM,MAAM,CAAC,OAAO,SAAS,MAAM,CAAC,WAAW,QAAQ,MAAM,CAAC,SAAS,EAAE;QACzE,MAAM,MAAM,CAAC,SAAS,KAAK,kBAAkB,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,mBAAmB,GAAG;QACjF,EAAE;KACH,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAA8C;IACzE,OAAO;QACL,EAAE;QACF,WAAW;QACX,EAAE;QACF,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM;YACxB,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,GAAG,EAAE,CAAC;YACnF,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC;QAC3B,EAAE;QACF,SAAS;QACT,EAAE;QACF,GAAG,MAAM,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;KACjD,CAAC;AACJ,CAAC;AAKD,MAAM,UAAU,gBAAgB,CAAC,MAAmB;IAClD,MAAM,KAAK,GAAG,YAAY,CACxB,MAAM,EACN,UAAU,MAAM,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,EAAE,CACpG,CAAC;IACF,IAAI,MAAM,CAAC,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,KAAK,CAAC,IAAI,CACR,OAAO,MAAM,CAAC,KAAK,OAAO,MAAM,CAAC,KAAK,KAAK,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,EAAE,GAAG,EACjG,EAAE,CACH,CAAC;QACF,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI;YAC3B,KAAK,CAAC,IAAI,CACR,OAAO,GAAG,CAAC,KAAK,QAAQ,GAAG,CAAC,GAAG,MAAM,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,OAAO,GAAG,CAAC,KAAK,GAAG,EAC5E,UAAU,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,EAC3F,UAAU,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CACnC,CAAC;IACN,CAAC;SAAM,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,EAAE,CAAC;QAC1C,IAAI,MAAM,CAAC,IAAI;YACb,KAAK,CAAC,IAAI,CACR,MAAM,MAAM,CAAC,IAAI,CAAC,KAAK,MAAM,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,EAC9C,EAAE,EACF,MAAM,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EACtC,EAAE,EACF,SAAS,EACT,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAC1C,KAAK,EACL,EAAE,EACF,YAAY,EACZ,EAAE,EACF,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,gBAAgB,CAAC,CAC9C,CAAC;;YAEF,KAAK,CAAC,IAAI,CACR,QAAQ,MAAM,CAAC,MAAM,6BAA6B,EAClD,EAAE,EACF,GAAG,MAAM,CAAC,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,KAAK,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC,CAC9E,CAAC;IACN,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,QAAQ,MAAM,CAAC,MAAM,OAAO,MAAM,CAAC,SAAS,SAAS,MAAM,CAAC,KAAK,GAAG,EAAE,EAAE,CAAC,CAAC;QACrF,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI,EAAE,CAAC;YAC3B,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC,CAAC;YAC5E,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,KAAK;gBAC7B,KAAK,CAAC,IAAI,CACR,MAAM,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,EAAE,EAAE,EACvF,GAAG,gBAAgB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAClC,EAAE,CACH,CAAC;QACN,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CACR,gFAAgF,EAChF,EAAE,EACF,GAAG,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC;gBACzC,GAAG,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,MAAM,EAAE;gBAC3B,GAAG,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,KAAK,MAAM,GAAG,CAAC,GAAG,IAAI,CAAC;aAC9D,CAAC,CACH,CAAC;QACJ,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,MAAM,KAAK,WAAW;QAC/B,KAAK,CAAC,IAAI,CAAC,EAAE,EAAE,qCAAqC,CAAC,CAAC;IACxD,OAAO,CAAC,GAAG,KAAK,EAAE,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACxD,CAAC"}

package/dist/graph-relations.d.ts

@@ -0,0 +1,14 @@
+import { type GraphModel, type ViewEdge, type ViewNode } from './graph-model.js';
+/** 解释来自已抽取的声明，不借连线猜测运行结果。尤其要区分“允许读取”、
+ * “声明依赖”和“事件触发”，否则图谱很容易被误读为一张执行时序图。 */
+export interface RelationExplanation {
+    label: string;
+    category: string;
+    why: string;
+    purpose: string;
+    direction: string;
+    evidence: string[];
+    source: ViewNode;
+    basis: 'declared' | 'inferred' | 'text-match';
+}
+export declare function explainEdge(edge: ViewEdge, model: GraphModel, labels?: Record<string, string>): RelationExplanation;