gitnexus 1.6.3-rc.2 → 1.6.3-rc.21

package/dist/core/ingestion/registry-primary-flag.js

@@ -0,0 +1,78 @@
+/**
+ * `REGISTRY_PRIMARY_<LANG>` per-language feature flags for the scope-based
+ * resolution rollout (RFC §6.1 Ring 3; Ring 2 PKG #924).
+ *
+ * This module is the single source of truth for whether a given language
+ * has been flipped to registry-primary call resolution. When a language's
+ * flag is true, its files route through `Registry.lookup` (RFC §4) instead
+ * of the legacy call-resolution DAG; when false (the default), the legacy
+ * DAG runs unchanged.
+ *
+ * ## Contract
+ *
+ *   - Env-var name per language: `REGISTRY_PRIMARY_<UPPER(enum-value)>`.
+ *     Example: `SupportedLanguages.Python` → `REGISTRY_PRIMARY_PYTHON`;
+ *     `SupportedLanguages.CPlusPlus` (value `'cpp'`) → `REGISTRY_PRIMARY_CPP`.
+ *   - Truthy values: `'true'`, `'1'`, `'yes'` (case-insensitive,
+ *     whitespace-trimmed). Anything else — including `undefined`, empty
+ *     string, or unknown tokens — is `false`.
+ *   - No per-process caching. `process.env` is read on every call. The
+ *     flag is consulted once per file at call-resolution time, so the
+ *     overhead is negligible; skipping caching keeps test isolation
+ *     trivial (no `resetFlagCache()` coordination needed).
+ *
+ * ## Integration site
+ *
+ * `call-processor.ts` integration lands in **#921** (`finalize-orchestrator`)
+ * where the `SemanticModel` becomes accessible and `Registry.lookup` can
+ * actually be called with a populated context. This module ships the flag
+ * primitive in isolation so #921 has a clean, tested utility to consult.
+ *
+ * ## Shadow mode is orthogonal
+ *
+ * Shadow mode (`GITNEXUS_SHADOW_MODE=1`, introduced in #923) runs BOTH
+ * legacy and registry paths regardless of the per-language flag, so the
+ * parity dashboard has signal even for un-flipped languages. That logic
+ * lives in `shadow-harness.ts` (#923), not here.
+ */
+import { SupportedLanguages } from '../../_shared/index.js';
+/**
+ * Return the env-var name that controls a given language's registry-
+ * primary flag. Exported for test assertions and for the PR-labeling
+ * CI job that cross-references per-language flag changes.
+ */
+export function envVarNameFor(lang) {
+    return `REGISTRY_PRIMARY_${lang.toUpperCase()}`;
+}
+/**
+ * Whether `lang` has been flipped to registry-primary call resolution.
+ *
+ * Returns `false` by default — a language must explicitly set its env
+ * var to a truthy value to opt in. The flag is the sole control surface:
+ * flipping it requires no code change, and reverting it requires no code
+ * change.
+ */
+export function isRegistryPrimary(lang) {
+    return parseFlag(process.env[envVarNameFor(lang)]);
+}
+/**
+ * All languages whose registry-primary flag is currently on. Useful for
+ * startup-time logging + the shadow-harness dashboard, which wants to
+ * distinguish "primary: legacy" from "primary: registry" rows.
+ */
+export function primaryLanguages() {
+    const out = new Set();
+    for (const lang of Object.values(SupportedLanguages)) {
+        if (isRegistryPrimary(lang))
+            out.add(lang);
+    }
+    return out;
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+/** Accepted truthy strings (case-insensitive, trimmed). */
+const TRUTHY_VALUES = new Set(['true', '1', 'yes']);
+function parseFlag(raw) {
+    if (raw === undefined)
+        return false;
+    return TRUTHY_VALUES.has(raw.trim().toLowerCase());
+}

package/dist/core/ingestion/scope-extractor-bridge.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Bridge between a language provider's `emitScopeCaptures` hook and the
+ * `ScopeExtractor` (RFC #909 Ring 2 PKG #920).
+ *
+ * Extracted into its own module so it can be imported by test code
+ * without pulling in `parse-worker.ts` — which has a top-level
+ * `parentPort!.on('message', ...)` call that assumes a worker-thread
+ * context and throws on direct import.
+ *
+ * The bridge:
+ *
+ *   1. Short-circuits when the provider has NOT implemented
+ *      `emitScopeCaptures`. Returns `undefined`; zero work done. This is
+ *      the state of every language today — `ParsedFile` production stays
+ *      dormant until a language migrates.
+ *   2. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
+ *   3. **Swallows exceptions from either side.** A failure here returns
+ *      `undefined` and emits a warning via `onWarn`; legacy parsing on
+ *      the same file continues unaffected by the scope-extraction miss.
+ *      Scope-based resolution is the new path under construction — it
+ *      must not destabilize the legacy DAG.
+ */
+import type { ParsedFile } from '../../_shared/index.js';
+import type { LanguageProvider } from './language-provider.js';
+/** Callback used to report scope-extraction warnings to the host (worker or direct). */
+export type ScopeBridgeWarn = (message: string) => void;
+/**
+ * Produce a `ParsedFile` for the given file, or `undefined` when the
+ * provider hasn't migrated / the extractor throws. Never propagates
+ * exceptions.
+ */
+export declare function extractParsedFile(provider: LanguageProvider, sourceText: string, filePath: string, onWarn?: ScopeBridgeWarn): ParsedFile | undefined;

package/dist/core/ingestion/scope-extractor-bridge.js

@@ -0,0 +1,44 @@
+/**
+ * Bridge between a language provider's `emitScopeCaptures` hook and the
+ * `ScopeExtractor` (RFC #909 Ring 2 PKG #920).
+ *
+ * Extracted into its own module so it can be imported by test code
+ * without pulling in `parse-worker.ts` — which has a top-level
+ * `parentPort!.on('message', ...)` call that assumes a worker-thread
+ * context and throws on direct import.
+ *
+ * The bridge:
+ *
+ *   1. Short-circuits when the provider has NOT implemented
+ *      `emitScopeCaptures`. Returns `undefined`; zero work done. This is
+ *      the state of every language today — `ParsedFile` production stays
+ *      dormant until a language migrates.
+ *   2. Invokes the hook + feeds its output to `ScopeExtractor.extract`.
+ *   3. **Swallows exceptions from either side.** A failure here returns
+ *      `undefined` and emits a warning via `onWarn`; legacy parsing on
+ *      the same file continues unaffected by the scope-extraction miss.
+ *      Scope-based resolution is the new path under construction — it
+ *      must not destabilize the legacy DAG.
+ */
+import { extract as extractScope } from './scope-extractor.js';
+/**
+ * Produce a `ParsedFile` for the given file, or `undefined` when the
+ * provider hasn't migrated / the extractor throws. Never propagates
+ * exceptions.
+ */
+export function extractParsedFile(provider, sourceText, filePath, onWarn) {
+    if (provider.emitScopeCaptures === undefined)
+        return undefined;
+    try {
+        const captures = provider.emitScopeCaptures(sourceText, filePath);
+        return extractScope(captures, filePath, provider);
+    }
+    catch (err) {
+        const message = `scope extraction failed for ${filePath}: ${err instanceof Error ? err.message : String(err)}`;
+        if (onWarn !== undefined)
+            onWarn(message);
+        else
+            console.warn(message);
+        return undefined;
+    }
+}

package/dist/core/ingestion/scope-extractor.d.ts

@@ -0,0 +1,87 @@
+/**
+ * `ScopeExtractor` — the central, source-agnostic driver that turns a
+ * language provider's `CaptureMatch[]` into a `ParsedFile`
+ * (RFC §5.3 + §3.2 Phase 1; Ring 2 PKG #919).
+ *
+ * Exactly one entry point: `extract(matches, filePath, provider) → ParsedFile`.
+ * Runs a five-pass pipeline over the matches. Each pass is internal; the
+ * public contract is the output `ParsedFile`.
+ *
+ * ## Design principles
+ *
+ *   - **Source-agnostic.** Consumes `CaptureMatch[]` from providers;
+ *     doesn't know whether they came from tree-sitter queries or COBOL's
+ *     regex tagger. No `Tree` / `SyntaxNode` types leak into this file.
+ *   - **One AST walk per language.** Providers do the AST walk inside
+ *     their `emitScopeCaptures` hook; this driver does zero further
+ *     traversal — it consumes captures only.
+ *   - **Pure-ish.** The extractor itself is pure (same matches →
+ *     same ParsedFile) when providers are pure. No side effects, no I/O.
+ *   - **Centralized invariant enforcement.** Structural invariants on the
+ *     scope tree (non-module has parent; parent contains child; siblings
+ *     don't overlap) are enforced by `buildScopeTree` from Ring 2 SHARED
+ *     (#912). Malformed inputs throw `ScopeTreeInvariantError`.
+ *
+ * ## The five passes
+ *
+ *   1. **Build scope tree.** Walk `@scope.*` matches. For each, consult
+ *      `provider.shouldCreateScope` (default true) and
+ *      `provider.resolveScopeKind` (default: suffix of the capture name).
+ *      Derive parent by lexical-range containment. Hand the resulting
+ *      `Scope[]` to `buildScopeTree` for validation.
+ *   2. **Attach declarations + local bindings.** Walk `@declaration.*`
+ *      matches. For each, build a `SymbolDefinition` and attach it to
+ *      `provider.bindingScopeFor` (default: innermost containing scope)
+ *      as `ownedDefs` + a local `BindingRef { origin: 'local' }`.
+ *   3. **Collect raw imports.** Walk `@import.*` matches. Call
+ *      `provider.interpretImport` per match; attach the returned
+ *      `ParsedImport` to the ParsedFile (not to any `Scope` — finalize
+ *      reconstructs the owning scope via `provider.importOwningScope`
+ *      during Phase 2).
+ *   4. **Collect type bindings.** Walk `@type-binding.*` matches. Call
+ *      `provider.interpretTypeBinding` per match. Attach the resulting
+ *      `TypeRef` to the innermost containing scope's `typeBindings`
+ *      (or override via `provider.bindingScopeFor` if set).
+ *   5. **Collect reference sites.** Walk `@reference.*` matches. Emit
+ *      one `ReferenceSite` per match. Classify call form via
+ *      `provider.classifyCallForm` (default: the capture's sub-tag if
+ *      present; else `'free'`).
+ *
+ * ## What gets attached where
+ *
+ *   - `Scope.bindings`     — **local bindings only** at this stage (Pass 2).
+ *                            Finalize (#915) merges imports/wildcards on top.
+ *   - `Scope.ownedDefs`    — declarations structurally owned by this scope.
+ *   - `Scope.typeBindings` — local type facts (parameter annotations, `self`).
+ *   - `Scope.imports`      — empty here. Populated by the finalize algorithm
+ *                            when it resolves `ParsedImport.targetRaw`.
+ *   - `ParsedFile.parsedImports` — every raw import in this file.
+ *   - `ParsedFile.localDefs`     — flattened union of `Scope.ownedDefs`.
+ *   - `ParsedFile.referenceSites` — pre-resolution usage facts.
+ */
+import type { CaptureMatch, ParsedFile } from '../../_shared/index.js';
+import type { LanguageProvider } from './language-provider.js';
+/**
+ * The subset of `LanguageProvider` hooks that `extract()` reads. Declared
+ * as its own type so:
+ *
+ *   - Tests can implement just these six hooks without faking the whole
+ *     `LanguageProvider` interface (which is ~40 fields including the
+ *     legacy-DAG surface).
+ *   - The extractor's dependency contract stays explicit — adding a new
+ *     hook read requires updating this type.
+ *
+ * Real callers pass a full `LanguageProvider` — structural typing makes it
+ * a `ScopeExtractorHooks` for free.
+ */
+export type ScopeExtractorHooks = Pick<LanguageProvider, 'shouldCreateScope' | 'resolveScopeKind' | 'bindingScopeFor' | 'interpretImport' | 'interpretTypeBinding' | 'classifyCallForm'>;
+/**
+ * Drive the five extraction passes and return a `ParsedFile`.
+ *
+ * Throws `ScopeTreeInvariantError` (from #912) when the provider emits
+ * captures that violate structural scope invariants. The error surfaces
+ * upward rather than being silently corrected — a malformed capture set
+ * is a bug in the provider's `emitScopeCaptures`, not a data condition
+ * to tolerate.
+ */
+export declare function extract(matches: readonly CaptureMatch[], filePath: string, provider: ScopeExtractorHooks): ParsedFile;