cgraphx 2.0.2 → 2.0.6

package/dist/core/code/engine/core/ingestion/workspace-config.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WORKSPACE_CONFIG_FILENAME = exports.WorkspaceConfigError = void 0;
+exports.loadWorkspaceConfig = loadWorkspaceConfig;
+exports.clearWorkspaceConfigCache = clearWorkspaceConfigCache;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+// js-yaml 5 为 CJS 包,在 ESM 顶层 default import 不可靠(基线 spring-config.ts 同模式)
+const yaml = require('js-yaml');
+/**
+ * workspace 配置解析/校验错误。
+ * 配置文件存在但解析失败或结构非法时抛出(spec §9:analyze 明确报错并中止)。
+ */
+class WorkspaceConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'WorkspaceConfigError';
+    }
+}
+exports.WorkspaceConfigError = WorkspaceConfigError;
+/** workspace 配置文件名(spec §5.2 契约,文件名逐字锁定,不读取任何历史别名)。 */
+exports.WORKSPACE_CONFIG_FILENAME = 'cgraphx-workspace.yaml';
+/**
+ * 进程级缓存:undefined = 未计算;null = 文件不存在(契约阶段跳过);
+ * WorkspaceConfig = 已解析的有效配置。解析失败时**不写缓存**(错误透传,语义不被缓存吞掉)。
+ */
+let cachedConfig;
+/**
+ * 加载 workspace 配置(spec §5.2 / §9)。
+ *
+ * 异常语义两分:
+ * - 配置文件**缺失** → 返回 null,契约阶段跳过,其余阶段正常;
+ * - 配置文件**存在但解析失败/结构非法**(YAML 语法错、缺 services/annotations.rpc 等必需项、
+ *   annotations.rpc 为数组等)→ 抛 {@link WorkspaceConfigError},analyze 明确报错并中止。
+ *
+ * 结果在进程内缓存(文件存在性 + 解析结果),避免重复读盘。
+ */
+function loadWorkspaceConfig(repoPath) {
+    if (cachedConfig !== undefined)
+        return cachedConfig;
+    const configPath = (0, node_path_1.join)(repoPath, exports.WORKSPACE_CONFIG_FILENAME);
+    if (!(0, node_fs_1.existsSync)(configPath)) {
+        cachedConfig = null;
+        return null;
+    }
+    // 文件存在 → 解析;任何解析/校验失败一律抛错,不产出半索引
+    let parsed;
+    try {
+        const raw = (0, node_fs_1.readFileSync)(configPath, 'utf-8');
+        parsed = yaml.load(raw);
+    }
+    catch (e) {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 解析失败(YAML 语法错误):${extractMessage(e)}。` +
+            `请检查 YAML 缩进/引号/冒号后空格等语法;修复后重新运行 \`cgraph analyze\`。`);
+    }
+    validateConfig(parsed);
+    const config = parsed;
+    cachedConfig = config;
+    return config;
+}
+/** 清除进程级缓存(测试用)。 */
+function clearWorkspaceConfigCache() {
+    cachedConfig = undefined;
+}
+/**
+ * 校验配置结构,非法时抛 {@link WorkspaceConfigError}(错误消息带字段路径与修复提示)。
+ * 校验顺序:根对象 → services → annotations → annotations.rpc(含数组演进预留)→ rpc 字段。
+ */
+function validateConfig(parsed) {
+    if (!isObject(parsed)) {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 根必须是一个映射对象(services/annotations 等字段),` +
+            `但当前解析为 ${typeof parsed}。请将文件内容改为顶层键值对结构,例如:\n` +
+            `  services:\n    - your-service/\n  annotations:\n    rpc: { ... }`);
+    }
+    const root = parsed;
+    // services 必需
+    if (!Array.isArray(root.services) || root.services.length === 0) {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 缺少必需字段 \`services\`(子工程相对目录清单)。` +
+            `请在根级声明非空数组,例如:\n  services:\n    - your-service/`);
+    }
+    for (const [i, s] of root.services.entries()) {
+        if (typeof s !== 'string' || s.length === 0) {
+            throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 的 services[${i}] 必须是非空字符串(子工程相对目录),` +
+                `但当前为 ${JSON.stringify(s)}。请改为形如 \`your-service/\` 的目录路径。`);
+        }
+    }
+    // annotations.rpc 必需
+    const annotations = root.annotations;
+    if (!isObject(annotations)) {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 缺少必需字段 \`annotations.rpc\`(RPC 注解定义)。` +
+            `请在根级声明 annotations.rpc,例如:\n  annotations:\n    rpc:\n      provider: "@YourProvider"\n      consumer: "@YourConsumer"\n      serviceIdArg: 0\n      matchBy: methodName`);
+    }
+    const rpc = annotations.rpc;
+    if (rpc === undefined || rpc === null) {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 缺少必需字段 \`annotations.rpc\`(RPC 注解定义)。` +
+            `请在 annotations 下声明 rpc 对象(provider/consumer/serviceIdArg/matchBy 四项)。`);
+    }
+    // 数组化演进预留:v1 仅支持单 RPC 框架配置,显式拒绝数组形态(不静默取第一个)
+    if (Array.isArray(rpc)) {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 的 annotations.rpc 为数组,但 v1 每个 workspace 仅支持` +
+            `单个 RPC 框架配置(spec §6.3)。请改为单个 rpc 对象(provider/consumer/serviceIdArg/matchBy)。` +
+            `多框架数组配置为未来演进方向,v1 暂不支持。`);
+    }
+    if (!isObject(rpc)) {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 的 annotations.rpc 必须是一个对象,但当前解析为 ${typeof rpc}。` +
+            `请改为键值对结构(provider/consumer/serviceIdArg/matchBy 四项)。`);
+    }
+    // rpc 必需字段(注解名等全部来自配置,无默认值)
+    const rpcObj = rpc;
+    if (typeof rpcObj.provider !== 'string' || rpcObj.provider.length === 0) {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 的 annotations.rpc.provider 必须是非空字符串(提供方注解名)。` +
+            `请填入你的 RPC 框架提供方注解,如 "@YourProvider"——注解名由配置给出,引擎不内置默认。`);
+    }
+    if (typeof rpcObj.consumer !== 'string' || rpcObj.consumer.length === 0) {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 的 annotations.rpc.consumer 必须是非空字符串(消费方注解名)。` +
+            `请填入你的 RPC 框架消费方注解,如 "@YourConsumer"——注解名由配置给出,引擎不内置默认。`);
+    }
+    if (typeof rpcObj.serviceIdArg !== 'number' ||
+        !Number.isInteger(rpcObj.serviceIdArg) ||
+        rpcObj.serviceIdArg < 0) {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 的 annotations.rpc.serviceIdArg 必须是非负整数` +
+            `(注解中 serviceId 的参数位置,0-based),但当前为 ${JSON.stringify(rpcObj.serviceIdArg)}。` +
+            `请改为形如 \`serviceIdArg: 0\` 的整数值。`);
+    }
+    if (rpcObj.matchBy !== 'methodName') {
+        throw new WorkspaceConfigError(`${exports.WORKSPACE_CONFIG_FILENAME} 的 annotations.rpc.matchBy 必须为 \`methodName\`(v1 唯一支持的匹配策略),` +
+            `但当前为 ${JSON.stringify(rpcObj.matchBy)}。请改为 \`matchBy: methodName\`。`);
+    }
+}
+/** 是否为普通对象(非 null、非数组)。 */
+function isObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** 从未知错误中提取消息文本。 */
+function extractMessage(e) {
+    if (e instanceof Error)
+        return e.message;
+    return String(e);
+}

package/dist/core/code/engine/core/lbug/conn-lock.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._resetConnLockForTests = exports.withConnLock = void 0;
+/**
+ * Serialize every operation on the shared singleton LadybugDB connection.
+ *
+ * LadybugDB is single-writer and its `Connection` is NOT safe for concurrent
+ * query execution: dispatching two queries on one connection at the same time
+ * lets two libuv workers mutate shared native engine state at once, corrupting
+ * the heap. This surfaced as `double free or corruption (out)` / SIGSEGV at the
+ * end of `analyze --pdg`, where the periodic WAL-checkpoint driver
+ * (`wal-checkpoint-driver.ts`) fired `CHECKPOINT` on the same connection a
+ * long-running PDG-table COPY was still using. `--pdg` makes those COPYs outlast
+ * the driver's 5 s tick, so the overlap (rare without `--pdg`) becomes reliable.
+ *
+ * Every singleton-`conn` helper in `lbug-adapter.ts` runs its full query +
+ * result-drain inside this lock, so the checkpoint driver, the bulk COPY, the
+ * embedding writeback, and the PDG edge deletes are mutually exclusive — the
+ * property that makes a strictly-serial workload stable.
+ *
+ * As of v0.18.0, none of LadybugDB's upstream fixes touch this specific risk
+ * (concurrent queries on ONE connection) — the closest are a deadlock fix
+ * between concurrent *connections* (LadybugDB/ladybug#605) and a narrow
+ * database close/destroy-vs-GC race fix (#623), both different scenarios
+ * from the one above. This lock's justification is unchanged.
+ *
+ * Implementation: a promise chain. Each caller installs a fresh unresolved tail,
+ * awaits the previous holder's tail, runs, then releases its own in `finally`
+ * (so a thrown op never wedges the connection). FIFO and non-reentrant: a wrapped
+ * helper MUST NOT call another wrapped helper — the inner call would await its own
+ * holder's tail and deadlock. The re-entry guard below catches this and throws
+ * instead of hanging. A boolean flag can't do this: a legitimately-queued
+ * top-level caller also runs while the lock is held, so only AsyncLocalStorage —
+ * which marks the *async context* of the running `fn` — distinguishes a true
+ * nested call from normal contention.
+ */
+const node_async_hooks_1 = require("node:async_hooks");
+let tail = Promise.resolve();
+// Set (to `true`) only inside a holding `fn`'s async context. A withConnLock call
+// that observes it set is a nested/re-entrant call from within a critical section.
+const inCriticalSection = new node_async_hooks_1.AsyncLocalStorage();
+const withConnLock = async (fn) => {
+    if (inCriticalSection.getStore()) {
+        throw new Error('conn-lock re-entry: a withConnLock-wrapped helper called another wrapped ' +
+            'helper, which would deadlock the single LadybugDB connection. Run the inner ' +
+            'work outside the lock, or inline it. See src/core/lbug/conn-lock.ts.');
+    }
+    const prior = tail;
+    let release;
+    tail = new Promise((resolve) => {
+        release = resolve;
+    });
+    await prior;
+    try {
+        return await inCriticalSection.run(true, fn);
+    }
+    finally {
+        release();
+    }
+};
+exports.withConnLock = withConnLock;
+/**
+ * Test-only: reset the lock chain to a fresh resolved tail. Production code has
+ * no reason to call this — a leaked-but-resolved tail is harmless — but unit
+ * tests want a clean chain per case.
+ *
+ * @internal
+ */
+const _resetConnLockForTests = () => {
+    tail = Promise.resolve();
+};
+exports._resetConnLockForTests = _resetConnLockForTests;