@opencodehub/ingestion 0.1.0

package/dist/parse/cobol-regex.js

@@ -0,0 +1,355 @@
+/**
+ * COBOL regex hot path.
+ *
+ * Pure-function extractor for fixed-format COBOL files (`.cbl`, `.cob`,
+ * `.cpy`). Emits {@link CobolElement} records for the five targets that a
+ * human reader would use to navigate a legacy mainframe program:
+ *
+ *   - `program-id`   — `PROGRAM-ID. <name>.`, one per file
+ *   - `paragraph`    — labels in Area A: `^[ ]{7}[A-Z0-9][A-Z0-9-]*\.`
+ *   - `perform`      — `PERFORM <identifier>`, each occurrence (heuristic
+ *                      CALL-like reference; the enclosing paragraph is the
+ *                      caller)
+ *   - `copy`         — `COPY <name>`, each occurrence (copybook inclusion)
+ *   - `cics`         — `EXEC CICS ... END-EXEC` spans (multi-line aware)
+ *
+ * ## Fixed-format COBOL refresher
+ *
+ *   Columns 1-6   sequence numbers (ignored)
+ *   Column  7     indicator area: `*` or `/` = comment line, `-` =
+ *                 continuation, `D` = debugging aid, ` ` = normal
+ *   Columns 8-11  Area A: divisions, sections, paragraphs
+ *   Columns 12-72 Area B: statements
+ *   Columns 73-80 identification (ignored)
+ *
+ * The default parse path runs at ≤ 1 ms on 1000-line fixtures; a p50
+ * regression in that number is a graph-ingestion regression.
+ *
+ * ## Anti-goals
+ *
+ *   - NOT a full parse: `PERFORM ... THRU ... VARYING`, `COPY ... REPLACING
+ *     ==tag== BY ==value==`, and nested `EXEC SQL` blocks are all resolved
+ *     heuristically. The deep-parse path (ProLeap, when wired in) owns the
+ *     precise AST.
+ *   - NOT free-format aware: the 99% legacy estate is fixed-format;
+ *     free-format COBOL (column-0 start) lands with the ProLeap backend.
+ *   - NO filesystem I/O, NO subprocesses, NO external deps. The function
+ *     is pure over `(path, content)`.
+ *
+ * ## Author's note
+ *
+ * The regex vocabulary here (PROGRAM-ID, PARAGRAPH, PERFORM, COPY, CICS) is
+ * explicitly allow-listed in `scripts/check-banned-strings.sh` (U2 in spec
+ * 004) because it's the standard public COBOL surface.
+ */
+// ---------------------------------------------------------------------------
+// Regexes (all case-insensitive; the `/i` flag is set at the source below).
+// ---------------------------------------------------------------------------
+/**
+ * PROGRAM-ID. <name>.  May have spaces around the period.
+ * We intentionally match the full line rather than positional columns so a
+ * mildly-misaligned fixture still classifies. A well-formed PROGRAM-ID sits
+ * in Area A (column 8), and the matcher still works there too.
+ */
+const PROGRAM_ID_RE = /\bPROGRAM-ID\s*\.\s*([A-Z0-9][A-Z0-9-]*)/i;
+/**
+ * Paragraph label: 6 arbitrary chars (sequence area), a blank indicator
+ * column, then a bare identifier plus a period at the start of Area A.
+ * Legacy fixed-format lines often put digits in the sequence area
+ * (`000100 MAIN-PARA.`), so we allow any character there rather than
+ * insisting on 6 spaces. The matcher is applied only to non-comment
+ * lines whose column 7 is blank — enforced via the explicit ` ` after
+ * the `.{6}` anchor.
+ */
+const PARAGRAPH_RE = /^.{6} ([A-Z0-9][A-Z0-9-]*)\.\s*$/i;
+/**
+ * PERFORM <identifier>. We strip the `VARYING`, `UNTIL`, `TIMES`, `THRU`,
+ * `THROUGH`, `WITH`, `TEST` keywords out of the set of valid target names
+ * so they don't masquerade as paragraphs. Occurrence-based — one emission
+ * per PERFORM, even if the same paragraph is called from multiple sites.
+ */
+const PERFORM_RE = /\bPERFORM\s+([A-Z0-9][A-Z0-9-]*)/gi;
+/**
+ * COPY <name> — both simple (`COPY BOOKFILE.`) and REPLACING variants
+ * (the REPLACING clause is ignored here; deep parse handles it).
+ */
+const COPY_RE = /\bCOPY\s+([A-Z0-9][A-Z0-9-]*)/gi;
+/**
+ * `EXEC CICS` opener — the closing `END-EXEC` is matched separately so we
+ * can span multiple lines. A missing `END-EXEC` emits a diagnostic.
+ */
+const EXEC_CICS_OPEN_RE = /\bEXEC\s+CICS\b/i;
+const END_EXEC_RE = /\bEND-EXEC\b/i;
+/**
+ * PERFORM modifiers that must NOT be reported as target paragraphs. COBOL
+ * allows e.g. `PERFORM VARYING I FROM 1` or `PERFORM UNTIL DONE` where the
+ * first token after PERFORM is a keyword, not a paragraph name.
+ */
+const PERFORM_KEYWORD_TARGETS = new Set([
+    "VARYING",
+    "UNTIL",
+    "TIMES",
+    "THRU",
+    "THROUGH",
+    "WITH",
+    "TEST",
+]);
+const MAX_SNIPPET_LENGTH = 120;
+const MAX_FILE_BYTES_FOR_REGEX = 5 * 1024 * 1024; // 5 MB — matches parse-worker cap.
+/**
+ * Parse a COBOL file and return the extracted element set. Pure function;
+ * safe to call from any thread / worker.
+ */
+export function parseCobolFile(path, content) {
+    const diagnostics = [];
+    // Binary / oversize early exit — cheaper than splitting into lines first.
+    if (content.length === 0) {
+        return { elements: [], copybookRefs: [], diagnostics: [] };
+    }
+    if (content.length > MAX_FILE_BYTES_FOR_REGEX) {
+        return {
+            elements: [],
+            copybookRefs: [],
+            diagnostics: [`cobol-regex: ${path} exceeds ${MAX_FILE_BYTES_FOR_REGEX}-byte cap; skipping`],
+        };
+    }
+    if (looksBinary(content)) {
+        return {
+            elements: [],
+            copybookRefs: [],
+            diagnostics: [`cobol-regex: ${path} looks binary; skipping`],
+        };
+    }
+    const lines = content.split(/\r?\n/);
+    const elements = [];
+    const copybookSet = new Set();
+    let programIdEmitted = false;
+    let cicsOpenLine;
+    let cicsOpenSnippet;
+    for (let i = 0; i < lines.length; i++) {
+        const raw = lines[i] ?? "";
+        const lineNo = i + 1;
+        // Comment lines: `*` or `/` in column 7 (0-indexed position 6). We also
+        // honor `*>` at any column (the rare free-format-style inline comment).
+        if (isCommentLine(raw))
+            continue;
+        // Strip the sequence area (columns 1-6) and indicator (column 7) before
+        // running pattern matches, so PROGRAM-ID / PERFORM / COPY matches in
+        // Area A + B are indifferent to column bookkeeping. We KEEP the raw
+        // line for the paragraph-label matcher, which cares about column
+        // alignment.
+        const stripped = stripSequenceAndIndicator(raw);
+        // --- PROGRAM-ID ---
+        // Only the first PROGRAM-ID counts (per the COBOL spec there is exactly
+        // one per file). We still warn on extras as a diagnostic.
+        if (!programIdEmitted) {
+            const m = stripped.match(PROGRAM_ID_RE);
+            if (m !== null && m[1] !== undefined) {
+                elements.push({
+                    kind: "program-id",
+                    name: m[1],
+                    filePath: path,
+                    startLine: lineNo,
+                    endLine: lineNo,
+                    language: "cobol",
+                    confidence: "heuristic",
+                    snippet: trimSnippet(raw),
+                });
+                programIdEmitted = true;
+            }
+        }
+        else if (PROGRAM_ID_RE.test(stripped)) {
+            diagnostics.push(`cobol-regex: ${path}:${lineNo}: duplicate PROGRAM-ID ignored`);
+        }
+        // --- Paragraph label (strict column-alignment matcher on the raw line) ---
+        const paraMatch = raw.match(PARAGRAPH_RE);
+        if (paraMatch !== null && paraMatch[1] !== undefined) {
+            // Skip reserved division / section headers — they also match the
+            // grammar but live in their own COBOL level. The usual suspects are
+            // "IDENTIFICATION", "ENVIRONMENT", "DATA", "PROCEDURE", "WORKING-STORAGE",
+            // "LINKAGE", "FILE", "LOCAL-STORAGE" — see ISO/IEC 1989:2014 §8.
+            if (!isReservedDivisionOrSection(paraMatch[1])) {
+                elements.push({
+                    kind: "paragraph",
+                    name: paraMatch[1],
+                    filePath: path,
+                    startLine: lineNo,
+                    endLine: lineNo,
+                    language: "cobol",
+                    confidence: "heuristic",
+                    snippet: trimSnippet(raw),
+                });
+            }
+        }
+        // --- PERFORM target(s) on this line ---
+        // Reset regex state per line because of the `g` flag.
+        PERFORM_RE.lastIndex = 0;
+        for (let m = PERFORM_RE.exec(stripped); m !== null; m = PERFORM_RE.exec(stripped)) {
+            const target = m[1];
+            if (target === undefined)
+                continue;
+            if (PERFORM_KEYWORD_TARGETS.has(target.toUpperCase()))
+                continue;
+            elements.push({
+                kind: "perform",
+                name: target,
+                filePath: path,
+                startLine: lineNo,
+                endLine: lineNo,
+                language: "cobol",
+                confidence: "heuristic",
+                snippet: trimSnippet(raw),
+            });
+        }
+        // --- COPY target(s) on this line ---
+        COPY_RE.lastIndex = 0;
+        for (let m = COPY_RE.exec(stripped); m !== null; m = COPY_RE.exec(stripped)) {
+            const target = m[1];
+            if (target === undefined)
+                continue;
+            copybookSet.add(target);
+            elements.push({
+                kind: "copy",
+                name: target,
+                filePath: path,
+                startLine: lineNo,
+                endLine: lineNo,
+                language: "cobol",
+                confidence: "heuristic",
+                snippet: trimSnippet(raw),
+            });
+        }
+        // --- EXEC CICS ... END-EXEC spans ---
+        // State machine: when we hit EXEC CICS (without an inline END-EXEC on
+        // the same line), remember the opening line and look for END-EXEC on
+        // subsequent lines. If the closing token shows up on the same line
+        // (single-line inline block), emit immediately.
+        if (cicsOpenLine === undefined) {
+            if (EXEC_CICS_OPEN_RE.test(stripped)) {
+                if (END_EXEC_RE.test(stripped)) {
+                    elements.push({
+                        kind: "cics",
+                        name: inferCicsVerb(stripped),
+                        filePath: path,
+                        startLine: lineNo,
+                        endLine: lineNo,
+                        language: "cobol",
+                        confidence: "heuristic",
+                        snippet: trimSnippet(raw),
+                    });
+                }
+                else {
+                    cicsOpenLine = lineNo;
+                    cicsOpenSnippet = trimSnippet(raw);
+                }
+            }
+        }
+        else {
+            if (END_EXEC_RE.test(stripped)) {
+                elements.push({
+                    kind: "cics",
+                    name: cicsOpenSnippet !== undefined ? inferCicsVerb(cicsOpenSnippet) : "CICS",
+                    filePath: path,
+                    startLine: cicsOpenLine,
+                    endLine: lineNo,
+                    language: "cobol",
+                    confidence: "heuristic",
+                    ...(cicsOpenSnippet !== undefined ? { snippet: cicsOpenSnippet } : {}),
+                });
+                cicsOpenLine = undefined;
+                cicsOpenSnippet = undefined;
+            }
+        }
+    }
+    // Dangling EXEC CICS block — record a diagnostic but emit nothing.
+    if (cicsOpenLine !== undefined) {
+        diagnostics.push(`cobol-regex: ${path}:${cicsOpenLine}: EXEC CICS without matching END-EXEC`);
+    }
+    const copybookRefs = [...copybookSet].sort();
+    return { elements, copybookRefs, diagnostics };
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+/**
+ * `true` if the line is a COBOL comment (col 7 = `*` or `/`) OR if it's
+ * whitespace-only (cheaper to skip than to match).
+ */
+function isCommentLine(raw) {
+    if (raw.length === 0)
+        return true;
+    if (/^\s*$/.test(raw))
+        return true;
+    // Column 7 (0-indexed 6) — guard length before peeking.
+    const indicator = raw.length >= 7 ? raw.charAt(6) : "";
+    if (indicator === "*" || indicator === "/")
+        return true;
+    // Rare inline marker used by some dialects; cheap extra check.
+    if (raw.trimStart().startsWith("*>"))
+        return true;
+    return false;
+}
+/**
+ * Strip columns 1-7 (sequence + indicator areas) from a fixed-format line.
+ * Shorter lines return empty — caller handles that gracefully.
+ */
+function stripSequenceAndIndicator(raw) {
+    if (raw.length <= 7)
+        return "";
+    return raw.slice(7);
+}
+/**
+ * COBOL reserved division + section headers that would otherwise trip the
+ * paragraph matcher. Upper-case set for O(1) lookup; caller uppercases.
+ */
+const RESERVED_AREA_A = new Set([
+    "IDENTIFICATION",
+    "ENVIRONMENT",
+    "DATA",
+    "PROCEDURE",
+    "WORKING-STORAGE",
+    "LINKAGE",
+    "FILE",
+    "LOCAL-STORAGE",
+    "CONFIGURATION",
+    "INPUT-OUTPUT",
+    "FILE-CONTROL",
+    "SPECIAL-NAMES",
+    "REPORT",
+    "SCREEN",
+    "COMMUNICATION",
+]);
+function isReservedDivisionOrSection(name) {
+    return RESERVED_AREA_A.has(name.toUpperCase());
+}
+/**
+ * Heuristic — pull the first CICS verb (`READ`, `WRITE`, `LINK`, `XCTL`,
+ * `RETURN`, `SEND`, `RECEIVE`, etc.) out of the `EXEC CICS` opener so the
+ * graph node carries a human-readable name rather than a bare `"CICS"`.
+ */
+function inferCicsVerb(stripped) {
+    const m = stripped.match(/\bEXEC\s+CICS\s+([A-Z][A-Z0-9-]*)/i);
+    if (m === null || m[1] === undefined)
+        return "CICS";
+    return `CICS ${m[1].toUpperCase()}`;
+}
+/**
+ * Peek the first ~2 KB for NUL bytes — matches the scan-phase binary
+ * heuristic. Cheaper than the 8 KB probe the scan phase uses, but fine
+ * here since the scan phase already filtered obvious binaries upstream.
+ */
+function looksBinary(content) {
+    const probeLen = Math.min(content.length, 2048);
+    for (let i = 0; i < probeLen; i++) {
+        if (content.charCodeAt(i) === 0)
+            return true;
+    }
+    return false;
+}
+function trimSnippet(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length <= MAX_SNIPPET_LENGTH)
+        return trimmed;
+    return `${trimmed.slice(0, MAX_SNIPPET_LENGTH - 3)}...`;
+}
+//# sourceMappingURL=cobol-regex.js.map

package/dist/parse/cobol-regex.js.map

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

package/dist/parse/grammar-registry.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Lazy grammar loader.
+ *
+ * Imports the native tree-sitter grammar modules on demand — the first call
+ * to `loadGrammar('python')` pulls in `tree-sitter-python`, subsequent calls
+ * hit the in-process cache. This keeps the cold-start cost of the parse
+ * subsystem low: importing `grammar-registry` alone does not load any grammar
+ * `.node` file.
+ *
+ * Each grammar package exposes its tree-sitter `Language` object differently:
+ *   - typescript: module has `.typescript` and `.tsx` properties
+ *   - javascript/python/go/go/java/rust: module IS the Language
+ *   - c-sharp: ESM default export IS the Language
+ *   - c, cpp, ruby, kotlin, swift: module IS the Language (CJS require)
+ *   - php: module has `.php` and `.php_only` — we load `.php_only` (pure PHP,
+ *     no HTML template injection; better for static analysis)
+ *   - dart: git-pinned CJS module that IS the Language
+ *
+ * This module abstracts those differences behind {@link loadGrammar}.
+ *
+ * ## Regex-provider escape hatch
+ *
+ * Some languages — COBOL is the first — have no maintained tree-sitter
+ * grammar and ship via a pure-regex extractor instead. The registry encodes
+ * that split with a {@link LanguageProviderSpec} discriminated union:
+ *
+ *   - `{ kind: "tree-sitter", package: string }` — the classic path; the
+ *     grammar package is resolved lazily from npm and hashed into the
+ *     parse-cache key via {@link getGrammarSha}.
+ *   - `{ kind: "regex" }` — the escape hatch; {@link loadGrammar} refuses
+ *     to build a `GrammarHandle`, {@link getGrammarSha} returns `null`
+ *     (disables parse-cache keying), and upstream parse-phase code is
+ *     expected to route the file through the language-specific regex
+ *     extractor instead of the worker pool.
+ *
+ * This keeps every tree-sitter consumer of the registry working unchanged
+ * while giving downstream code a typed way to detect regex-only languages.
+ */
+import type { LanguageId } from "./types.js";
+/**
+ * Provider spec for a single language. Discriminated on `kind`:
+ *   - `"tree-sitter"` — the language has an npm-published tree-sitter
+ *     grammar. `package` names the package whose `package.json` supplies
+ *     the parse-cache fingerprint.
+ *   - `"regex"` — the language has no tree-sitter grammar; the parse
+ *     pipeline routes its files through a bespoke regex extractor. No
+ *     grammar package to fingerprint, so parse-cache keying is disabled
+ *     (see {@link getGrammarSha}).
+ *
+ * Named `LanguageProviderSpec` to avoid colliding with the broader
+ * `LanguageProvider` interface in `providers/types.ts` (which covers
+ * extract-* hooks, MRO strategy, and other provider-wide behavior).
+ */
+export type LanguageProviderSpec = {
+    readonly kind: "tree-sitter";
+    readonly package: string;
+} | {
+    readonly kind: "regex";
+};
+/**
+ * Narrow a language's provider spec to its discriminated union. Exported so
+ * upstream parse-phase code can branch on the provider kind without
+ * re-implementing the registry lookup. Typical use:
+ * `getLanguageProvider(lang).kind === "regex"` to guard the regex-dispatch
+ * path.
+ */
+export declare function getLanguageProvider(lang: LanguageId): LanguageProviderSpec;
+/** `true` iff `lang` ships via the regex hot path rather than tree-sitter. */
+export declare function isRegexProviderLanguage(lang: LanguageId): boolean;
+/** Opaque wrapper holding everything a worker needs for one language. */
+export interface GrammarHandle {
+    readonly language: LanguageId;
+    /** tree-sitter Language object (opaque to callers). */
+    readonly tsLanguage: unknown;
+    /** Unified S-expression query body for this language. */
+    readonly queryText: string;
+}
+/**
+ * Load and cache the tree-sitter grammar for a language.
+ *
+ * Thread/context note: the cache is per-module-instance, so in the
+ * piscina worker model each worker has its own cache — which matches
+ * tree-sitter's thread-safety rules (one Parser per worker_thread).
+ *
+ * Regex-provider languages (see {@link isRegexProviderLanguage}) throw
+ * on entry: they have no tree-sitter grammar to load, and reaching this
+ * function means the caller skipped the `kind === "regex"` dispatch
+ * guard. That is a bug on the call site, not a runtime condition to
+ * recover from.
+ */
+export declare function loadGrammar(lang: LanguageId): Promise<GrammarHandle>;
+/**
+ * Preload a list of grammars in parallel. Useful as a warm-up hint during
+ * indexing start-up, but not required — {@link loadGrammar} is safe to call
+ * lazily during parsing.
+ */
+export declare function preloadGrammars(langs: readonly LanguageId[]): Promise<void>;
+/**
+ * Compute a stable SHA for the grammar backing `lang`. The SHA is derived
+ * from `sha256(JSON.stringify({ name, version }))` of the grammar's
+ * `package.json` — bumping the grammar version in the workspace therefore
+ * produces a new SHA, which is what the content-addressed parse cache
+ * needs in its composite key.
+ *
+ * Returns `null` when:
+ *   - the grammar package is not installed (e.g. languages whose provider
+ *     track has not landed yet), OR
+ *   - the package.json could not be read/parsed.
+ *
+ * Result is memoized per-process. Idempotent across concurrent callers.
+ */
+export declare function getGrammarSha(lang: LanguageId): Promise<string | null>;
+/** For tests: drop the cache so the next load() re-imports fresh. */
+export declare function _resetGrammarCacheForTests(): void;
+//# sourceMappingURL=grammar-registry.d.ts.map

package/dist/parse/grammar-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar-registry.d.ts","sourceRoot":"","sources":["../../src/parse/grammar-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAIH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAK7C;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAoC/B;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,UAAU,GAAG,oBAAoB,CAE1E;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAEjE;AAED,yEAAyE;AACzE,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,uDAAuD;IACvD,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAWD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAuB1E;AAED;;;;GAIG;AACH,wBAAsB,eAAe,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAEjF;AA8FD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAW5E;AA2BD,qEAAqE;AACrE,wBAAgB,0BAA0B,IAAI,IAAI,CAIjD"}