cgraphx 2.0.2 → 2.0.3

package/dist/core/code/engine/lib/utils.js

@@ -0,0 +1,121 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripWindowsLongPathPrefix = exports.CAUSE_CHAIN_MAX_DEPTH = exports.compareCodeUnits = exports.generateId = void 0;
+exports.causeChain = causeChain;
+exports.findInCauseChain = findInCauseChain;
+const generateId = (label, name) => {
+    return `${label}:${name}`;
+};
+exports.generateId = generateId;
+/**
+ * Total order on strings by UTF-16 code unit — deliberately NOT `localeCompare`.
+ *
+ * `localeCompare` resolves against the host's default ICU locale, so two machines
+ * can order the same pair differently and a tie-broken cap keeps a different
+ * subset on each (#2787). Code-unit order is host-independent and matches the
+ * binary `ORDER BY` the graph queries use, so a JS re-sort reproduces the DB's
+ * order instead of fighting it.
+ *
+ * Use this for every tiebreak that feeds a `.slice()`, a page boundary, or any
+ * other cut — `Array.prototype.sort` is stable, so a comparator that returns 0
+ * for distinct elements silently falls back to input order.
+ */
+const compareCodeUnits = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+exports.compareCodeUnits = compareCodeUnits;
+/**
+ * How many links of an `Error.cause` chain any walker below visits, counting
+ * the head. THE bound — hand-rolled copies had drifted to three different
+ * numbers with three different loop conditions (`depth < 5` in two places,
+ * `depth <= 5` in a third, i.e. six levels).
+ *
+ * The bound exists purely so a cyclic chain (`a.cause = b; b.cause = a`)
+ * cannot loop forever. Real chains are one or two links deep — the ingestion
+ * phase runner wraps a phase failure once as
+ * `new Error("Phase 'X' failed: …", { cause })` — so five leaves ample
+ * headroom for future nesting.
+ */
+exports.CAUSE_CHAIN_MAX_DEPTH = 5;
+/**
+ * Walk `err` and its `cause` chain, head first, yielding each `Error` link.
+ *
+ * Stops at the first non-`Error` link (a `cause` may legally be any value, and
+ * a non-Error carries no further `cause` worth following) and after
+ * `maxDepth` links. Non-`Error` input yields nothing.
+ *
+ * THE single cause-chain traversal. Consume this (or {@link findInCauseChain})
+ * rather than re-rolling the `for (let depth = 0; …; current = current.cause)`
+ * loop: every hand-rolled copy has to re-decide the bound and the loop
+ * condition, and they did not agree.
+ */
+function* causeChain(err, maxDepth = exports.CAUSE_CHAIN_MAX_DEPTH) {
+    let current = err;
+    for (let depth = 0; depth < maxDepth && current instanceof Error; depth++) {
+        yield current;
+        current = current.cause;
+    }
+}
+/**
+ * Find the first link of `err`'s cause chain that `match` accepts.
+ *
+ * Load-bearing for CLI error classification: the ingestion phase runner
+ * rewraps every phase failure as `new Error("Phase 'X' failed: …", { cause })`,
+ * so a bare `instanceof` at the CLI boundary misses the real error entirely
+ * and falls through to a generic stack dump. Classify by TYPE through this
+ * helper (the repo norm from #2385), never by message text.
+ */
+function findInCauseChain(err, match, maxDepth = exports.CAUSE_CHAIN_MAX_DEPTH) {
+    for (const link of causeChain(err, maxDepth)) {
+        if (match(link))
+            return link;
+    }
+    return undefined;
+}
+/**
+ * Drop a Windows extended-length (`\\?\`) prefix from a path (#2667).
+ *
+ * **Comparison domain only.** Never apply this to a string that is about to be
+ * handed to `fs`: libuv's `fs__capture_path` only converts WTF-8 to UTF-16 and
+ * does *not* re-add the prefix for over-MAX_PATH paths, so stripping an
+ * filesystem-facing path would break long-path access on hosts that have not
+ * opted into `LongPathsEnabled`. Registry keys, repo-resolution lookups and
+ * other pure string comparisons are safe — and are exactly where an
+ * un-normalized prefix silently fails to match.
+ *
+ * The prefix can only ever arrive from caller-supplied input (`path.resolve`
+ * preserves it); `realpathSync.native` cannot emit it, because libuv's
+ * `fs__realpath_handle` strips it unconditionally.
+ *
+ * `\\?\Volume{GUID}\…` is deliberately left alone: the remainder of a volume-GUID
+ * path is not a usable path, so stripping it would invent a wrong one. The `\\.\`
+ * device namespace is left alone for the same reason and one more — most of what
+ * it addresses (`\\.\PhysicalDrive0`, `\\.\COM1`, `\\.\pipe\…`) is not a
+ * filesystem path at all. Both forms simply fail to match a registry entry, which
+ * is the safe direction. `platform` is explicit so the transform is unit-testable
+ * off Windows — same shape as `normalizeAnalyzerRootPath` in
+ * `src/core/analyzer-identity.ts`.
+ *
+ * Call this on a `path.resolve`d path. Only the backslash spelling is matched,
+ * which is sufficient there because `path.win32.resolve` already folds the
+ * forward-slash spelling into it (`//?/D:/a` → `\\?\D:\a`). A raw, unresolved
+ * `//?/…` string is returned unchanged rather than half-normalized.
+ */
+const stripWindowsLongPathPrefix = (p, platform = process.platform) => {
+    if (platform !== 'win32')
+        return p;
+    // Both spellings are case-insensitive: the Windows object namespace that
+    // `\\?\` addresses is, so `\\?\unc\…` is as valid as `\\?\UNC\…`.
+    //
+    // Each pattern requires the component that makes the remainder a usable path —
+    // a share name after `UNC\`, a separator after the drive colon. Without those
+    // the slice would emit something worse than the input it was handed: `\\?\UNC`
+    // would become the bare root `\\`, and the drive-relative `\\?\D:foo` would
+    // become `D:foo`, which is not absolute and would resolve against the process
+    // cwd if a future caller ever passed it to `fs`. A malformed extended path is
+    // left untouched instead, so it simply fails to match a registry entry.
+    if (/^\\\\\?\\UNC\\(?=[^\\])/i.test(p))
+        return `\\\\${p.slice(8)}`;
+    if (/^\\\\\?\\[A-Za-z]:\\/.test(p))
+        return p.slice(4);
+    return p;
+};
+exports.stripWindowsLongPathPrefix = stripWindowsLongPathPrefix;

package/dist/core/code/engine/mcp/core/lbug-adapter.js

@@ -0,0 +1,27 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * LadybugDB connection pool — re-exported from core.
+ *
+ * KEEP THIS FILE. It is intentionally a shim re-export of
+ * `../../core/lbug/pool-adapter.js`. The MCP test suite uses this path as
+ * a vi.mock seam so unit tests can stub LadybugDB without affecting other
+ * importers of `core/lbug/pool-adapter.js` (which is shared with the
+ * analyze pipeline). New non-test code MAY import from `pool-adapter.js`
+ * directly, but the shim must continue to exist for the mock seam to work.
+ */
+__exportStar(require("../../core/lbug/pool-adapter.js"), exports);

package/dist/core/code/engine/mcp/local/aop-metadata.js

@@ -0,0 +1,230 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.querySpringAopMetadata = querySpringAopMetadata;
+const pool_adapter_js_1 = require("../../core/lbug/pool-adapter.js");
+const aop_js_1 = require("../../core/ingestion/frameworks/spring/aop.js");
+const SUPPORTED_SYMBOL_TYPES = new Set(['Class', 'Interface', 'Method', 'CodeElement']);
+const QUERY_RESULT_LIMIT = 1_000;
+const QUERY_FETCH_LIMIT = QUERY_RESULT_LIMIT + 1;
+function readRowValue(row, name, index) {
+    if (typeof row === 'object' && row !== null && name in row) {
+        return row[name];
+    }
+    return Array.isArray(row) ? row[index] : undefined;
+}
+function readRequiredString(row, name, index) {
+    const value = readRowValue(row, name, index);
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function readOptionalString(row, name, index) {
+    const value = readRowValue(row, name, index);
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function normalizeRelationshipRow(row) {
+    const sourceId = readRequiredString(row, 'sourceId', 0);
+    const targetId = readRequiredString(row, 'targetId', 3);
+    if (sourceId === undefined || targetId === undefined)
+        return undefined;
+    const sourceName = readOptionalString(row, 'sourceName', 1);
+    const sourceFilePath = readOptionalString(row, 'sourceFilePath', 2);
+    const targetName = readOptionalString(row, 'targetName', 4);
+    const targetFilePath = readOptionalString(row, 'targetFilePath', 5);
+    return {
+        sourceId,
+        ...optionalField('sourceName', sourceName),
+        ...optionalField('sourceFilePath', sourceFilePath),
+        targetId,
+        ...optionalField('targetName', targetName),
+        ...optionalField('targetFilePath', targetFilePath),
+        reason: readRowValue(row, 'reason', 6),
+    };
+}
+function optionalField(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+function stableDedupe(values, keyOf) {
+    const unique = new Map();
+    for (const value of values)
+        unique.set(keyOf(value), value);
+    return [...unique.entries()]
+        .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+        .map(([, value]) => value);
+}
+const RELATIONSHIP_PROJECTION = `
+  RETURN source.id AS sourceId, source.name AS sourceName, source.filePath AS sourceFilePath,
+         target.id AS targetId, target.name AS targetName, target.filePath AS targetFilePath,
+         r.reason AS reason, r.step AS step
+`;
+const DETERMINISTIC_RELATIONSHIP_ORDER = 'ORDER BY sourceId, targetId, reason, step';
+/**
+ * Read additive Spring proxy/advice metadata for context and impact results.
+ *
+ * The helper intentionally trusts only versioned reasons accepted by the
+ * shared decoder. Other DECLARES edges (for example Spring Bean factories)
+ * and malformed/forward-version evidence are ignored. Query failures are
+ * fail-soft because older or partially upgraded indexes must remain readable.
+ */
+async function querySpringAopMetadata(lbugPath, symbolId, symbolType) {
+    if (!SUPPORTED_SYMBOL_TYPES.has(symbolType))
+        return undefined;
+    try {
+        const [outgoingAdviceRows, incomingAdviceRows, outgoingPointcutRows, incomingPointcutRows] = await Promise.all([
+            (0, pool_adapter_js_1.executeParameterized)(lbugPath, `MATCH (source {id: $symbolId})-[r:CodeRelation]->(target)
+           WHERE r.type = 'ADVISED_BY'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+            (0, pool_adapter_js_1.executeParameterized)(lbugPath, `MATCH (source)-[r:CodeRelation]->(target {id: $symbolId})
+           WHERE r.type = 'ADVISED_BY'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+            (0, pool_adapter_js_1.executeParameterized)(lbugPath, `MATCH (source {id: $symbolId})-[r:CodeRelation]->(target:CodeElement)
+           WHERE r.type = 'DECLARES'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+            (0, pool_adapter_js_1.executeParameterized)(lbugPath, `MATCH (source)-[r:CodeRelation]->(target:CodeElement {id: $symbolId})
+           WHERE r.type = 'DECLARES'
+             AND r.reason STARTS WITH 'spring-aop:v1:'
+           ${RELATIONSHIP_PROJECTION}
+           ${DETERMINISTIC_RELATIONSHIP_ORDER}
+           LIMIT 1001`, { symbolId }),
+        ]);
+        const behaviors = [];
+        const advices = [];
+        const resolvedPointcuts = [];
+        const unresolvedPointcuts = [];
+        const aspects = [];
+        const truncated = [
+            outgoingAdviceRows,
+            incomingAdviceRows,
+            outgoingPointcutRows,
+            incomingPointcutRows,
+        ].some((rows) => rows.length >= QUERY_FETCH_LIMIT);
+        let queriedSymbolIsAdvisedSource = false;
+        for (const [rows, isOutgoing] of [
+            [outgoingAdviceRows, true],
+            [incomingAdviceRows, false],
+        ]) {
+            for (const rawRow of rows.slice(0, QUERY_RESULT_LIMIT)) {
+                const row = normalizeRelationshipRow(rawRow);
+                if (row === undefined)
+                    continue;
+                const reason = (0, aop_js_1.decodeSpringAopReason)(row.reason);
+                if (reason?.kind === 'behavior') {
+                    if (isOutgoing)
+                        queriedSymbolIsAdvisedSource = true;
+                    behaviors.push({
+                        annotation: reason.annotation,
+                        behavior: reason.behavior,
+                        declaredOn: reason.declaredOn,
+                        activation: reason.activation,
+                        evidenceId: row.targetId,
+                    });
+                }
+                else if (reason?.kind === 'advice') {
+                    if (isOutgoing)
+                        queriedSymbolIsAdvisedSource = true;
+                    advices.push({
+                        annotation: reason.annotation,
+                        advice: reason.advice,
+                        pointcut: reason.pointcut,
+                        match: reason.match,
+                        activation: reason.activation,
+                        adviceId: row.targetId,
+                        ...optionalField('adviceName', row.targetName),
+                        ...optionalField('adviceFilePath', row.targetFilePath),
+                        advisedId: row.sourceId,
+                        ...optionalField('advisedName', row.sourceName),
+                        ...optionalField('advisedFilePath', row.sourceFilePath),
+                    });
+                }
+            }
+        }
+        for (const rows of [outgoingPointcutRows, incomingPointcutRows]) {
+            for (const rawRow of rows.slice(0, QUERY_RESULT_LIMIT)) {
+                const row = normalizeRelationshipRow(rawRow);
+                if (row === undefined)
+                    continue;
+                const reason = (0, aop_js_1.decodeSpringAopReason)(row.reason);
+                if (reason?.kind === 'aspect') {
+                    aspects.push({
+                        annotation: reason.annotation,
+                        activation: reason.activation,
+                        registration: reason.registration,
+                        evidenceId: row.targetId,
+                    });
+                }
+                else if (reason?.kind === 'pointcut' &&
+                    reason.match === 'static' &&
+                    reason.resolution === 'resolved' &&
+                    typeof reason.pointcut === 'string') {
+                    resolvedPointcuts.push({
+                        annotation: reason.annotation,
+                        pointcut: reason.pointcut,
+                        match: reason.match,
+                        resolution: reason.resolution,
+                        adviceId: row.sourceId,
+                        ...optionalField('adviceName', row.sourceName),
+                        ...optionalField('adviceFilePath', row.sourceFilePath),
+                        evidenceId: row.targetId,
+                    });
+                }
+                else if (reason?.kind === 'pointcut' && reason.match === 'unresolved') {
+                    unresolvedPointcuts.push({
+                        annotation: reason.annotation,
+                        pointcut: reason.pointcut,
+                        adviceId: row.sourceId,
+                        ...optionalField('adviceName', row.sourceName),
+                        ...optionalField('adviceFilePath', row.sourceFilePath),
+                        evidenceId: row.targetId,
+                    });
+                }
+            }
+        }
+        const dedupedAspects = stableDedupe(aspects, (aspect) => JSON.stringify([aspect.annotation, aspect.evidenceId]));
+        const dedupedBehaviors = stableDedupe(behaviors, (behavior) => JSON.stringify([
+            behavior.behavior,
+            behavior.annotation,
+            behavior.declaredOn,
+            behavior.evidenceId,
+        ]));
+        const dedupedAdvices = stableDedupe(advices, (advice) => JSON.stringify([advice.advisedId, advice.adviceId, advice.advice, advice.pointcut]));
+        const dedupedPointcuts = stableDedupe(unresolvedPointcuts, (pointcut) => JSON.stringify([
+            pointcut.adviceId,
+            pointcut.evidenceId,
+            pointcut.annotation,
+            pointcut.pointcut,
+        ]));
+        const dedupedResolvedPointcuts = stableDedupe(resolvedPointcuts, (pointcut) => JSON.stringify([
+            pointcut.adviceId,
+            pointcut.evidenceId,
+            pointcut.annotation,
+            pointcut.pointcut,
+        ]));
+        if (dedupedAspects.length === 0 &&
+            dedupedBehaviors.length === 0 &&
+            dedupedAdvices.length === 0 &&
+            dedupedResolvedPointcuts.length === 0 &&
+            dedupedPointcuts.length === 0) {
+            return undefined;
+        }
+        return {
+            framework: 'spring',
+            ...(queriedSymbolIsAdvisedSource ? { proxied: 'possible' } : {}),
+            ...(truncated ? { truncated: true } : {}),
+            ...(dedupedAspects[0] === undefined ? {} : { aspect: dedupedAspects[0] }),
+            behaviors: dedupedBehaviors,
+            advices: dedupedAdvices,
+            resolvedPointcuts: dedupedResolvedPointcuts,
+            unresolvedPointcuts: dedupedPointcuts,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/core/code/engine/mcp/local/bean-metadata.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.queryClassBeanMetadata = queryClassBeanMetadata;
+const pool_adapter_js_1 = require("../../core/lbug/pool-adapter.js");
+const bean_catalog_js_1 = require("../../core/ingestion/frameworks/spring/bean-catalog.js");
+const bean_factories_js_1 = require("../../core/ingestion/frameworks/spring/bean-factories.js");
+async function queryClassBeanMetadata(lbugPath, symbolId, symbolType) {
+    if (symbolType !== 'Class' && symbolType !== 'Method' && symbolType !== 'CodeElement') {
+        return undefined;
+    }
+    try {
+        if (symbolType !== 'Class') {
+            const pattern = symbolType === 'Method'
+                ? 'MATCH (m:Method {id: $symbolId})-[r:CodeRelation]->(b:CodeElement)'
+                : 'MATCH (m:Method)-[r:CodeRelation]->(b:CodeElement {id: $symbolId})';
+            // determinism: probe — PK-anchored singleton. A @Bean factory's declaration
+            // node id is derived from the declaring method's id
+            // (`CodeElement:spring-bean:<methodId>`, see bean-factories.ts), so exactly
+            // one DECLARES edge with this reason prefix exists per anchored endpoint,
+            // whichever end `$symbolId` pins.
+            const rows = await (0, pool_adapter_js_1.executeParameterized)(lbugPath, `${pattern}
+         WHERE r.type = 'DECLARES'
+           AND r.reason STARTS WITH 'spring-bean-factory:'
+         RETURN r.reason AS reason
+         LIMIT 1`, { symbolId });
+            const row = rows[0];
+            return row === undefined ? undefined : (0, bean_factories_js_1.decodeSpringBeanFactoryReason)(row.reason ?? row[0]);
+        }
+        // determinism: probe — PK-anchored singleton. `$symbolId` is a node primary
+        // key, so at most one Class row can match and the LIMIT never chooses.
+        const rows = await (0, pool_adapter_js_1.executeParameterized)(lbugPath, `
+      MATCH (c:Class {id: $symbolId})
+      RETURN c.frameworkAnnotations AS frameworkAnnotations
+      LIMIT 1
+    `, { symbolId });
+        const row = rows[0];
+        if (!row)
+            return undefined;
+        const value = row.frameworkAnnotations ?? row[0];
+        if (!Array.isArray(value))
+            return undefined;
+        return (0, bean_catalog_js_1.deriveSpringBeanMetadata)(value.filter((annotation) => typeof annotation === 'string'));
+    }
+    catch {
+        // Older or partially upgraded indexes may not have the column. This
+        // enrichment is additive, so context and impact must still succeed.
+        return undefined;
+    }
+}

package/dist/core/code/engine/mcp/local/limits.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * PDG 遍历能力共享限额。
+ *
+ * 原 MCP tool 注册层（tools.ts）裁剪后，这些分页/深度上限由 local 侧持有：
+ * `pdg-impact.ts` 的分页钳制与遍历深度校验从这里取值，保持单一事实来源
+ * （数值与原 tools.ts 完全一致）。
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IMPACT_MAX_DEPTH = exports.PDG_QUERY_MAX_LIMIT = exports.PDG_QUERY_DEFAULT_LIMIT = void 0;
+// PDG 结果分页上限（#2086 M6）——pdg-impact.ts 的锚定 + LIMIT 约束取值于此。
+exports.PDG_QUERY_DEFAULT_LIMIT = 50;
+exports.PDG_QUERY_MAX_LIMIT = 200;
+// impact 遍历深度共享上限。PDG 直连 backend 调用方在遍历前也会强制该校验。
+exports.IMPACT_MAX_DEPTH = 32;

package/dist/core/code/engine/mcp/local/line-display.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toDisplayLine = toDisplayLine;
+function toDisplayLine(zeroBasedLine) {
+    return typeof zeroBasedLine === 'number' ? zeroBasedLine + 1 : undefined;
+}