knodin 0.7.6 → 0.8.2

package/dist/src/engine/scip-import.js

@@ -0,0 +1,423 @@
+import fs from "node:fs";
+import path from "node:path";
+import { compareBytes } from "../compare.js";
+export const SCIP_DEFAULT_LIMITS = {
+    maxBytes: 64 * 1024 * 1024,
+    maxFiles: 10_000,
+    maxFacts: 250_000,
+    timeoutMs: 30_000,
+};
+const textDecoder = new TextDecoder("utf-8", { fatal: true });
+let activeDeadline = Number.POSITIVE_INFINITY;
+let activeTimeoutMs = 0;
+function fail(message) {
+    activeDeadline = Number.POSITIVE_INFINITY;
+    activeTimeoutMs = 0;
+    throw new Error(`knodin SCIP import: ${message}`);
+}
+function checkDeadline() {
+    if (performance.now() > activeDeadline)
+        fail(`import exceeded the ${activeTimeoutMs} ms limit. Raise it with --scip-timeout-ms.`);
+}
+function readVarint(bytes, offset) {
+    let value = 0;
+    let shift = 0;
+    for (let count = 0; count < 10 && offset < bytes.length; count++) {
+        const byte = bytes[offset++];
+        if (shift < 53)
+            value += (byte & 0x7f) * 2 ** shift;
+        if ((byte & 0x80) === 0)
+            return [value, offset];
+        shift += 7;
+    }
+    return fail("malformed protobuf varint");
+}
+function visitFields(bytes, visitor) {
+    let offset = 0;
+    while (offset < bytes.length) {
+        checkDeadline();
+        let tag;
+        [tag, offset] = readVarint(bytes, offset);
+        const number = Math.floor(tag / 8);
+        const wire = tag & 7;
+        if (number < 1)
+            fail("malformed protobuf field number");
+        if (wire === 0) {
+            let value;
+            [value, offset] = readVarint(bytes, offset);
+            visitor(number, wire, value);
+        }
+        else if (wire === 2) {
+            let length;
+            [length, offset] = readVarint(bytes, offset);
+            if (!Number.isSafeInteger(length) || length < 0 || offset + length > bytes.length)
+                fail("malformed protobuf length");
+            visitor(number, wire, bytes.subarray(offset, offset + length));
+            offset += length;
+        }
+        else if (wire === 1) {
+            offset += 8;
+        }
+        else if (wire === 5) {
+            offset += 4;
+        }
+        else {
+            fail(`unsupported protobuf wire type ${wire}`);
+        }
+        if (offset > bytes.length)
+            fail("truncated protobuf field");
+    }
+}
+function countLengthDelimitedFields(bytes, target, maximum) {
+    let count = 0;
+    let offset = 0;
+    while (offset < bytes.length) {
+        checkDeadline();
+        let tag;
+        [tag, offset] = readVarint(bytes, offset);
+        const number = Math.floor(tag / 8);
+        const wire = tag & 7;
+        if (number < 1)
+            fail("malformed protobuf field number");
+        if (wire === 0) {
+            [, offset] = readVarint(bytes, offset);
+        }
+        else if (wire === 2) {
+            let length;
+            [length, offset] = readVarint(bytes, offset);
+            if (!Number.isSafeInteger(length) || length < 0 || offset + length > bytes.length)
+                fail("malformed protobuf length");
+            if (number === target && ++count > maximum)
+                return count;
+            offset += length;
+        }
+        else if (wire === 1)
+            offset += 8;
+        else if (wire === 5)
+            offset += 4;
+        else
+            fail(`unsupported protobuf wire type ${wire}`);
+        if (offset > bytes.length)
+            fail("truncated protobuf field");
+    }
+    return count;
+}
+function strings(message, number) {
+    const result = [];
+    visitFields(message, (fieldNumber, wire, value) => {
+        if (fieldNumber === number && wire === 2)
+            result.push(textDecoder.decode(value));
+    });
+    return result;
+}
+function messages(message, number) {
+    const result = [];
+    visitFields(message, (fieldNumber, wire, value) => {
+        if (fieldNumber === number && wire === 2)
+            result.push(value);
+    });
+    return result;
+}
+function numberField(message, number) {
+    let result = 0;
+    let found = false;
+    visitFields(message, (fieldNumber, wire, value) => {
+        if (!found && fieldNumber === number && wire === 0) {
+            result = value;
+            found = true;
+        }
+    });
+    return result;
+}
+function packedNumbers(message, number) {
+    const result = [];
+    visitFields(message, (fieldNumber, wire, value) => {
+        if (fieldNumber !== number)
+            return;
+        if (wire === 0)
+            result.push(value);
+        if (wire === 2) {
+            const bytes = value;
+            let offset = 0;
+            while (offset < bytes.length) {
+                let packedValue;
+                [packedValue, offset] = readVarint(bytes, offset);
+                result.push(packedValue);
+            }
+        }
+    });
+    return result;
+}
+function parseRange(values) {
+    if (values.length !== 3 && values.length !== 4)
+        fail("range must contain three or four integers");
+    const [startLine, startCol] = values;
+    const endLine = values.length === 3 ? startLine : values[2];
+    const endCol = values.length === 3 ? values[2] : values[3];
+    if ([startLine, startCol, endLine, endCol].some((value) => !Number.isSafeInteger(value)))
+        fail("range contains an unsafe integer");
+    if (endLine < startLine || (endLine === startLine && endCol < startCol))
+        fail("range is reversed");
+    return { startLine, startCol, endLine, endCol };
+}
+function parseOccurrence(message) {
+    const singleLine = messages(message, 8)[0];
+    const multiLine = messages(message, 9)[0];
+    const symbol = strings(message, 2)[0] ?? "";
+    let range;
+    if (singleLine) {
+        const line = numberField(singleLine, 1);
+        range = parseRange([line, numberField(singleLine, 2), numberField(singleLine, 3)]);
+    }
+    else if (multiLine) {
+        range = parseRange([
+            numberField(multiLine, 1),
+            numberField(multiLine, 2),
+            numberField(multiLine, 3),
+            numberField(multiLine, 4),
+        ]);
+    }
+    else {
+        range = parseRange(packedNumbers(message, 1));
+    }
+    if (!symbol)
+        fail("occurrence is missing its symbol");
+    return { range, symbol, roles: numberField(message, 3) };
+}
+function parseSymbolInfo(message) {
+    const symbol = strings(message, 1)[0] ?? "";
+    if (!symbol)
+        fail("symbol information is missing its symbol");
+    return {
+        symbol,
+        displayName: strings(message, 6)[0] ?? "",
+        kind: numberField(message, 5),
+        relationships: messages(message, 4).map((relationship) => ({
+            symbol: strings(relationship, 1)[0] ?? "",
+            isReference: numberField(relationship, 2) !== 0,
+            isImplementation: numberField(relationship, 3) !== 0,
+            isTypeDefinition: numberField(relationship, 4) !== 0,
+            isDefinition: numberField(relationship, 5) !== 0,
+        })),
+    };
+}
+function safeRelativePath(repoPath, value) {
+    if (!value || value.includes("\0") || path.isAbsolute(value))
+        fail(`hostile document path ${JSON.stringify(value)}`);
+    const normalized = value.replaceAll("\\", "/");
+    if (normalized.split("/").some((part) => part === ".." || part === ""))
+        fail(`hostile document path ${JSON.stringify(value)}`);
+    const absolute = path.resolve(repoPath, normalized);
+    const relative = path.relative(repoPath, absolute);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        fail(`document escapes repository: ${value}`);
+    let stat;
+    try {
+        stat = fs.lstatSync(absolute);
+    }
+    catch {
+        return fail(`document is missing: ${normalized}`);
+    }
+    if (!stat.isFile() || stat.isSymbolicLink())
+        fail(`document is not a regular repository file: ${normalized}`);
+    return normalized;
+}
+function symbolName(symbol, displayName) {
+    if (displayName.trim())
+        return displayName.trim();
+    if (symbol.startsWith("local "))
+        return symbol;
+    const descriptor = symbol.trim().split(/\s+/).at(-1) ?? symbol;
+    const withoutSuffix = descriptor.replace(/\([^)]*\)\.$|[#/.:!]$/, "");
+    const cleaned = (withoutSuffix.split(/[/#]/).at(-1) ?? descriptor).replaceAll("`", "");
+    return cleaned || symbol;
+}
+function symbolKind(_kind) {
+    // Do not translate a versioned producer enum into a potentially false native
+    // semantic kind; the original SCIP symbol remains in provenance.
+    return "SCIP_Symbol";
+}
+function parseMetadata(index) {
+    const metadata = messages(index, 1)[0];
+    if (!metadata)
+        return [];
+    const toolInfo = messages(metadata, 2)[0];
+    if (!toolInfo)
+        return [];
+    const name = strings(toolInfo, 1)[0];
+    const version = strings(toolInfo, 2)[0];
+    const suffix = version ? `@${version}` : "";
+    return name ? [`${name}${suffix}`] : [];
+}
+export function readScipIndex(repoPath, options) {
+    const started = performance.now();
+    const limits = { ...SCIP_DEFAULT_LIMITS, ...options };
+    for (const [name, value] of Object.entries(limits)) {
+        if (name === "path")
+            continue;
+        if (!Number.isSafeInteger(value) || value < 1)
+            fail(`${name} must be a positive integer`);
+    }
+    activeTimeoutMs = limits.timeoutMs;
+    activeDeadline = started + limits.timeoutMs;
+    const resolvedRepo = path.resolve(repoPath);
+    const inputPath = path.resolve(resolvedRepo, options.path);
+    const inputRelative = path.relative(resolvedRepo, inputPath);
+    if (inputRelative.startsWith("..") || path.isAbsolute(inputRelative))
+        fail("input path escapes repository");
+    let inputStat;
+    try {
+        inputStat = fs.lstatSync(inputPath);
+    }
+    catch {
+        return fail(`input is missing: ${inputRelative}`);
+    }
+    if (!inputStat.isFile() || inputStat.isSymbolicLink())
+        fail("input must be a regular repository file");
+    // A ceiling nobody can raise is just a failure, so name the flag and a value
+    // that would admit this file.
+    if (inputStat.size > limits.maxBytes)
+        fail(`input is ${inputStat.size.toLocaleString()} bytes, over the ` +
+            `${limits.maxBytes.toLocaleString()} byte limit. Raise it with ` +
+            `--scip-max-bytes ${inputStat.size}, or narrow the indexer that produced this file.`);
+    const bytes = fs.readFileSync(inputPath);
+    const index = new Uint8Array(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const documents = [];
+    let parsedFacts = 0;
+    const documentCount = countLengthDelimitedFields(index, 2, limits.maxFiles);
+    if (documentCount > limits.maxFiles)
+        fail(`index covers ${documentCount.toLocaleString()} files, over the ` +
+            `${limits.maxFiles.toLocaleString()} file limit. Raise it with ` +
+            `--scip-max-files ${documentCount}, or narrow the indexer that produced this file.`);
+    for (const message of messages(index, 2)) {
+        const filePath = safeRelativePath(resolvedRepo, strings(message, 1)[0] ?? "");
+        const sourceStat = fs.statSync(path.join(resolvedRepo, filePath));
+        if (sourceStat.mtimeMs > inputStat.mtimeMs + 1)
+            fail(`input is stale for ${filePath}`);
+        const occurrenceCount = countLengthDelimitedFields(message, 2, limits.maxFacts - parsedFacts);
+        parsedFacts += occurrenceCount;
+        if (parsedFacts > limits.maxFacts)
+            fail(`index exceeds the ${limits.maxFacts.toLocaleString()} fact limit. ` +
+                `Raise it with --scip-max-facts, or narrow the indexer that produced this file.`);
+        const symbolCount = countLengthDelimitedFields(message, 3, limits.maxFacts - parsedFacts);
+        parsedFacts += symbolCount;
+        if (parsedFacts > limits.maxFacts)
+            fail(`index exceeds the ${limits.maxFacts.toLocaleString()} fact limit. ` +
+                `Raise it with --scip-max-facts, or narrow the indexer that produced this file.`);
+        const occurrenceMessages = messages(message, 2);
+        const symbolMessages = messages(message, 3);
+        for (const symbolMessage of symbolMessages) {
+            const remainingRelationships = Math.floor((limits.maxFacts - parsedFacts) / 4);
+            parsedFacts += countLengthDelimitedFields(symbolMessage, 4, remainingRelationships) * 4;
+            if (parsedFacts > limits.maxFacts)
+                fail(`index exceeds the ${limits.maxFacts.toLocaleString()} fact limit. ` +
+                    `Raise it with --scip-max-facts, or narrow the indexer that produced this file.`);
+        }
+        documents.push({
+            filePath,
+            language: strings(message, 4)[0] ?? "unknown",
+            occurrences: occurrenceMessages.map(parseOccurrence),
+            symbols: symbolMessages.map(parseSymbolInfo),
+        });
+        if (performance.now() - started > limits.timeoutMs)
+            fail(`import exceeded ${limits.timeoutMs} ms limit`);
+    }
+    const scopedSymbol = (document, symbol) => symbol.startsWith("local ") ? `${document.filePath}\0${symbol}` : `\0${symbol}`;
+    const definitions = new Map();
+    for (const document of documents) {
+        const infos = new Map(document.symbols.map((info) => [info.symbol, info]));
+        for (const occurrence of document.occurrences) {
+            const key = scopedSymbol(document, occurrence.symbol);
+            if ((occurrence.roles & 1) !== 0 && !definitions.has(key)) {
+                definitions.set(key, {
+                    document,
+                    occurrence,
+                    info: infos.get(occurrence.symbol),
+                });
+            }
+        }
+    }
+    const symbols = [...definitions.values()].map((definition) => ({
+        symbol: definition.occurrence.symbol,
+        name: symbolName(definition.occurrence.symbol, definition.info?.displayName ?? ""),
+        kind: symbolKind(definition.info?.kind ?? 0),
+        filePath: definition.document.filePath,
+        startLine: definition.occurrence.range.startLine + 1,
+        endLine: definition.occurrence.range.endLine + 1,
+        startCol: definition.occurrence.range.startCol + 1,
+        endCol: definition.occurrence.range.endCol + 1,
+    }));
+    const references = [];
+    for (const document of documents) {
+        for (const occurrence of document.occurrences) {
+            if ((occurrence.roles & 1) !== 0)
+                continue;
+            const target = definitions.get(scopedSymbol(document, occurrence.symbol));
+            if (!target)
+                continue;
+            references.push({
+                callerSymbol: null,
+                callerFile: document.filePath,
+                calleeSymbol: symbolName(occurrence.symbol, target.info?.displayName ?? ""),
+                calleeFile: target.document.filePath,
+                line: occurrence.range.startLine + 1,
+                column: occurrence.range.startCol + 1,
+                kind: "scip_reference",
+            });
+        }
+        for (const info of document.symbols) {
+            const source = definitions.get(scopedSymbol(document, info.symbol));
+            if (!source)
+                continue;
+            for (const relationship of info.relationships) {
+                const target = definitions.get(scopedSymbol(document, relationship.symbol));
+                if (!target)
+                    continue;
+                const kinds = [];
+                if (relationship.isReference)
+                    kinds.push("scip_relationship_reference");
+                if (relationship.isImplementation)
+                    kinds.push("scip_implementation");
+                if (relationship.isTypeDefinition)
+                    kinds.push("scip_type_definition");
+                if (relationship.isDefinition)
+                    kinds.push("scip_definition");
+                for (const kind of kinds)
+                    references.push({
+                        callerSymbol: symbolName(info.symbol, info.displayName),
+                        callerFile: source.document.filePath,
+                        calleeSymbol: symbolName(relationship.symbol, target.info?.displayName ?? ""),
+                        calleeFile: target.document.filePath,
+                        line: source.occurrence.range.startLine + 1,
+                        column: source.occurrence.range.startCol + 1,
+                        kind,
+                    });
+            }
+        }
+    }
+    const factCount = symbols.length + references.length;
+    if (factCount > limits.maxFacts)
+        fail(`index exceeds ${limits.maxFacts} fact limit`);
+    if (performance.now() - started > limits.timeoutMs)
+        fail(`import exceeded ${limits.timeoutMs} ms limit`);
+    // Byte order: imported facts are persisted and compared across runs, so their
+    // order has to be a function of the bytes rather than of host collation.
+    symbols.sort((a, b) => compareBytes(a.filePath, b.filePath) || a.startLine - b.startLine);
+    references.sort((a, b) => compareBytes(a.callerFile, b.callerFile) ||
+        a.line - b.line ||
+        compareBytes(a.calleeSymbol, b.calleeSymbol));
+    const result = {
+        inputPath: inputRelative.replaceAll("\\", "/"),
+        bytes: inputStat.size,
+        files: documents.length,
+        facts: factCount,
+        languages: [...new Set(documents.map((document) => document.language))].sort(compareBytes),
+        indexers: parseMetadata(index).sort(compareBytes),
+        symbols,
+        references,
+        elapsedMs: Math.round((performance.now() - started) * 1000) / 1000,
+    };
+    activeDeadline = Number.POSITIVE_INFINITY;
+    activeTimeoutMs = 0;
+    return result;
+}

package/dist/src/engine/source-policy.js

@@ -0,0 +1,85 @@
+import path from "node:path";
+import { isIndexablePath } from "./prune.js";
+const SOURCE_EXTENSIONS = new Set([
+    ".ts",
+    ".tsx",
+    ".mts",
+    ".cts",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".cjs",
+    ".py",
+    ".cls",
+    ".trigger",
+    ".page",
+    ".component",
+    ".app",
+    ".cmp",
+    ".design",
+    ".docs",
+    ".evt",
+    ".intf",
+    ".svg",
+    ".sql",
+    ".pkb",
+    ".pks",
+    ".prisma",
+    ".java",
+    ".cs",
+    ".go",
+    ".rs",
+    ".clp",
+    ".ws",
+    ".xml",
+    ".tf",
+    ".tfvars",
+    ".hcl",
+    ".dockerfile",
+    ".lsif",
+    // Documentation participates as a link-only graph: doc-to-doc and doc-to-code
+    // edges, no symbols. Without it, "which docs describe this subsystem" and
+    // "which docs point at code that no longer exists" are unanswerable.
+    ".md",
+    ".mdx",
+    // CI pipeline definitions participate as link-only template references.
+    ".yml",
+    ".yaml",
+    // The .NET build graph: project-to-project references across services.
+    ".csproj",
+    ".sln",
+    ".props",
+    ".targets",
+    // Razor views/components: the C# members in their @code/@functions blocks.
+    ".cshtml",
+    ".razor",
+]);
+function isSalesforceBundleMarkup(normalized) {
+    return (/^force-app\/main\/default\/lwc\/([A-Za-z][A-Za-z0-9_]*)\/\1\.(?:html|css)$/.test(normalized) ||
+        /^force-app\/main\/default\/aura\/([A-Za-z][A-Za-z0-9_]*)\/\1\.(?:css)$/.test(normalized));
+}
+function isSalesforceExperienceJson(normalized) {
+    return (normalized === "lwr.config.json" ||
+        /^force-app\/main\/default\/experiences\/[A-Za-z][A-Za-z0-9_]*\/(?:routes|views|themes)\/[^/]+\.json$/.test(normalized));
+}
+/**
+ * Canonical, path-only candidate policy shared by full-repository collection,
+ * file watching, repair selection, and Git-hook refresh. Content-sensitive
+ * formats (currently dbt manifest.json) are accepted as candidates here and
+ * validated by the parser before symbols are persisted.
+ */
+export function isIndexableSourcePath(relativePath) {
+    if (!isIndexablePath(relativePath))
+        return false;
+    const normalized = relativePath.replaceAll("\\", "/");
+    const base = path.posix.basename(normalized);
+    if (base === "Dockerfile")
+        return true;
+    if (normalized.endsWith(".json")) {
+        return base === "manifest.json" || isSalesforceExperienceJson(normalized);
+    }
+    if (normalized.endsWith(".html") || normalized.endsWith(".css")) {
+        return isSalesforceBundleMarkup(normalized);
+    }
+    return SOURCE_EXTENSIONS.has(path.posix.extname(normalized));
+}

package/dist/src/engine/sqlite.js

@@ -0,0 +1,71 @@
+/**
+ * Production SQLite adapter for the Node runtime.
+ *
+ * knodin's engine was originally written against the compact `bun:sqlite`
+ * surface. Node 24 ships `node:sqlite` without a runtime flag, so this adapter
+ * preserves the engine's existing typed `query<Row, Params>()` contract while
+ * using Node's native `DatabaseSync` implementation underneath.
+ */
+import { DatabaseSync } from "node:sqlite";
+/**
+ * knodin's call sites pass bind params either spread (`stmt.all(a, b)`) or as a
+ * single array (`db.run(sql, [a, b])`). node:sqlite wants them spread — normalize a
+ * lone array argument back into a spread list. SQLite has no array column type,
+ * so a single array can only ever mean "the parameter list", never one value.
+ */
+function normalize(params) {
+    if (params.length === 1 && Array.isArray(params[0]))
+        return params[0];
+    return params;
+}
+class Statement {
+    // node:sqlite's parameter union is intentionally narrower than the engine's
+    // generic call-site contract. Runtime validation still belongs to SQLite.
+    // biome-ignore lint/suspicious/noExplicitAny: adapter boundary around native bindings.
+    stmt;
+    // biome-ignore lint/suspicious/noExplicitAny: adapter boundary around native bindings.
+    constructor(stmt) {
+        this.stmt = stmt;
+    }
+    all(...params) {
+        return this.stmt.all(...normalize(params));
+    }
+    get(...params) {
+        return (this.stmt.get(...normalize(params)) ?? null);
+    }
+    run(...params) {
+        return this.stmt.run(...normalize(params));
+    }
+    finalize() {
+        // node:sqlite statements are released on GC; there is nothing to finalize.
+    }
+}
+export class Database {
+    db;
+    constructor(databasePath, options = {}) {
+        this.db = new DatabaseSync(databasePath, { readOnly: options.readonly === true });
+    }
+    query(sql) {
+        return new Statement(this.db.prepare(sql));
+    }
+    prepare(sql) {
+        return new Statement(this.db.prepare(sql));
+    }
+    run(sql, ...params) {
+        if (params.length === 0) {
+            // DDL / PRAGMA / BEGIN / COMMIT / multi-statement schema — `exec` avoids
+            // prepare() edge cases and handles more-than-one statement in one string.
+            this.db.exec(sql);
+            return { changes: 0, lastInsertRowid: 0 };
+        }
+        // biome-ignore lint/suspicious/noExplicitAny: adapter boundary around native bindings.
+        const statement = this.db.prepare(sql);
+        return statement.run(...normalize(params));
+    }
+    exec(sql) {
+        this.db.exec(sql);
+    }
+    close() {
+        this.db.close();
+    }
+}