gitnexus 1.6.3-rc.11 → 1.6.3-rc.13

package/dist/core/ingestion/language-provider.d.ts

@@ -242,9 +242,15 @@ interface LanguageProviderConfig {
      * Providers that have not yet migrated continue to run through the
      * legacy DAG path (feature-flagged per `REGISTRY_PRIMARY_<LANG>`).
      *
+     * **Sync return.** Tree-sitter query execution and COBOL's regex
+     * tagger are both synchronous; no current or foreseeable provider
+     * needs async work inside this hook. The sync signature lets
+     * `parse-worker.ts` (#920) invoke it inline in its already-sync
+     * per-file loop without cascading `async` through the batch pipeline.
+     *
      * Default: undefined (language continues to use legacy DAG).
      */
-    readonly emitScopeCaptures?: (sourceText: string, filePath: string) => Promise<readonly CaptureMatch[]>;
+    readonly emitScopeCaptures?: (sourceText: string, filePath: string) => readonly CaptureMatch[];
     /**
      * Interpret a raw `@import.statement` capture group into a `ParsedImport`.
      * The central finalize algorithm resolves `ParsedImport.targetRaw` to a

package/dist/core/ingestion/parsing-processor.d.ts

@@ -1,6 +1,7 @@
 import { KnowledgeGraph } from '../graph/types.js';
 import type { SymbolTableWriter, ExtractedHeritage } from './model/index.js';
 import { ASTCache } from './ast-cache.js';
+import type { ParsedFile } from '../../_shared/index.js';
 import { WorkerPool } from './workers/worker-pool.js';
 import type { ExtractedImport, ExtractedCall, ExtractedAssignment, ExtractedRoute, ExtractedFetchCall, ExtractedDecoratorRoute, ExtractedToolDef, FileConstructorBindings, FileScopeBindings, ExtractedORMQuery } from './workers/parse-worker.js';
 export type FileProgressCallback = (current: number, total: number, filePath: string) => void;
@@ -16,6 +17,14 @@ export interface WorkerExtractedData {
     ormQueries: ExtractedORMQuery[];
     constructorBindings: FileConstructorBindings[];
     fileScopeBindings: FileScopeBindings[];
+    /**
+     * Per-file `ParsedFile` artifacts from the new scope-based resolution
+     * pipeline (RFC #909 Ring 2). Empty until a provider implements
+     * `emitScopeCaptures` — additive to the legacy DAG path. Aggregated
+     * from every worker chunk; consumed downstream by #921's
+     * finalize-orchestrator.
+     */
+    parsedFiles: ParsedFile[];
 }
 export declare const processParsing: (graph: KnowledgeGraph, files: {
     path: string;

package/dist/core/ingestion/parsing-processor.js

@@ -34,6 +34,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
             ormQueries: [],
             constructorBindings: [],
             fileScopeBindings: [],
+            parsedFiles: [],
         };
     const total = files.length;
     // Dispatch to worker pool — pool handles splitting into chunks and sub-batching
@@ -52,6 +53,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
     const allORMQueries = [];
     const allConstructorBindings = [];
     const fileScopeBindingsByFile = [];
+    const allParsedFiles = [];
     for (const result of chunkResults) {
         for (const node of result.nodes) {
             graph.addNode({
@@ -98,6 +100,13 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
         if (result.fileScopeBindings)
             for (const item of result.fileScopeBindings)
                 fileScopeBindingsByFile.push(item);
+        // RFC #909 Ring 2: aggregate per-file scope artifacts. Tolerant of
+        // workers that don't emit the field yet (older worker builds or
+        // partial rollouts), since the additive contract means undefined =
+        // "this worker produced no ParsedFiles for this chunk".
+        if (result.parsedFiles)
+            for (const item of result.parsedFiles)
+                allParsedFiles.push(item);
     }
     // Merge and log skipped languages from workers
     const skippedLanguages = new Map();
@@ -126,6 +135,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
         ormQueries: allORMQueries,
         constructorBindings: allConstructorBindings,
         fileScopeBindings: fileScopeBindingsByFile,
+        parsedFiles: allParsedFiles,
     };
 };
 // ============================================================================

package/dist/core/ingestion/registry-primary-flag.d.ts

@@ -0,0 +1,59 @@
+/**
+ * `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 declare function envVarNameFor(lang: SupportedLanguages): string;
+/**
+ * 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 declare function isRegistryPrimary(lang: SupportedLanguages): boolean;
+/**
+ * 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 declare function primaryLanguages(): ReadonlySet<SupportedLanguages>;

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/workers/parse-worker.d.ts

@@ -4,6 +4,7 @@ import { type MixedChainStep } from '../utils/call-analysis.js';
 import type { ConstructorBinding } from '../type-env.js';
 import type { NamedBinding } from '../named-bindings/types.js';
 import type { NodeLabel } from '../../../_shared/index.js';
+import type { ParsedFile } from '../../../_shared/index.js';
 interface ParsedNode {
     id: string;
     label: string;
@@ -174,6 +175,14 @@ export interface ParseWorkerResult {
     constructorBindings: FileConstructorBindings[];
     /** All-scope type bindings from TypeEnv for BindingAccumulator (includes function-local). */
     fileScopeBindings: FileScopeBindings[];
+    /**
+     * Per-file `ParsedFile` artifacts from the new scope-based resolution
+     * pipeline (RFC #909 Ring 2). Empty unless the file's provider implements
+     * `emitScopeCaptures` — default for every language today, so this is
+     * additive and leaves the legacy DAG untouched. Consumed by #921's
+     * finalize-orchestrator.
+     */
+    parsedFiles: ParsedFile[];
     skippedLanguages: Record<string, number>;
     fileCount: number;
 }

package/dist/core/ingestion/workers/parse-worker.js

@@ -43,6 +43,7 @@ import { generateId } from '../../../lib/utils.js';
 import { preprocessImportPath } from '../import-processor.js';
 import { extractVueScript, extractTemplateComponents, isVueSetupTopLevel, } from '../vue-sfc-extractor.js';
 import { buildMethodProps, arityForIdFromInfo, typeTagForId, constTagForId, buildCollisionGroups, } from '../utils/method-props.js';
+import { extractParsedFile } from '../scope-extractor-bridge.js';
 // ============================================================================
 // Worker-local parser + language map
 // ============================================================================
@@ -415,6 +416,7 @@ const processBatch = (files, onProgress) => {
         ormQueries: [],
         constructorBindings: [],
         fileScopeBindings: [],
+        parsedFiles: [],
         skippedLanguages: {},
         fileCount: 0,
     };
@@ -1017,11 +1019,25 @@ const processFileGroup = (files, language, queryString, result, onFileProcessed)
             console.warn(`Query execution failed for ${file.path}: ${err instanceof Error ? err.message : String(err)}`);
             continue;
         }
+        const provider = getProvider(language);
+        // RFC #909 Ring 2: produce a `ParsedFile` for the new scope-based
+        // resolution pipeline. No-op (returns undefined) for every language
+        // today — only fires once a provider implements `emitScopeCaptures`.
+        // Runs BEFORE legacy extraction and its result is independent: a
+        // failure here is caught inside `extractParsedFile` and does NOT
+        // affect the legacy DAG path that follows.
+        const parsedFile = extractParsedFile(provider, parseContent, file.path, (message) => {
+            if (parentPort)
+                parentPort.postMessage({ type: 'warning', message });
+            else
+                console.warn(message);
+        });
+        if (parsedFile !== undefined)
+            result.parsedFiles.push(parsedFile);
         // Pre-pass: extract heritage from query matches to build parentMap for buildTypeEnv.
         // Heritage edges (EXTENDS/IMPLEMENTS) are created by heritage-processor which runs
         // in PARALLEL with call-processor, so the graph edges don't exist when buildTypeEnv
         // runs. This pre-pass makes parent class information available for type resolution.
-        const provider = getProvider(language);
         const fileParentMap = new Map();
         if (provider.heritageExtractor) {
             for (const match of matches) {
@@ -1804,6 +1820,7 @@ let accumulated = {
     ormQueries: [],
     constructorBindings: [],
     fileScopeBindings: [],
+    parsedFiles: [],
     skippedLanguages: {},
     fileCount: 0,
 };
@@ -1830,6 +1847,7 @@ const mergeResult = (target, src) => {
     appendAll(target.ormQueries, src.ormQueries);
     appendAll(target.constructorBindings, src.constructorBindings);
     appendAll(target.fileScopeBindings, src.fileScopeBindings);
+    appendAll(target.parsedFiles, src.parsedFiles);
     for (const [lang, count] of Object.entries(src.skippedLanguages)) {
         target.skippedLanguages[lang] = (target.skippedLanguages[lang] || 0) + count;
     }
@@ -1878,6 +1896,7 @@ parentPort.on('message', (msg) => {
                 ormQueries: [],
                 constructorBindings: [],
                 fileScopeBindings: [],
+                parsedFiles: [],
                 skippedLanguages: {},
                 fileCount: 0,
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.3-rc.11",
+  "version": "1.6.3-rc.13",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",