cgraphx 2.0.2 → 2.0.6

package/dist/core/code/engine/cli/analyze-config.js

@@ -0,0 +1,320 @@
+"use strict";
+/**
+ * Project-local `.cgraphrc` support for `cgraph analyze` (#243).
+ *
+ * Lets a repository commit recurring `analyze` defaults — embedding knobs,
+ * worker tuning, registry naming — so contributors don't re-pass the same
+ * flags on every run. Design rules:
+ *
+ *   - Config is repo-local (`.cgraphrc` at the resolved repo root). It is NOT
+ *     read from `.cgraphx/code/` because that directory is index storage and is
+ *     commonly gitignored.
+ *   - JSON only. No YAML, no `package.json` field, no global `~/.cgraphx/code`
+ *     file in this pass.
+ *   - CLI flags always override config (see {@link mergeAnalyzeOptions}).
+ *   - Fail closed: unknown keys, wrong value types, and invalid JSON all throw
+ *     {@link GitNexusRcError} so a typo never silently no-ops. Errors are
+ *     actionable and surface before any expensive analysis.
+ *   - Config values never reach a shell. Strings are validated against control
+ *     and hidden/bidirectional characters.
+ *
+ * Both a flat shape and a nested `analyze` block are accepted:
+ *
+ *     { "pdg": true, "workerTimeout": 60 }
+ *     { "analyze": { "pdg": true } }
+ *
+ * When both set the same option, the nested `analyze` block wins (deterministic,
+ * documented precedence).
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GitNexusRcError = exports.CGRAPH_RC_FILENAME = void 0;
+exports.validateBranchName = validateBranchName;
+exports.sanitizeDetectedBranch = sanitizeDetectedBranch;
+exports.loadAnalyzeConfig = loadAnalyzeConfig;
+exports.mergeAnalyzeOptions = mergeAnalyzeOptions;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+exports.CGRAPH_RC_FILENAME = '.cgraphrc';
+/** Git refs longer than this are almost certainly a mistake / injection attempt. */
+const BRANCH_MAX_LENGTH = 255;
+/**
+ * Thrown for any `.cgraphrc` problem (missing-file is NOT an error — it
+ * returns `undefined`). The message is user-facing and names the file so the
+ * CLI can print it verbatim before starting the progress bar.
+ */
+class GitNexusRcError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'GitNexusRcError';
+    }
+}
+exports.GitNexusRcError = GitNexusRcError;
+/** Allowed `.cgraphrc` keys and how each maps onto `AnalyzeOptions`. */
+const KEY_SPECS = {
+    name: { target: 'name', kind: 'string' },
+    allowDuplicateName: { target: 'allowDuplicateName', kind: 'boolean' },
+    maxFileSize: { target: 'maxFileSize', kind: 'numeric-string' },
+    workerTimeout: { target: 'workerTimeout', kind: 'numeric-string' },
+    walCheckpointThreshold: { target: 'walCheckpointThreshold', kind: 'numeric-string' },
+    workers: { target: 'workers', kind: 'numeric-string' },
+    // #1589/#1852 residual — extra fetch-wrapper function names to treat as HTTP
+    // consumers. The auto-detector only flags functions that call the bare global
+    // `fetch()`; a wrapper built on axios / a custom client, or named outside the
+    // built-in convention set, is otherwise invisible to route_map consumers.
+    // Listing it here adds it to the cross-file consumer scan.
+    fetchWrappers: { target: 'fetchWrappers', kind: 'string-array' },
+};
+/** Top-level container key for the nested form; not itself an `AnalyzeOptions` field. */
+const NESTED_KEY = 'analyze';
+const ALLOWED_KEYS_HINT = `Allowed keys: ${Object.keys(KEY_SPECS).join(', ')} (or a nested "${NESTED_KEY}" object).`;
+/**
+ * Reject control characters and hidden / bidirectional Unicode in a string
+ * value. These have no legitimate place in a branch name, registry name, or
+ * device string, and would otherwise let a committed config smuggle invisible
+ * controls into downstream consumers.
+ */
+const isHiddenOrControl = (codePoint) => codePoint < 0x20 ||
+    codePoint === 0x7f ||
+    (codePoint >= 0x200b && codePoint <= 0x200f) || // zero-width + LRM/RLM
+    (codePoint >= 0x202a && codePoint <= 0x202e) || // bidi embeddings/overrides
+    (codePoint >= 0x2060 && codePoint <= 0x2064) || // word-joiner + invisible math
+    (codePoint >= 0x2066 && codePoint <= 0x206f) || // bidi isolates + deprecated
+    codePoint === 0xfeff; // BOM / zero-width no-break space
+const assertNoHiddenChars = (value, source) => {
+    for (const ch of value) {
+        const cp = ch.codePointAt(0);
+        if (cp !== undefined && isHiddenOrControl(cp)) {
+            throw new GitNexusRcError(`${source}: value contains control or hidden/bidirectional characters, which are not allowed.`);
+        }
+    }
+};
+/**
+ * Validate a user-supplied branch name (from CLI or `.cgraphrc`). Returns the
+ * trimmed name or throws {@link GitNexusRcError}. Conservative but accepts the
+ * shapes real branches use (`feature/foo-bar`, `release/1.2`, `develop`).
+ */
+function validateBranchName(value, source) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        throw new GitNexusRcError(`${source}: branch name must not be empty.`);
+    }
+    if (trimmed.length > BRANCH_MAX_LENGTH) {
+        throw new GitNexusRcError(`${source}: branch name is too long (max ${BRANCH_MAX_LENGTH}).`);
+    }
+    assertNoHiddenChars(trimmed, source);
+    if (/\s/.test(trimmed)) {
+        throw new GitNexusRcError(`${source}: branch name must not contain whitespace.`);
+    }
+    // git ref-name rules (subset): reject characters git itself forbids in refs.
+    if (/[~^:?*[\\]/.test(trimmed)) {
+        throw new GitNexusRcError(`${source}: branch name contains characters not allowed in a git ref (~ ^ : ? * [ \\).`);
+    }
+    if (trimmed.startsWith('-')) {
+        throw new GitNexusRcError(`${source}: branch name must not start with "-".`);
+    }
+    if (trimmed.includes('..')) {
+        throw new GitNexusRcError(`${source}: branch name must not contain "..".`);
+    }
+    // Git permits a backtick in a ref, but branch labels surface in user-facing
+    // messages and registry metadata; a backtick is rejected at this single
+    // chokepoint so all tiers (CLI flag, auto-detect via sanitizeDetectedBranch)
+    // are covered (#1996 tri-review P1).
+    if (trimmed.includes('`')) {
+        throw new GitNexusRcError(`${source}: branch name must not contain a backtick.`);
+    }
+    return trimmed;
+}
+/**
+ * Best-effort validation for an auto-detected branch (from git). Never throws —
+ * returns `undefined` for anything unusable so the resolver falls back to the
+ * next precedence tier.
+ */
+function sanitizeDetectedBranch(value) {
+    if (!value)
+        return undefined;
+    try {
+        return validateBranchName(value, 'detected branch');
+    }
+    catch {
+        return undefined;
+    }
+}
+const normalizeValue = (kind, value, key) => {
+    const source = `${exports.CGRAPH_RC_FILENAME} "${key}"`;
+    switch (kind) {
+        case 'boolean':
+            if (typeof value !== 'boolean') {
+                throw new GitNexusRcError(`${source} must be a boolean (true/false).`);
+            }
+            return value;
+        case 'string': {
+            if (typeof value !== 'string') {
+                throw new GitNexusRcError(`${source} must be a string.`);
+            }
+            const trimmed = value.trim();
+            if (!trimmed) {
+                throw new GitNexusRcError(`${source} must not be empty.`);
+            }
+            assertNoHiddenChars(trimmed, source);
+            // `name` flows into registry metadata and user-facing messages, so a
+            // Markdown-significant character is rejected (#1996 tri-review P1). `_`
+            // is intentionally allowed (legitimate in repo names). embeddingDevice
+            // (the other `string`-kind option) only ever holds a fixed device token,
+            // so this guard never rejects a valid value there.
+            if (/[`*[\]<>]/.test(trimmed)) {
+                throw new GitNexusRcError(`${source} must not contain Markdown-significant characters (\` * [ ] < >).`);
+            }
+            return trimmed;
+        }
+        case 'string-array': {
+            // Generic shared validator — `source` already names the config key, so
+            // messages here stay key-agnostic (no fetch-wrapper coupling in the
+            // shared normalizer; #1589/#1852 review F7).
+            if (!Array.isArray(value)) {
+                throw new GitNexusRcError(`${source} must be an array of strings.`);
+            }
+            const names = [];
+            for (const item of value) {
+                if (typeof item !== 'string') {
+                    throw new GitNexusRcError(`${source} entries must all be strings.`);
+                }
+                const trimmed = item.trim();
+                if (!trimmed) {
+                    throw new GitNexusRcError(`${source} entries must not be empty.`);
+                }
+                assertNoHiddenChars(trimmed, source);
+                // Values may be interpolated into a RegExp downstream. Restrict to
+                // identifier / member-access shapes so a config value can never smuggle
+                // regex metacharacters into a consumer.
+                if (!/^[A-Za-z_$][A-Za-z0-9_$.]*$/.test(trimmed)) {
+                    throw new GitNexusRcError(`${source} entry "${trimmed}" must be an identifier or member name ` +
+                        `(letters, digits, _, $, . — e.g. "client.get").`);
+                }
+                names.push(trimmed);
+            }
+            if (names.length === 0) {
+                throw new GitNexusRcError(`${source} must list at least one string.`);
+            }
+            // De-duplicate and cap to a sane bound so a pathological config cannot
+            // blow up the consumer scan's alternation.
+            return Array.from(new Set(names)).slice(0, 100);
+        }
+        case 'numeric-string': {
+            // Mirror Commander's contract: these options reach the existing CLI
+            // validation as strings. Accept a JSON number or a string; normalize to a
+            // string and let the downstream per-flag validation enforce ranges so the
+            // error messages stay in one place.
+            if (typeof value === 'number') {
+                if (!Number.isFinite(value)) {
+                    throw new GitNexusRcError(`${source} must be a finite number.`);
+                }
+                return String(value);
+            }
+            if (typeof value === 'string') {
+                const trimmed = value.trim();
+                if (!trimmed) {
+                    throw new GitNexusRcError(`${source} must not be empty.`);
+                }
+                return trimmed;
+            }
+            throw new GitNexusRcError(`${source} must be a number or numeric string.`);
+        }
+        default:
+            // Exhaustive — kept for forward-compat if a new kind is added.
+            throw new GitNexusRcError(`${source}: unsupported config value kind.`);
+    }
+};
+/**
+ * Normalize one level (flat top-level or the nested `analyze` block) into a
+ * partial `AnalyzeOptions`. Rejects unknown keys (and, defensively, two keys
+ * that map onto the same option at the same level).
+ */
+const normalizeLevel = (obj, { allowNestedKey }) => {
+    const out = {};
+    const setBy = new Map();
+    for (const [key, value] of Object.entries(obj)) {
+        if (allowNestedKey && key === NESTED_KEY)
+            continue; // handled separately
+        // `Object.hasOwn`, not a truthiness check: a plain-object lookup like
+        // `KEY_SPECS["__proto__"]` returns an inherited member (Object.prototype,
+        // truthy) and would slip past `if (!spec)`, hitting the wrong error branch
+        // instead of the documented "Unknown key" message (#1996 tri-review P3).
+        if (!Object.hasOwn(KEY_SPECS, key)) {
+            throw new GitNexusRcError(`Unknown key "${key}" in ${exports.CGRAPH_RC_FILENAME}. ${ALLOWED_KEYS_HINT}`);
+        }
+        const spec = KEY_SPECS[key];
+        const prev = setBy.get(spec.target);
+        if (prev && prev !== key) {
+            throw new GitNexusRcError(`${exports.CGRAPH_RC_FILENAME}: "${prev}" and "${key}" both configure the same option; set only one.`);
+        }
+        setBy.set(spec.target, key);
+        out[spec.target] = normalizeValue(spec.kind, value, key);
+    }
+    return out;
+};
+/**
+ * Locate, read, parse, validate, and normalize `.cgraphrc` at `repoRoot`.
+ *
+ * @returns the normalized config defaults, or `undefined` when no file exists
+ *          (the normal case). Throws {@link GitNexusRcError} on any problem.
+ */
+function loadAnalyzeConfig(repoRoot) {
+    const filePath = node_path_1.default.join(repoRoot, exports.CGRAPH_RC_FILENAME);
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        if (err?.code === 'ENOENT')
+            return undefined;
+        throw new GitNexusRcError(`Could not read ${exports.CGRAPH_RC_FILENAME}: ${err.message}`);
+    }
+    // Strip a leading UTF-8 BOM: Node's 'utf-8' decode keeps it, and JSON.parse
+    // then fails with a confusing "Unexpected token" on an otherwise-valid file
+    // (#1996 tri-review). Only one leading BOM is stripped; in-string control
+    // rejection still applies to the parsed values.
+    if (raw.charCodeAt(0) === 0xfeff)
+        raw = raw.slice(1);
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new GitNexusRcError(`${exports.CGRAPH_RC_FILENAME} is not valid JSON: ${err.message}. ` +
+            `Expected a JSON object such as {"pdg": true, "workerTimeout": 60}.`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new GitNexusRcError(`${exports.CGRAPH_RC_FILENAME} must contain a JSON object.`);
+    }
+    const obj = parsed;
+    const flat = normalizeLevel(obj, { allowNestedKey: true });
+    let nested = {};
+    if (Object.prototype.hasOwnProperty.call(obj, NESTED_KEY)) {
+        const nestedRaw = obj[NESTED_KEY];
+        if (nestedRaw === null || typeof nestedRaw !== 'object' || Array.isArray(nestedRaw)) {
+            throw new GitNexusRcError(`${exports.CGRAPH_RC_FILENAME} "${NESTED_KEY}" must be a JSON object.`);
+        }
+        nested = normalizeLevel(nestedRaw, { allowNestedKey: false });
+    }
+    // Nested `analyze` block overrides flat top-level keys for the same option.
+    return { ...flat, ...nested };
+}
+/**
+ * Merge CLI options over `.cgraphrc` defaults. CLI wins whenever it provides a
+ * value — including an explicit `false` (so an explicit CLI off-switch beats a
+ * config `true`). Config fills only the genuinely-unset (`undefined`) options.
+ */
+function mergeAnalyzeOptions(cli, config) {
+    if (!config)
+        return cli;
+    const merged = { ...cli };
+    for (const key of Object.keys(config)) {
+        if (merged[key] === undefined) {
+            merged[key] = config[key];
+        }
+    }
+    return merged;
+}