gitnexus 1.6.7-rc.2 → 1.6.7-rc.4

package/dist/cli/analyze.js

@@ -19,7 +19,7 @@ import { getGitRoot, hasGitDir, getDefaultBranch } from '../storage/git.js';
 import { loadAnalyzeConfig, mergeAnalyzeOptions, resolveDefaultBranch, validateBranchName, GitNexusRcError, } from './analyze-config.js';
 import { runFullAnalysis } from '../core/run-analyze.js';
 import { getMaxFileSizeBannerMessage } from '../core/ingestion/utils/max-file-size.js';
-import { warnMissingOptionalGrammars } from './optional-grammars.js';
+import { warnMissingOptionalGrammars, getOptionalGrammarExtensions } from './optional-grammars.js';
 import { glob } from 'glob';
 import fs from 'fs/promises';
 import { cliError } from './cli-message.js';
@@ -691,11 +691,13 @@ const analyzeCommandImpl = async (inputPath, cliOptions) => {
         console.log('  Note: --index-only overrides --skills; community skill files will not be written.\n');
     }
     // If the target repo contains files an optional grammar would parse but
-    // that grammar's native binding is absent, warn before analysis so users
-    // learn why those files end up unparsed instead of silently getting a
-    // degraded index.
+    // that grammar's native binding is absent (or disabled via
+    // GITNEXUS_SKIP_OPTIONAL_GRAMMARS), warn before analysis so users learn why
+    // those files end up unparsed instead of silently getting a degraded index.
+    // The extension set is derived from OPTIONAL_GRAMMARS so it can't drift.
     try {
-        const matches = await glob(['**/*.dart', '**/*.proto'], {
+        const optionalGlobs = getOptionalGrammarExtensions().map((e) => `**/*${e}`);
+        const matches = await glob(optionalGlobs, {
             cwd: repoPath,
             ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
             dot: false,

package/dist/cli/optional-grammars.d.ts

@@ -4,19 +4,33 @@
  * tree-sitter-dart, tree-sitter-proto, and tree-sitter-swift are vendored
  * under vendor/ and materialized into node_modules/ at postinstall. Dart
  * and Proto are built from source with node-gyp; Swift ships platform
- * prebuilds activated via node-gyp-build. All three can be skipped via
+ * prebuilds activated via node-gyp-build. tree-sitter-kotlin is a declared
+ * optionalDependency (not vendored). All can be skipped via
  * GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or can silently
- * soft-fail when the toolchain is missing (Dart/Proto) or no prebuild
- * matches the host platform (Swift).
+ * soft-fail when the toolchain is missing (Dart/Proto), when no prebuild
+ * matches the host platform (Swift), or when the optional install was
+ * skipped or its native build failed (Kotlin).
  *
  * Either path produces the same observable: the .node binding is absent
  * at runtime. This helper detects that condition and surfaces a single
- * stderr line per missing grammar so users learn why .dart/.proto/.swift
+ * stderr line per missing grammar so users learn why .dart/.proto/.swift/.kt
  * support is unavailable instead of silently getting a degraded index.
  */
+/**
+ * The file extensions backed by an optional grammar — the single source for
+ * the `analyze` preflight glob (so the glob can't drift from this list).
+ */
+export declare function getOptionalGrammarExtensions(): string[];
 export interface MissingGrammar {
     name: string;
     extensions: string[];
+    /**
+     * `missing` — the native binding could not be loaded (not installed / build
+     * soft-failed / no prebuild). `skipped` — the binding is fine but the user
+     * disabled it via `GITNEXUS_SKIP_OPTIONAL_GRAMMARS`. Drives the warning text
+     * so a deliberate opt-out is not told to reinstall.
+     */
+    reason: 'missing' | 'skipped';
 }
 /**
  * Returns the list of optional grammars whose native binding cannot be

package/dist/cli/optional-grammars.js

@@ -4,24 +4,51 @@
  * tree-sitter-dart, tree-sitter-proto, and tree-sitter-swift are vendored
  * under vendor/ and materialized into node_modules/ at postinstall. Dart
  * and Proto are built from source with node-gyp; Swift ships platform
- * prebuilds activated via node-gyp-build. All three can be skipped via
+ * prebuilds activated via node-gyp-build. tree-sitter-kotlin is a declared
+ * optionalDependency (not vendored). All can be skipped via
  * GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (postinstall scripts), or can silently
- * soft-fail when the toolchain is missing (Dart/Proto) or no prebuild
- * matches the host platform (Swift).
+ * soft-fail when the toolchain is missing (Dart/Proto), when no prebuild
+ * matches the host platform (Swift), or when the optional install was
+ * skipped or its native build failed (Kotlin).
  *
  * Either path produces the same observable: the .node binding is absent
  * at runtime. This helper detects that condition and surfaces a single
- * stderr line per missing grammar so users learn why .dart/.proto/.swift
+ * stderr line per missing grammar so users learn why .dart/.proto/.swift/.kt
  * support is unavailable instead of silently getting a degraded index.
  */
 import { createRequire } from 'module';
+import { SupportedLanguages } from '../_shared/index.js';
+import { isGrammarRuntimeSkipped } from '../core/tree-sitter/parser-loader.js';
 import { cliWarn } from './cli-message.js';
 const _require = createRequire(import.meta.url);
 const OPTIONAL_GRAMMARS = [
-    { name: 'tree-sitter-dart', pkg: 'tree-sitter-dart', extensions: ['.dart'] },
+    {
+        name: 'tree-sitter-dart',
+        pkg: 'tree-sitter-dart',
+        extensions: ['.dart'],
+        language: SupportedLanguages.Dart,
+    },
     { name: 'tree-sitter-proto', pkg: 'tree-sitter-proto', extensions: ['.proto'] },
-    { name: 'tree-sitter-swift', pkg: 'tree-sitter-swift', extensions: ['.swift'] },
+    {
+        name: 'tree-sitter-swift',
+        pkg: 'tree-sitter-swift',
+        extensions: ['.swift'],
+        language: SupportedLanguages.Swift,
+    },
+    {
+        name: 'tree-sitter-kotlin',
+        pkg: 'tree-sitter-kotlin',
+        extensions: ['.kt', '.kts'],
+        language: SupportedLanguages.Kotlin,
+    },
 ];
+/**
+ * The file extensions backed by an optional grammar — the single source for
+ * the `analyze` preflight glob (so the glob can't drift from this list).
+ */
+export function getOptionalGrammarExtensions() {
+    return [...new Set(OPTIONAL_GRAMMARS.flatMap((g) => g.extensions))];
+}
 /**
  * Returns the list of optional grammars whose native binding cannot be
  * loaded. Actually `require()`s the package — `require.resolve` would
@@ -41,6 +68,13 @@ const OPTIONAL_GRAMMARS = [
 export function detectMissingOptionalGrammars() {
     const missing = [];
     for (const g of OPTIONAL_GRAMMARS) {
+        // Deliberate runtime opt-out comes first: even an installed binding is
+        // treated as unavailable, with a `skipped` reason so the warning says so
+        // instead of suggesting a reinstall (#2101 review).
+        if (g.language !== undefined && isGrammarRuntimeSkipped(g.language)) {
+            missing.push({ name: g.name, extensions: g.extensions, reason: 'skipped' });
+            continue;
+        }
         try {
             _require(g.pkg);
         }
@@ -59,7 +93,7 @@ export function detectMissingOptionalGrammars() {
                 // there for tool-data stdout output).
                 cliWarn(`GitNexus: optional grammar "${g.name}" is installed but failed to load (${msg.slice(0, 200)}). ${g.extensions.join('/')} files will not be parsed.`, { grammar: g.name, extensions: g.extensions, error: msg });
             }
-            missing.push({ name: g.name, extensions: g.extensions });
+            missing.push({ name: g.name, extensions: g.extensions, reason: 'missing' });
         }
     }
     return missing;
@@ -86,6 +120,15 @@ export function warnMissingOptionalGrammars(opts) {
         if (relevantExtensions && !g.extensions.some((e) => relevantExtensions.has(e))) {
             continue;
         }
-        cliWarn(`GitNexus${ctx}: optional grammar "${g.name}" is unavailable — ${g.extensions.join('/')} files will not be parsed. Reinstall without GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (and ensure python3, make, g++) to enable.`, { grammar: g.name, extensions: g.extensions, context: opts?.context });
+        const exts = g.extensions.join('/');
+        const message = g.reason === 'skipped'
+            ? `GitNexus${ctx}: optional grammar "${g.name}" is disabled via GITNEXUS_SKIP_OPTIONAL_GRAMMARS — ${exts} files will not be parsed. Unset the variable to re-enable.`
+            : `GitNexus${ctx}: optional grammar "${g.name}" is unavailable — ${exts} files will not be parsed. Reinstall without GITNEXUS_SKIP_OPTIONAL_GRAMMARS=1 (and ensure python3, make, g++) to enable.`;
+        cliWarn(message, {
+            grammar: g.name,
+            extensions: g.extensions,
+            reason: g.reason,
+            context: opts?.context,
+        });
     }
 }

package/dist/core/ingestion/languages/dart/query.js

@@ -22,7 +22,15 @@
  *   - Parameter / return / receiver type bindings and arity metadata.
  */
 import Parser from 'tree-sitter';
-import Dart from 'tree-sitter-dart';
+import { SupportedLanguages } from '../../../../_shared/index.js';
+// `tree-sitter-dart` is an optional/vendored grammar that may be absent on a
+// default install. Loaded lazily + guarded via parser-loader rather than
+// statically imported: this module is pulled onto the main thread eagerly by
+// the scope-resolution registry and the language-provider index, so a top-level
+// `import Dart from 'tree-sitter-dart'` would throw ERR_MODULE_NOT_FOUND at
+// module-load and crash `analyze` even for repos with no Dart files (#2091,
+// #2093). The grammar is only ever needed inside the lazy getters below.
+import { getLanguageGrammar } from '../../../tree-sitter/parser-loader.js';
 const DART_SCOPE_QUERY = `
 ; ── Scopes ───────────────────────────────────────────────────────────────────
 (program) @scope.module
@@ -130,13 +138,13 @@ let _query = null;
 export function getDartParser() {
     if (_parser === null) {
         _parser = new Parser();
-        _parser.setLanguage(Dart);
+        _parser.setLanguage(getLanguageGrammar(SupportedLanguages.Dart));
     }
     return _parser;
 }
 export function getDartScopeQuery() {
     if (_query === null) {
-        _query = new Parser.Query(Dart, DART_SCOPE_QUERY);
+        _query = new Parser.Query(getLanguageGrammar(SupportedLanguages.Dart), DART_SCOPE_QUERY);
     }
     return _query;
 }

package/dist/core/ingestion/languages/kotlin/query.js

@@ -1,5 +1,13 @@
 import Parser from 'tree-sitter';
-import Kotlin from 'tree-sitter-kotlin';
+import { SupportedLanguages } from '../../../../_shared/index.js';
+// `tree-sitter-kotlin` is an optionalDependency that may be absent on a default
+// install (or fail its native build). Loaded lazily + guarded via parser-loader
+// rather than statically imported: this module is pulled onto the main thread
+// eagerly by the scope-resolution registry and the language-provider index, so
+// a top-level `import Kotlin from 'tree-sitter-kotlin'` would throw
+// ERR_MODULE_NOT_FOUND at module-load and crash `analyze` even for repos with no
+// Kotlin files (#2091, #2093). The grammar is only ever needed in the getters.
+import { getLanguageGrammar } from '../../../tree-sitter/parser-loader.js';
 const KOTLIN_SCOPE_QUERY = `
 ;; Scopes
 (source_file) @scope.module
@@ -176,13 +184,13 @@ let query = null;
 export function getKotlinParser() {
     if (parser === null) {
         parser = new Parser();
-        parser.setLanguage(Kotlin);
+        parser.setLanguage(getLanguageGrammar(SupportedLanguages.Kotlin));
     }
     return parser;
 }
 export function getKotlinScopeQuery() {
     if (query === null) {
-        query = new Parser.Query(Kotlin, KOTLIN_SCOPE_QUERY);
+        query = new Parser.Query(getLanguageGrammar(SupportedLanguages.Kotlin), KOTLIN_SCOPE_QUERY);
     }
     return query;
 }

package/dist/core/ingestion/languages/swift/query.js

@@ -42,7 +42,15 @@
  * tree-sitter init cost per file.
  */
 import Parser from 'tree-sitter';
-import Swift from 'tree-sitter-swift';
+import { SupportedLanguages } from '../../../../_shared/index.js';
+// `tree-sitter-swift` is an optional/vendored grammar that may be absent on a
+// default install. It is loaded lazily + guarded via parser-loader rather than
+// statically imported: this module is pulled onto the main thread eagerly by
+// the scope-resolution registry and the language-provider index, so a top-level
+// `import Swift from 'tree-sitter-swift'` would throw ERR_MODULE_NOT_FOUND at
+// module-load and crash `analyze` even for repos with no Swift files (#2091,
+// #2093). The grammar is only ever needed inside the lazy getters below.
+import { getLanguageGrammar } from '../../../tree-sitter/parser-loader.js';
 const SWIFT_SCOPE_QUERY = `
 ;; ── Scopes ──────────────────────────────────────────────────────────
 (source_file) @scope.module
@@ -182,13 +190,13 @@ let _query = null;
 export function getSwiftParser() {
     if (_parser === null) {
         _parser = new Parser();
-        _parser.setLanguage(Swift);
+        _parser.setLanguage(getLanguageGrammar(SupportedLanguages.Swift));
     }
     return _parser;
 }
 export function getSwiftScopeQuery() {
     if (_query === null) {
-        _query = new Parser.Query(Swift, SWIFT_SCOPE_QUERY);
+        _query = new Parser.Query(getLanguageGrammar(SupportedLanguages.Swift), SWIFT_SCOPE_QUERY);
     }
     return _query;
 }

package/dist/core/ingestion/pipeline-phases/parse-impl.js

@@ -20,9 +20,9 @@ import { fileContentHash, computeChunkHash, loadParseCacheChunk, persistParseCac
 import { clearParsedFileStore, persistParsedFileChunk, getDurableParsedFileDir, loadDurableParsedFileIndex, restoreDurableParsedFileShard, } from '../../../storage/parsedfile-store.js';
 import { processRoutesFromExtracted, buildExportedTypeMapFromGraph, } from '../call-processor.js';
 import { createSemanticModel } from '../model/index.js';
-import { getLanguageFromFilename } from '../../../_shared/index.js';
+import { getLanguageFromFilename, } from '../../../_shared/index.js';
 import { readFileContents } from '../filesystem-walker.js';
-import { isLanguageAvailable } from '../../tree-sitter/parser-loader.js';
+import { isLanguageAvailable, isGrammarRuntimeSkipped } from '../../tree-sitter/parser-loader.js';
 import { createWorkerPool, workerPoolDisabledByEnv, resolveAutoPoolSize, WorkerPoolInitializationError, WorkerPoolDisabledError, } from '../workers/worker-pool.js';
 import fs from 'node:fs';
 import path from 'node:path';
@@ -167,7 +167,15 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         }
     }
     for (const [lang, count] of skippedByLang) {
-        logger.warn(`Skipping ${count} ${lang} file(s) — ${lang} parser not available (native binding may not have built). Try: npm rebuild tree-sitter-${lang}`);
+        // Distinguish a deliberate runtime opt-out from a genuinely-missing binding
+        // so we don't tell a user who set GITNEXUS_SKIP_OPTIONAL_GRAMMARS to
+        // `npm rebuild` a grammar that built fine (#2091/#2093 review).
+        if (isGrammarRuntimeSkipped(lang)) {
+            logger.warn(`Skipping ${count} ${lang} file(s) — ${lang} parsing disabled via GITNEXUS_SKIP_OPTIONAL_GRAMMARS.`);
+        }
+        else {
+            logger.warn(`Skipping ${count} ${lang} file(s) — ${lang} parser not available (native binding may not have built). Try: npm rebuild tree-sitter-${lang}`);
+        }
     }
     // Sort parseableScanned alphabetically for stable chunk membership
     // across runs (Finding 4). Without this, filesystem-scan order can

package/dist/core/ingestion/scope-resolution/pipeline/phase.js

@@ -27,6 +27,7 @@ import { getPhaseOutput } from '../../pipeline-phases/types.js';
 import { getLanguageFromFilename } from '../../../../_shared/index.js';
 import { readFileContents } from '../../filesystem-walker.js';
 import { runScopeResolution } from './run.js';
+import { isLanguageAvailable } from '../../../tree-sitter/parser-loader.js';
 import { buildGraphNodeLookup } from '../graph-bridge/node-lookup.js';
 import { SCOPE_RESOLVERS } from './registry.js';
 import { isDev, isSemanticModelValidatorEnabled } from '../../utils/env.js';
@@ -120,6 +121,16 @@ export const scopeResolutionPhase = {
             const fileLang = getLanguageFromFilename(f.path);
             if (fileLang === null)
                 continue;
+            // Skip files whose grammar isn't available (optional grammars like
+            // swift/dart/kotlin on an install where the binding is absent or the
+            // user set GITNEXUS_SKIP_OPTIONAL_GRAMMARS). The parse phase already
+            // excluded and warned about these (parse-impl.ts); without this guard the
+            // file would fall through to the main-thread re-extract in run.ts and
+            // throw "Unsupported language" (caught, but noisy, and it needlessly
+            // loads the grammar on the main thread). `isLanguageAvailable` is
+            // memoized, so this stays O(1) per language. (#2091, #2093)
+            if (!isLanguageAvailable(fileLang))
+                continue;
             let bucket = filesByLang.get(fileLang);
             if (bucket === undefined) {
                 bucket = [];

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

@@ -18,6 +18,19 @@ import { getProvider } from '../languages/index.js';
 import { getTreeSitterBufferSize, getTreeSitterContentByteLength, TREE_SITTER_MAX_BUFFER, } from '../constants.js';
 import { ARRAY_METHOD_HOC_BLOCKLIST_SET, DEFAULT_EXPORT_IDENTIFIER_BLOCKLIST_SET, deriveDefaultExportHocName, } from '../ts-js-hoc-utils.js';
 import { parseSourceSafe } from '../../tree-sitter/safe-parse.js';
+// ── Worker grammar loading — enforcement boundary (#2091/#2093, #2101) ───────
+// The worker maintains its own grammar table (the guarded `_require`s below +
+// `languageMap`) and intentionally does NOT consult the runtime
+// `GITNEXUS_SKIP_OPTIONAL_GRAMMARS` opt-out. It does not need to: the MAIN
+// THREAD's `parseableScanned` filter (pipeline-phases/parse-impl.ts, gated on
+// `parser-loader.isLanguageAvailable`, which honors the runtime opt-out and a
+// genuinely-absent binding alike) excludes files of an unavailable/opted-out
+// language BEFORE any chunk is dispatched, so the worker never receives them.
+// That main-thread filter is the single enforcement point. Any future change
+// that dispatches files to the worker WITHOUT first passing them through
+// `isLanguageAvailable` must re-introduce the gate here. (The cleaner end-state
+// — routing this table through `parser-loader.getLanguageGrammar` so there is
+// one loader — is the deferred Tier-1 consolidation.)
 // tree-sitter-swift is an optionalDependency — may not be installed
 const _require = createRequire(import.meta.url);
 let Swift = null;

package/dist/core/tree-sitter/parser-loader.d.ts

@@ -15,6 +15,14 @@ export interface GrammarSourceDescriptor {
 export declare const listGrammarSources: () => GrammarSourceDescriptor[];
 export declare const resolveLanguageKey: (language: SupportedLanguages, filePath?: string) => string;
 export declare const isLanguageAvailable: (language: SupportedLanguages, filePath?: string) => boolean;
+/**
+ * True when `language`'s grammar is being treated as unavailable specifically
+ * because of the runtime GITNEXUS_SKIP_OPTIONAL_GRAMMARS opt-out — as opposed
+ * to a genuinely-missing/broken native binding. Lets callers surface an
+ * accurate "skipped on purpose" message instead of a spurious "npm rebuild"
+ * recovery hint. Returns false for required grammars and for an absent env.
+ */
+export declare const isGrammarRuntimeSkipped: (language: SupportedLanguages, filePath?: string) => boolean;
 export declare const getLanguageGrammar: (language: SupportedLanguages, filePath?: string) => unknown;
 export declare const loadParser: () => Promise<Parser>;
 export declare const loadLanguage: (language: SupportedLanguages, filePath?: string) => Promise<void>;

package/dist/core/tree-sitter/parser-loader.js

@@ -86,6 +86,7 @@ const SOURCES = {
     [SupportedLanguages.Swift]: {
         load: () => _require('tree-sitter-swift'),
         optional: true,
+        userSkippable: true,
         unavailableNote: 'Swift parsing disabled: vendored `tree-sitter-swift` (under ' +
             '`gitnexus/vendor/tree-sitter-swift`) failed to load. ' +
             'Likely cause: no prebuilt `.node` for this platform/architecture. ' +
@@ -94,6 +95,7 @@ const SOURCES = {
     [SupportedLanguages.Dart]: {
         load: () => _require('tree-sitter-dart'),
         optional: true,
+        userSkippable: true,
         unavailableNote: 'Dart parsing disabled: vendored `tree-sitter-dart` (under ' +
             '`gitnexus/vendor/tree-sitter-dart`) failed to load. ' +
             'Likely cause: native compile failed at install (missing python3/make/g++). ' +
@@ -102,6 +104,7 @@ const SOURCES = {
     [SupportedLanguages.Kotlin]: {
         load: () => _require('tree-sitter-kotlin'),
         optional: true,
+        userSkippable: true,
         unavailableNote: 'Kotlin parsing disabled: `tree-sitter-kotlin` is an optionalDependency ' +
             'and is not installed (or its native binding failed to build).',
     },
@@ -112,6 +115,43 @@ export const listGrammarSources = () => Object.entries(SOURCES).map(([key, sourc
 }));
 const loadCache = new Map();
 const logged = new Set();
+// Parsed form of GITNEXUS_SKIP_OPTIONAL_GRAMMARS, resolved lazily ONCE per
+// process. The env is set before analyze runs, so re-reading + re-allocating a
+// Set on every call was wasted work (and a latent trap for any future per-file
+// caller). `vi.resetModules()` gives the unit tests a fresh module — and thus a
+// fresh memo — per case, so this stays test-friendly.
+//   'all' → every userSkippable grammar; Set → only the named ids
+//   (and `tree-sitter-<id>` spellings); null → env unset/empty (nothing).
+let _skipDirective;
+const skipDirective = () => {
+    if (_skipDirective !== undefined)
+        return _skipDirective;
+    const raw = (process.env.GITNEXUS_SKIP_OPTIONAL_GRAMMARS ?? '').trim().toLowerCase();
+    if (raw === '')
+        return (_skipDirective = null);
+    if (raw === '1' || raw === 'true' || raw === 'all' || raw === '*')
+        return (_skipDirective = 'all');
+    return (_skipDirective = new Set(raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .flatMap((s) => [s, s.replace(/^tree-sitter-/, '')])));
+};
+const isRuntimeSkippedGrammar = (key, source) => {
+    // Only grammars explicitly flagged user-skippable (swift/dart/kotlin) — never
+    // required deps that use the optional machinery for ABI safety (C carries no
+    // `userSkippable`).
+    if (source.userSkippable !== true)
+        return false;
+    const directive = skipDirective();
+    if (directive === null)
+        return false;
+    if (directive === 'all')
+        return true;
+    // `key` is the SupportedLanguages value (e.g. `swift`); the directive Set
+    // already holds both the bare id and the `tree-sitter-<id>` spelling.
+    return directive.has(key) || directive.has(`tree-sitter-${key}`);
+};
 const logFailure = (key, result) => {
     if (result.ok === true)
         return;
@@ -148,6 +188,24 @@ const loadGrammar = (key) => {
         loadCache.set(key, result);
         return result;
     }
+    // Runtime opt-out: treat a user-skipped optional grammar exactly like an
+    // absent binding (non-fatal unavailable + one warning), without attempting
+    // the native load. See `isRuntimeSkippedGrammar`.
+    if (isRuntimeSkippedGrammar(key, source)) {
+        // Deliberate opt-out: emit an accurate "disabled on purpose" note rather
+        // than `source.unavailableNote` (which blames a missing/unbuilt binding and
+        // would mislead a user who set the env intentionally — #2101 review).
+        const result = {
+            ok: false,
+            error: new Error('runtime opt-out'),
+            note: `${key} parsing disabled via GITNEXUS_SKIP_OPTIONAL_GRAMMARS (unset it to re-enable).`,
+            fatal: false,
+            severity: 'warn',
+        };
+        loadCache.set(key, result);
+        logFailure(key, result);
+        return result;
+    }
     let result;
     try {
         result = { ok: true, grammar: source.load() };
@@ -168,6 +226,18 @@ const loadGrammar = (key) => {
     return result;
 };
 export const isLanguageAvailable = (language, filePath) => loadGrammar(resolveLanguageKey(language, filePath)).ok;
+/**
+ * True when `language`'s grammar is being treated as unavailable specifically
+ * because of the runtime GITNEXUS_SKIP_OPTIONAL_GRAMMARS opt-out — as opposed
+ * to a genuinely-missing/broken native binding. Lets callers surface an
+ * accurate "skipped on purpose" message instead of a spurious "npm rebuild"
+ * recovery hint. Returns false for required grammars and for an absent env.
+ */
+export const isGrammarRuntimeSkipped = (language, filePath) => {
+    const key = resolveLanguageKey(language, filePath);
+    const source = SOURCES[key];
+    return source !== undefined && isRuntimeSkippedGrammar(key, source);
+};
 export const getLanguageGrammar = (language, filePath) => {
     const key = resolveLanguageKey(language, filePath);
     const result = loadGrammar(key);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.7-rc.2",
+  "version": "1.6.7-rc.4",
   "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",