@opencodehub/ingestion 0.1.0

package/dist/parse/parse-worker.js

@@ -0,0 +1,230 @@
+/**
+ * Piscina worker entry point.
+ *
+ * Each worker thread imports this file once, then receives {@link ParseBatch}
+ * inputs on every `pool.run()` call. The worker:
+ *   1. Loads the grammar for each task's language (cached in the worker).
+ *   2. Builds a `Parser` with that language (cached).
+ *   3. Compiles the unified S-expression query (cached).
+ *   4. Parses each task's buffer and maps captures to {@link ParseCapture}.
+ *   5. Returns a {@link ParseResult} per task.
+ *
+ * Per-task wall-clock timeout: 30 seconds. On timeout the task returns a
+ * result with empty captures and a warning rather than crashing the worker.
+ *
+ * Safety: tree-sitter parsers are NOT thread-safe; one Parser per worker per
+ * language is a hard constraint. This file enforces that via per-worker maps
+ * keyed by LanguageId.
+ */
+import { Buffer } from "node:buffer";
+import { createRequire } from "node:module";
+import { performance } from "node:perf_hooks";
+import { loadGrammar } from "./grammar-registry.js";
+import { getUnifiedQuery } from "./unified-queries.js";
+import { isNativeAvailable, openWasmParser } from "./wasm-fallback.js";
+const requireFn = createRequire(import.meta.url);
+const PER_FILE_TIMEOUT_MS = 30_000;
+const MAX_FILE_BYTES = 5 * 1024 * 1024; // 5 MB
+// Per-worker caches. Each worker_thread has its own module instance so these
+// live per-worker, honoring tree-sitter's one-parser-per-thread rule.
+const parserCache = new Map();
+const queryCache = new Map();
+const wasmParserCache = new Map();
+let warnedRuntime = false;
+/**
+ * Read the `--native-parser` opt-in flag. Set either via env
+ * (`OCH_NATIVE_PARSER=1`) or via argv pass-through when the worker boots
+ * inside a process launched with the flag. The worker itself cannot read
+ * the CLI argv directly (piscina starts workers afresh) so env is the
+ * primary carrier.
+ *
+ * WASM is the default runtime as of Node 24 / M5 — the native tree-sitter
+ * N-API binding is opt-in for developer speed on Node 22 dev boxes.
+ */
+function forceNativeOpt() {
+    const v = process.env["OCH_NATIVE_PARSER"];
+    return v === "1" || v === "true";
+}
+/**
+ * Piscina task entry. Default export is the function piscina invokes.
+ */
+export default async function parseBatch(batch) {
+    // Emit a one-shot startup warning naming the runtime we actually landed
+    // on. Both paths are logged so the runtime choice is never silent — a
+    // user debugging a parse difference can see "native" vs "WASM" on the
+    // first worker invocation.
+    if (!warnedRuntime) {
+        warnedRuntime = true;
+        const usingNative = forceNativeOpt() && isNativeAvailable();
+        if (usingNative) {
+            process.stderr.write("[parse-worker] using tree-sitter native (N-API) runtime\n");
+        }
+        else if (forceNativeOpt() && !isNativeAvailable()) {
+            // Opt-in requested but native could not load — fall back to WASM
+            // with an explicit callout so the user notices the mismatch.
+            process.stderr.write("[parse-worker] OCH_NATIVE_PARSER=1 set but native tree-sitter unavailable; falling back to web-tree-sitter (WASM) runtime\n");
+        }
+        else {
+            process.stderr.write("[parse-worker] using web-tree-sitter (WASM) runtime\n");
+        }
+    }
+    const results = [];
+    for (const task of batch.tasks) {
+        results.push(await parseOne(task));
+    }
+    return results;
+}
+async function parseOne(task) {
+    const start = performance.now();
+    const warnings = [];
+    // piscina's structured-clone transport converts a Buffer into a plain
+    // Uint8Array on the worker side. Re-wrap so our Buffer-specific calls
+    // (notably `.toString('utf8')`) work as expected.
+    const content = Buffer.isBuffer(task.content)
+        ? task.content
+        : Buffer.from(task.content.buffer, task.content.byteOffset, task.content.byteLength);
+    const byteLength = content.byteLength;
+    if (byteLength > MAX_FILE_BYTES) {
+        warnings.push(`file exceeds ${MAX_FILE_BYTES} byte cap (${byteLength}); skipping parse`);
+        return {
+            filePath: task.filePath,
+            language: task.language,
+            captures: [],
+            byteLength,
+            parseTimeMs: performance.now() - start,
+            warnings,
+        };
+    }
+    try {
+        const captures = await withTimeout(runParse(task.language, content), PER_FILE_TIMEOUT_MS, `parse timed out after ${PER_FILE_TIMEOUT_MS}ms`);
+        return {
+            filePath: task.filePath,
+            language: task.language,
+            captures,
+            byteLength,
+            parseTimeMs: performance.now() - start,
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        warnings.push(message);
+        return {
+            filePath: task.filePath,
+            language: task.language,
+            captures: [],
+            byteLength,
+            parseTimeMs: performance.now() - start,
+            warnings,
+        };
+    }
+}
+async function runParse(language, content) {
+    // The tree-sitter 0.25 JS binding accepts a string primary input; decode
+    // the buffer once here. (The underlying parser still reads by byte
+    // offsets, so positions remain correct.)
+    const source = content.toString("utf8");
+    // WASM is the default runtime. Native tree-sitter is opt-in via
+    // `OCH_NATIVE_PARSER=1` (or `--native-parser` on the CLI) and still
+    // requires the N-API binding to load cleanly; if the opt-in is set but
+    // native is unavailable, we fall back to WASM (the startup warning in
+    // parseBatch already flagged the mismatch). The two paths produce
+    // semantically equivalent captures — the (tag, text) multiset is
+    // asserted identical by wasm-parity.test.ts, though coordinate values
+    // and internal node types may differ at the margins across grammars.
+    if (forceNativeOpt() && isNativeAvailable()) {
+        return runNative(language, source);
+    }
+    return runWasm(language, source);
+}
+async function runNative(language, source) {
+    // tree-sitter module is loaded lazily via require (not a static import)
+    // to keep cold-start cheap for workers that may never parse any file.
+    const TreeSitter = requireFn("tree-sitter");
+    const parser = await getOrBuildParser(language, TreeSitter);
+    const query = await getOrBuildQuery(language, TreeSitter);
+    const tree = parser.parse(source);
+    const root = tree.rootNode;
+    const out = [];
+    const matches = query.matches(root);
+    for (const m of matches) {
+        for (const cap of m.captures) {
+            const node = cap.node;
+            out.push({
+                tag: cap.name,
+                text: node.text,
+                // Convert 0-indexed tree-sitter positions to 1-indexed line numbers.
+                startLine: node.startPosition.row + 1,
+                endLine: node.endPosition.row + 1,
+                startCol: node.startPosition.column,
+                endCol: node.endPosition.column,
+                nodeType: node.type,
+            });
+        }
+    }
+    return out;
+}
+async function runWasm(language, source) {
+    let handle = wasmParserCache.get(language);
+    if (handle === undefined) {
+        handle = await openWasmParser(language);
+        wasmParserCache.set(language, handle);
+    }
+    if (handle === null) {
+        // Grammar unavailable on the WASM path; skip with a per-file warning
+        // surface so the worker's caller can see the miss.
+        return [];
+    }
+    const queryText = getUnifiedQuery(language);
+    const captures = handle.runQuery(queryText, source);
+    const out = [];
+    for (const cap of captures) {
+        const node = cap.node;
+        out.push({
+            tag: cap.name,
+            text: node.text,
+            startLine: node.startPosition.row + 1,
+            endLine: node.endPosition.row + 1,
+            startCol: node.startPosition.column,
+            endCol: node.endPosition.column,
+            nodeType: node.type,
+        });
+    }
+    return out;
+}
+// --- per-worker caches -----------------------------------------------------
+async function getOrBuildParser(lang, TS) {
+    const cached = parserCache.get(lang);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const handle = await loadGrammar(lang);
+    const parser = new TS();
+    parser.setLanguage(handle.tsLanguage);
+    parserCache.set(lang, parser);
+    return parser;
+}
+async function getOrBuildQuery(lang, TS) {
+    const cached = queryCache.get(lang);
+    if (cached !== undefined) {
+        return cached;
+    }
+    const handle = await loadGrammar(lang);
+    const q = new TS.Query(handle.tsLanguage, handle.queryText);
+    queryCache.set(lang, q);
+    return q;
+}
+// --- wall-clock timeout ----------------------------------------------------
+function withTimeout(p, ms, message) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(message)), ms);
+        p.then((v) => {
+            clearTimeout(timer);
+            resolve(v);
+        }, (e) => {
+            clearTimeout(timer);
+            reject(e);
+        });
+    });
+}
+//# sourceMappingURL=parse-worker.js.map

package/dist/parse/parse-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-worker.js","sourceRoot":"","sources":["../../src/parse/parse-worker.ts"],"names":[],"mappings":"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"}

package/dist/parse/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Shared types for the parse subsystem.
+ *
+ * These are the cross-boundary shapes exchanged between the main thread,
+ * the piscina worker pool, and downstream symbol-extraction code.
+ *
+ * All positions are normalized to 1-indexed line numbers and 0-indexed
+ * column offsets (matching most editor UIs).
+ */
+import type { LanguageId } from "@opencodehub/core-types";
+export type { LanguageId } from "@opencodehub/core-types";
+/** A single tagged node extracted from a parse tree by the unified query. */
+export interface ParseCapture {
+    /** Capture tag, e.g. `definition.class`, `reference.call`, `name`, `doc`. */
+    readonly tag: string;
+    /** Text slice the capture refers to (identifier name, snippet, etc.). */
+    readonly text: string;
+    /** 1-indexed line where the capture starts. */
+    readonly startLine: number;
+    /** 1-indexed line where the capture ends. */
+    readonly endLine: number;
+    /** 0-indexed column offset where the capture starts. */
+    readonly startCol: number;
+    /** 0-indexed column offset where the capture ends. */
+    readonly endCol: number;
+    /** Underlying tree-sitter node type — useful for debugging queries. */
+    readonly nodeType: string;
+}
+/** Result of parsing a single file. */
+export interface ParseResult {
+    readonly filePath: string;
+    readonly language: LanguageId;
+    readonly captures: readonly ParseCapture[];
+    readonly byteLength: number;
+    readonly parseTimeMs: number;
+    readonly warnings?: readonly string[];
+}
+/** Request to parse a single file. */
+export interface ParseTask {
+    readonly filePath: string;
+    /** Raw file bytes — avoids a UTF-8 round-trip in the worker. */
+    readonly content: Buffer;
+    readonly language: LanguageId;
+}
+/** A batch of parse tasks sent to a single worker invocation. */
+export interface ParseBatch {
+    readonly tasks: readonly ParseTask[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/parse/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/parse/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAMH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,YAAY,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,yEAAyE;IACzE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,uCAAuC;AACvC,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAC;IAC3C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,sCAAsC;AACtC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gEAAgE;IAChE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;CAC/B;AAED,iEAAiE;AACjE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,SAAS,EAAE,CAAC;CACtC"}

package/dist/parse/types.js

@@ -0,0 +1,11 @@
+/**
+ * Shared types for the parse subsystem.
+ *
+ * These are the cross-boundary shapes exchanged between the main thread,
+ * the piscina worker pool, and downstream symbol-extraction code.
+ *
+ * All positions are normalized to 1-indexed line numbers and 0-indexed
+ * column offsets (matching most editor UIs).
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/parse/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/parse/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/parse/unified-queries.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Unified cross-language S-expression queries.
+ *
+ * Clean-room authored from tree-sitter's code-navigation tag vocabulary:
+ *   definition.{class,function,method,interface,module,macro,constant,type}
+ *   reference.{call,class,type,interface,implementation,send}
+ *   doc   — documentation comment (JSDoc / docstring / rustdoc / godoc)
+ *   name  — inner capture for identifier substrings
+ *
+ * Docstring conventions captured here:
+ *   - JSDoc (TS/JS/TSX): comment nodes; the parse-phase consumer
+ *     narrows to those whose text begins with "/*" "*".
+ *   - Python: first expression_statement string child in a body.
+ *   - Rust: line_comment / block_comment groups above a decl; the
+ *     parse-phase consumer filters to triple-slash and rustdoc forms.
+ *   - Go: comment groups immediately preceding a declaration.
+ *
+ * These queries are authored independently from grammar tags.scm files by
+ * reading only the grammar's public AST node type names. No text is copied
+ * from any external source. License: Apache-2.0.
+ */
+import type { LanguageId } from "./types.js";
+/**
+ * Regex-provider sentinel. COBOL ships via the pure-regex extractor in
+ * `parse/cobol-regex.ts`; there is no tree-sitter grammar and therefore no
+ * S-expression query body. The sentinel is a stable string constant
+ * downstream consumers can match on (`query === REGEX_PROVIDER_SENTINEL`)
+ * to dispatch around the worker pool. The `"regex:<lang>"` prefix is
+ * intentional — unlike an empty string, it pattern-matches on read and
+ * never collides with a valid tree-sitter query body.
+ */
+export declare const REGEX_PROVIDER_SENTINEL = "regex:cobol";
+/** Return the unified S-expression query body for a given language. */
+export declare function getUnifiedQuery(lang: LanguageId): string;
+/** `true` iff `lang`'s query body is a regex-provider sentinel. */
+export declare function isRegexProviderQuery(query: string): boolean;
+//# sourceMappingURL=unified-queries.d.ts.map

package/dist/parse/unified-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unified-queries.d.ts","sourceRoot":"","sources":["../../src/parse/unified-queries.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAskB7C;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB,gBAAgB,CAAC;AAqBrD,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAExD;AAED,mEAAmE;AACnE,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAE3D"}