gitnexus 1.6.12-rc.2 → 1.6.12-rc.21

package/dist/core/ingestion/call-extractors/zig-static-gating.d.ts

@@ -11,17 +11,14 @@
  * Conservative by design: we only tag an edge when we can prove the
  * gating expression evaluates to `false`.  Anything ambiguous → live.
  *
- * Scope of v1:
+ * Supported scope:
  *
  *   (a) **File-local** consts (`pub const FOO = false;`, plus const-to-const
  *       aliases up to 5 hops), built once per file by `buildZigBoolConstMap`.
- *   (b) **Cross-file** (`const cfg = @import("./cfg.zig"); if (cfg.FOO)`) is
- *       NOT resolved yet. The evaluator keeps the seam for it (`importAliases`
- *       + `lookupBoolsForPath`, consumed by the `field_expression` case), but
- *       the only caller passes an empty alias map and a lookup that always
- *       returns `undefined`, because the capture emitter runs in the parse
- *       worker and sees only the current file. Tracked in #3162. Until then
- *       every `cfg.FOO` condition folds to unknown, i.e. live.
+ *   (b) **Cross-file** direct imports (`const cfg = @import("./cfg.zig");
+ *       if (cfg.FOO)`) are enriched after per-file extraction. The workspace
+ *       caller supplies `importAliases` and `lookupBoolsForPath`; the parse
+ *       worker still uses empty/undefined inputs and remains file-local.
  *
  * Also out of scope: multi-hop member access (`cfg.sub.FOO`), re-exported
  * consts, runtime-evaluated bools (`const FOO = computeIt();`), and

package/dist/core/ingestion/content-language-classification.d.ts

@@ -0,0 +1,10 @@
+import type { SupportedLanguages } from '../../_shared/index.js';
+/**
+ * Classify files whose language cannot be determined from their extension.
+ *
+ * Source text is retained only for the duration of each individual read and
+ * classification. The returned map deliberately contains language results,
+ * not source text, so downstream phases can reuse the decision without
+ * holding every candidate header in memory or rereading it to classify again.
+ */
+export declare function classifyContentLanguages(repoPath: string, relativePaths: readonly string[]): Promise<ReadonlyMap<string, SupportedLanguages | null>>;

package/dist/core/ingestion/content-language-classification.js

@@ -0,0 +1,30 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { mapConcurrent } from '../../lib/utils.js';
+import { READ_CONCURRENCY } from './filesystem-walker.js';
+import { getLanguageForFileContent } from './languages/index.js';
+/**
+ * Classify files whose language cannot be determined from their extension.
+ *
+ * Source text is retained only for the duration of each individual read and
+ * classification. The returned map deliberately contains language results,
+ * not source text, so downstream phases can reuse the decision without
+ * holding every candidate header in memory or rereading it to classify again.
+ */
+export async function classifyContentLanguages(repoPath, relativePaths) {
+    const classifications = new Map();
+    const results = await mapConcurrent(relativePaths, async (relativePath) => {
+        const sourceText = await fs.readFile(path.join(repoPath, relativePath), 'utf-8');
+        return {
+            path: relativePath,
+            language: getLanguageForFileContent(relativePath, sourceText),
+        };
+    }, { concurrency: READ_CONCURRENCY });
+    // An unreadable file yields `undefined` from mapConcurrent. Leave it absent
+    // so the caller retains the existing filename-based fallback behavior.
+    for (const result of results) {
+        if (result !== undefined)
+            classifications.set(result.path, result.language);
+    }
+    return classifications;
+}

package/dist/core/ingestion/filesystem-walker.d.ts

@@ -7,6 +7,7 @@ export interface ScannedFile {
 export interface FilePath {
     path: string;
 }
+export declare const READ_CONCURRENCY = 32;
 export interface WalkRepositoryOptions {
     /**
      * Suppress the operator-facing large-file notice. Set by read-only callers

package/dist/core/ingestion/filesystem-walker.js

@@ -6,7 +6,7 @@ import { glob } from 'glob';
 import { createIgnoreFilter } from '../../config/ignore-service.js';
 import { mapConcurrent } from '../../lib/utils.js';
 import { logger } from '../logger.js';
-const READ_CONCURRENCY = 32;
+export const READ_CONCURRENCY = 32;
 const ANALYZE_PROGRESS_ACTIVE_ENV = 'GITNEXUS_ANALYZE_PROGRESS_ACTIVE';
 const DECLARATION_COMPANION_SUFFIXES = [
     { declaration: '.d.ts', implementations: ['.ts', '.tsx'] },

package/dist/core/ingestion/import-resolvers/node-workspace-packages.js

@@ -268,13 +268,14 @@ export async function loadNodeWorkspacePackages(repoRoot) {
     const scope = await loadWorkspaceScope(repoRoot);
     const byName = new Map();
     const queue = [{ dir: repoRoot, depth: 0 }];
+    let queueHead = 0;
     let dirsScanned = 0;
-    while (queue.length > 0) {
+    while (queueHead < queue.length) {
         if (dirsScanned >= SCAN_MAX_DIRS) {
             logger.warn(`[node] package.json scan of ${repoRoot} hit the ${SCAN_MAX_DIRS}-directory cap; workspace packages below it will not resolve`);
             break;
         }
-        const { dir, depth } = queue.shift();
+        const { dir, depth } = queue[queueHead++];
         dirsScanned++;
         let entries;
         try {

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

@@ -71,13 +71,24 @@ export interface SwiftPackageConfig {
 /** Zig package config parsed from build.zig.zon and the root build.zig */
 export interface ZigBuildZonConfig {
     /**
-     * Map of dependency name -> the raw `.path = "..."` value, exactly as
-     * written in build.zig.zon (relative to the repo root, and possibly
-     * escaping it: `../local_dep`). Consumers normalize — see
-     * `normalizeZigDepPath` below, which rejects absolute
-     * and repo-escaping values. `.url`-based deps cannot be resolved to a
-     * repo-local file (they unpack into a build cache outside the repo) and so
-     * are not included here.
+     * Map of dependency name -> the dep's directory, in one of two spellings
+     * depending on which package this config describes:
+     *
+     *   - ROOT package (`pkg === ''`): the raw `.path = "..."` value, exactly as
+     *     written in build.zig.zon (relative to the repo root, and possibly
+     *     escaping it: `../local_dep`). This is what `parseZigBuildZon` promises
+     *     and what its tests pin.
+     *   - NESTED package: repo-relative and already normalized, because a nested
+     *     package's `.path` is written relative to ITS directory and means
+     *     nothing against the repo-relative keys consumers match on
+     *     (`packages/app`'s `../core` is stored as `packages/core`). A dep
+     *     escaping the REPO root is dropped rather than stored.
+     *
+     * Either spelling is safe to hand to `normalizeZigDepPath` below — it rejects
+     * absolute and repo-escaping values and is idempotent on an already
+     * normalized one, which is what `resolveZigImportInternal` relies on.
+     * `.url`-based deps cannot be resolved to a repo-local file (they unpack into
+     * a build cache outside the repo) and so are not included here.
      */
     pathDeps: Map<string, string>;
     /**
@@ -116,6 +127,27 @@ export interface ZigBuildZonConfig {
      */
     buildModules?: readonly ZigBuildModule[];
 }
+/**
+ * One Zig build package: the directory whose `build.zig` / `build.zig.zon`
+ * declare the config, and that config with every path REPO-relative.
+ *
+ * A Zig module's import table is declared by the `build.zig` of the package it
+ * belongs to, so a repo holding several packages holds several import tables —
+ * the same shape a TypeScript monorepo has with a `tsconfig.json` per package.
+ */
+export interface ZigPackageScope {
+    /** Repo-relative directory the package governs (`''` for the repo root). */
+    readonly dir: string;
+    readonly config: ZigBuildZonConfig;
+}
+/**
+ * Every Zig build package in the repo, indexed so the nearest one to a file
+ * wins — the `TsconfigIndex` analogue, and for the same reason.
+ */
+export interface ZigWorkspaceIndex {
+    /** Deepest-first, so the first `dir` that prefixes a file path governs it. */
+    readonly packages: readonly ZigPackageScope[];
+}
 /** One build module of the root `build.zig` — see `ZigBuildZonConfig.buildModules`. */
 export interface ZigBuildModule {
     /** The `addModule("<name>", …)` name; absent for `createModule` bindings
@@ -189,14 +221,51 @@ export declare function loadSwiftPackageConfig(repoRoot: string): Promise<SwiftP
  *     string literals — a commented-out `.path` or a `}` inside a comment
  *     or string cannot declare a dep or truncate the block.
  */
-export declare function loadZigBuildConfig(repoRoot: string): Promise<ZigBuildZonConfig | null>;
+export declare function loadZigBuildConfig(repoRoot: string, packageDir?: string): Promise<ZigBuildZonConfig | null>;
 /**
- * Normalize a `.path` value from build.zig.zon into a repo-relative form.
- * Returns null for paths that escape the repo root (start with `..`) or
- * are absolute — those point to files we don't index. `.` / `./` normalize
- * to the empty string (the repo root itself). Shared with the import
- * resolver so both sides agree on which deps are in-repo.
+ * The Zig build package governing `filePath` — the nearest one at or above it.
+ *
+ * A Zig module's import table is declared by the `build.zig` of the package the
+ * file belongs to, so the nearest enclosing package is the faithful reading of
+ * `@import("name")` at that site, exactly as `tsconfigFor` reads a non-relative
+ * specifier against the nearest enclosing project.
+ *
+ * There is deliberately NO fall-through to an enclosing package when the nearest
+ * one does not bind the name. Falling through is how a vendored dependency's
+ * `@import("config")` silently resolved to the outer repo's `config` module —
+ * the same failure `loadTsconfigIndex` documents for a package whose own
+ * tsconfig declares no `baseUrl`, and the same failure the per-module import
+ * tables in `resolveZigImportInternal` already exist to prevent one level down.
+ */
+export declare function zigPackageFor(index: ZigWorkspaceIndex | null | undefined, filePath: string): ZigBuildZonConfig | null;
+/**
+ * Load every Zig build package in the repo, nearest-first.
+ *
+ * Called with no `packageDir` — which is how every call site read it before
+ * this function existed — `loadZigBuildConfig` reads the ROOT `build.zig` /
+ * `build.zig.zon` and nothing else. That is the whole configuration of a
+ * single-package repo and none of the configuration of a monorepo: a repo
+ * laying its packages out as `packages/<name>/build.zig` has no root build
+ * files at all, so the loader answers `null` and EVERY bare
+ * `@import("<module>")` in it goes unresolved — cross-file resolution silently
+ * degrades to relative imports only. Measured on a two-package fixture:
+ * `config = null`, `@import("core")` → `null`.
+ *
+ * The loader itself is not root-bound any more: this function is what supplies
+ * it a `packageDir`, one per package below.
+ *
+ * So the packages are discovered the way tsconfigs are (`findTsconfigFiles`):
+ * one bounded breadth-first walk that skips the hardcoded ignore set, then
+ * deepest-first ordering so `zigPackageFor` can take the first match.
+ *
+ * Called from `ScopeResolver.loadResolutionConfig`, which the orchestrator runs
+ * once per LANGUAGE workspace pass — so the walk happens only for repos that
+ * actually contain Zig. `loadImportConfigs`, which runs unconditionally for
+ * every repo, keeps calling `loadZigBuildConfig` for the root package alone;
+ * that is the same split TypeScript already has between the cheap
+ * `loadTsconfigPaths` and the repo-walking `loadTsconfigIndex`.
  */
+export declare function loadZigWorkspaceIndex(repoRoot: string): Promise<ZigWorkspaceIndex | null>;
 export declare function normalizeZigDepPath(depPath: string): string | null;
 /**
  * The `root_source_file` paths a `build.zig` declares, dep-relative, with the

package/dist/core/ingestion/language-config.js

@@ -3,6 +3,7 @@ import { createReadStream } from 'fs';
 import { createInterface } from 'readline';
 import path from 'path';
 import { isDev } from './utils/env.js';
+import { isHardcodedIgnoredDirectoryAtPath } from '../../config/ignore-service.js';
 import { mapConcurrent } from '../../lib/utils.js';
 import { logger } from '../logger.js';
 function normalizeComposerDirectory(baseDir, directory) {
@@ -475,10 +476,18 @@ export async function loadSwiftPackageConfig(repoRoot) {
  *     string literals — a commented-out `.path` or a `}` inside a comment
  *     or string cannot declare a dep or truncate the block.
  */
-export async function loadZigBuildConfig(repoRoot) {
+export async function loadZigBuildConfig(repoRoot, packageDir = '') {
+    // Every path this function returns is REPO-relative, because that is the
+    // keyspace `allFilePaths` uses. The parsers below answer package-relative, so
+    // a nested package rebases them through `inPackage`. For the root package
+    // (`packageDir === ''`) the prefix is empty and every value is byte-identical
+    // to what this function returned before nested packages existed.
+    const pkg = packageDir === '' ? '' : `${packageDir}/`;
+    const inPackage = (relToPackage) => `${pkg}${relToPackage}`;
+    const packageFile = (name) => path.join(repoRoot, packageDir, name);
     let config = null;
     try {
-        const raw = await fs.readFile(path.join(repoRoot, 'build.zig.zon'), 'utf-8');
+        const raw = await fs.readFile(packageFile('build.zig.zon'), 'utf-8');
         config = parseZigBuildZon(raw);
     }
     catch {
@@ -490,10 +499,11 @@ export async function loadZigBuildConfig(repoRoot) {
     let rootModules;
     let rootBuildZig = null;
     try {
-        rootBuildZig = await fs.readFile(path.join(repoRoot, 'build.zig'), 'utf-8');
+        rootBuildZig = await fs.readFile(packageFile('build.zig'), 'utf-8');
         const parsed = parseZigRootModules(rootBuildZig);
-        if (parsed.size > 0)
-            rootModules = parsed;
+        if (parsed.size > 0) {
+            rootModules = new Map(Array.from(parsed, ([name, root]) => [name, inPackage(root)]));
+        }
     }
     catch {
         // No root build.zig — nothing to declare.
@@ -502,7 +512,7 @@ export async function loadZigBuildConfig(repoRoot) {
         if (rootBuildZig === null)
             return null;
         // No zon: no path deps, so `dep.module(…)` operands resolve to nothing.
-        const buildModules = parseZigBuildModules(rootBuildZig);
+        const buildModules = rebaseZigBuildModules(parseZigBuildModules(rootBuildZig), inPackage);
         if (!rootModules && buildModules.length === 0)
             return null;
         return {
@@ -519,10 +529,25 @@ export async function loadZigBuildConfig(repoRoot) {
     // Per path dep: the modules its build.zig NAMES (`addModule("core", …)`),
     // repo-relative — what a root-build.zig `dep.module("core")` operand means.
     const depModules = new Map();
+    // A nested package's `.path` values are written relative to ITS directory, so
+    // they are rebased here and stored repo-relative; `resolveZigImportInternal`
+    // then reads them through the same `normalizeZigDepPath`, which is idempotent
+    // on an already-normalized value. A dep that escapes the REPO root (not merely
+    // the package) resolves to nothing and is dropped. The root package keeps its
+    // raw spelling, which is what `parseZigBuildZon` promises and its tests pin.
+    const pathDeps = pkg === '' ? config.pathDeps : new Map();
     for (const [depName, depPath] of config.pathDeps) {
-        const rel = normalizeZigDepPath(depPath);
+        // Asked of the value AS WRITTEN, before the package prefix goes on: an
+        // absolute `.path` points outside the repository whichever package declared
+        // it, and prefixing hides that from `normalizeZigDepPath`. See
+        // `isAbsoluteZigDepPath`.
+        if (isAbsoluteZigDepPath(depPath))
+            continue;
+        const rel = normalizeZigDepPath(`${pkg}${depPath}`);
         if (rel === null)
             continue;
+        if (pkg !== '')
+            pathDeps.set(depName, rel);
         let buildZig;
         try {
             buildZig = await fs.readFile(path.join(repoRoot, rel, 'build.zig'), 'utf-8');
@@ -542,14 +567,169 @@ export async function loadZigBuildConfig(repoRoot) {
         if (named.size > 0)
             depModules.set(depName, named);
     }
-    const buildModules = rootBuildZig === null ? [] : parseZigBuildModules(rootBuildZig, depModules);
+    const buildModules = rootBuildZig === null
+        ? []
+        : rebaseZigBuildModules(parseZigBuildModules(rootBuildZig, depModules), inPackage, depModules);
     return {
         ...config,
+        pathDeps,
         ...(moduleRoots.size > 0 ? { moduleRoots } : {}),
         ...(rootModules ? { rootModules } : {}),
         ...(buildModules.length > 0 ? { buildModules } : {}),
     };
 }
+/**
+ * Rebase a package's own build modules to repo-relative paths.
+ *
+ * `parseZigBuildModules` answers package-relative for everything it read out of
+ * the `build.zig` it was handed, with one exception: an alias resolved through
+ * `depModules` (`addImport("api", dep.module("core"))`) is already repo-relative,
+ * because `depModules` was built that way. Prefixing that a second time would
+ * point the alias at a path no file has. The already-repo-relative values are
+ * therefore identified by membership in `depModules`, not guessed at from their
+ * shape.
+ */
+function rebaseZigBuildModules(modules, inPackage, depModules) {
+    if (inPackage('') === '')
+        return [...modules];
+    const fromDep = new Set();
+    for (const named of depModules?.values() ?? [])
+        for (const root of named.values())
+            fromDep.add(root);
+    return modules.map((mod) => ({
+        ...(mod.name !== undefined ? { name: mod.name } : {}),
+        root: inPackage(mod.root),
+        imports: new Map(Array.from(mod.imports, ([alias, root]) => [
+            alias,
+            fromDep.has(root) ? root : inPackage(root),
+        ])),
+    }));
+}
+/** Bounds for the package walk, mirroring the tsconfig scan. */
+const ZIG_SCAN_MAX_DIRS = 20_000;
+const ZIG_SCAN_MAX_DEPTH = 24;
+/**
+ * The Zig build package governing `filePath` — the nearest one at or above it.
+ *
+ * A Zig module's import table is declared by the `build.zig` of the package the
+ * file belongs to, so the nearest enclosing package is the faithful reading of
+ * `@import("name")` at that site, exactly as `tsconfigFor` reads a non-relative
+ * specifier against the nearest enclosing project.
+ *
+ * There is deliberately NO fall-through to an enclosing package when the nearest
+ * one does not bind the name. Falling through is how a vendored dependency's
+ * `@import("config")` silently resolved to the outer repo's `config` module —
+ * the same failure `loadTsconfigIndex` documents for a package whose own
+ * tsconfig declares no `baseUrl`, and the same failure the per-module import
+ * tables in `resolveZigImportInternal` already exist to prevent one level down.
+ */
+export function zigPackageFor(index, filePath) {
+    if (index === null || index === undefined)
+        return null;
+    for (const scope of index.packages) {
+        if (scope.dir === '')
+            return scope.config;
+        if (filePath.startsWith(`${scope.dir}/`))
+            return scope.config;
+    }
+    return null;
+}
+/**
+ * Load every Zig build package in the repo, nearest-first.
+ *
+ * Called with no `packageDir` — which is how every call site read it before
+ * this function existed — `loadZigBuildConfig` reads the ROOT `build.zig` /
+ * `build.zig.zon` and nothing else. That is the whole configuration of a
+ * single-package repo and none of the configuration of a monorepo: a repo
+ * laying its packages out as `packages/<name>/build.zig` has no root build
+ * files at all, so the loader answers `null` and EVERY bare
+ * `@import("<module>")` in it goes unresolved — cross-file resolution silently
+ * degrades to relative imports only. Measured on a two-package fixture:
+ * `config = null`, `@import("core")` → `null`.
+ *
+ * The loader itself is not root-bound any more: this function is what supplies
+ * it a `packageDir`, one per package below.
+ *
+ * So the packages are discovered the way tsconfigs are (`findTsconfigFiles`):
+ * one bounded breadth-first walk that skips the hardcoded ignore set, then
+ * deepest-first ordering so `zigPackageFor` can take the first match.
+ *
+ * Called from `ScopeResolver.loadResolutionConfig`, which the orchestrator runs
+ * once per LANGUAGE workspace pass — so the walk happens only for repos that
+ * actually contain Zig. `loadImportConfigs`, which runs unconditionally for
+ * every repo, keeps calling `loadZigBuildConfig` for the root package alone;
+ * that is the same split TypeScript already has between the cheap
+ * `loadTsconfigPaths` and the repo-walking `loadTsconfigIndex`.
+ */
+export async function loadZigWorkspaceIndex(repoRoot) {
+    const dirs = await findZigPackageDirs(repoRoot);
+    if (dirs.length === 0)
+        return null;
+    const packages = [];
+    for (const dir of dirs) {
+        const config = await loadZigBuildConfig(repoRoot, dir);
+        // A `build.zig` that declares no module and no path dep contributes nothing
+        // a lookup could answer with. Keeping it as an empty scope would be worse
+        // than dropping it: it would shadow an enclosing package that DOES declare
+        // the name, and answer nothing in its place.
+        if (config !== null)
+            packages.push({ dir, config });
+    }
+    if (packages.length === 0)
+        return null;
+    // Deepest first, so `zigPackageFor` takes the most specific package rather
+    // than whichever the walk reached first.
+    packages.sort((a, b) => b.dir.length - a.dir.length || a.dir.localeCompare(b.dir));
+    return { packages };
+}
+/** Repo-relative directories holding a `build.zig` and/or a `build.zig.zon`. */
+async function findZigPackageDirs(repoRoot) {
+    const found = [];
+    const queue = [{ dir: repoRoot, depth: 0 }];
+    // A HEAD INDEX rather than `queue.shift()`. The queue is pushed to while it is
+    // drained, which keeps the array in a mode where `shift()` memmoves the whole
+    // remainder instead of taking V8's left-trimming fast path — so the walk is
+    // quadratic in the frontier, and `ZIG_SCAN_MAX_DIRS` is the bound on how bad
+    // that gets. Measured at that bound (20,000 dequeues): 53 ms at fan-out 4 and
+    // 81 ms at fan-out 20, against 0.8 ms here — 66-106x, paid before any config
+    // is read. Memory is unchanged: entries were already retained by the pushes,
+    // `shift()` only dropped the head.
+    let queueHead = 0;
+    let dirsScanned = 0;
+    while (queueHead < queue.length && dirsScanned < ZIG_SCAN_MAX_DIRS) {
+        const { dir, depth } = queue[queueHead++];
+        dirsScanned++;
+        let entries;
+        try {
+            entries = await fs.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        let isPackage = false;
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                const childDir = path.join(dir, entry.name);
+                if (isHardcodedIgnoredDirectoryAtPath(repoRoot, childDir))
+                    continue;
+                if (depth < ZIG_SCAN_MAX_DEPTH)
+                    queue.push({ dir: childDir, depth: depth + 1 });
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            // Either marker declares a package: a `build.zig` with no zon still names
+            // modules, and a zon with no build.zig still names path deps.
+            if (entry.name === 'build.zig' || entry.name === 'build.zig.zon')
+                isPackage = true;
+        }
+        if (isPackage) {
+            const rel = path.relative(repoRoot, dir).split(path.sep).join('/');
+            found.push(rel === '.' || rel === '' ? '' : rel);
+        }
+    }
+    return found;
+}
 /**
  * Normalize a `.path` value from build.zig.zon into a repo-relative form.
  * Returns null for paths that escape the repo root (start with `..`) or
@@ -557,13 +737,37 @@ export async function loadZigBuildConfig(repoRoot) {
  * to the empty string (the repo root itself). Shared with the import
  * resolver so both sides agree on which deps are in-repo.
  */
+/**
+ * Does this `.path` value point outside the repository BY ITS SPELLING —
+ * POSIX absolute (`/dep`), Windows drive-qualified (`C:\dep`, `C:/dep`),
+ * root-relative (`\dep`) or UNC (`\\server\share`)?
+ *
+ * Separators are normalized first so every Windows spelling is visible to the
+ * one test. Exported-in-spirit rather than inlined because it must be asked in
+ * TWO places and the two must not drift: `normalizeZigDepPath` asks it of the
+ * value it is given, and `loadZigBuildConfig` asks it of a NESTED package's
+ * value BEFORE prefixing the package directory. That second call is the whole
+ * point — prefixing turns `/dep` into `packages/app//dep`, which is relative by
+ * inspection, so the check inside `normalizeZigDepPath` no longer sees an
+ * absolute path and the empty segment is simply dropped, mapping an
+ * out-of-repo dependency onto a real in-repo directory if one happens to exist.
+ *
+ * `path.posix.join` is NOT a substitute: it strips the leading slash too
+ * (`join('packages/app/', '/dep')` is `packages/app/dep`), so it produces the
+ * same fabricated path without ever rejecting anything.
+ *
+ * A `..` prefix is deliberately NOT handled here. `../core` escapes the
+ * package but not necessarily the repo, and rebasing it is exactly what the
+ * nested-package branch exists to do; `normalizeZigDepPath` rejects the ones
+ * that still escape the ROOT after rebasing.
+ */
+function isAbsoluteZigDepPath(depPath) {
+    const normalized = depPath.replace(/\\/g, '/');
+    return normalized.startsWith('/') || /^[A-Za-z]:\//.test(normalized);
+}
 export function normalizeZigDepPath(depPath) {
-    // Normalize separators BEFORE the absolute check so every Windows spelling
-    // is visible to it: POSIX (`/x`), drive (`C:\x`, `C:/x`), root-relative
-    // (`\x` → `/x`) and UNC (`\\server\share` → `//server/share`) paths all
-    // point outside the repository.
     const normalized = depPath.replace(/\\/g, '/');
-    if (normalized.startsWith('/') || /^[A-Za-z]:\//.test(normalized))
+    if (isAbsoluteZigDepPath(depPath))
         return null;
     const parts = [];
     for (const part of normalized.split('/')) {

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

@@ -20,7 +20,7 @@ import type { VariableExtractor } from './variable-types.js';
 import type { ImportResolverFn } from './import-resolvers/types.js';
 import type { SyntaxNode } from './utils/ast-helpers.js';
 import type { CfgVisitor } from './cfg/types.js';
-import type { GraphNode, NodeLabel } from '../../_shared/index.js';
+import type { GraphNode, NodeLabel, ParameterTypeClass, RelationshipType } from '../../_shared/index.js';
 import type { ExtractedRoute } from './route-extractors/laravel.js';
 import type { SharedSpringType } from './route-extractors/spring-shared.js';
 import type { ModuleConstants, Operand, RepoConstants } from './route-extractors/constant-resolver.js';
@@ -67,6 +67,60 @@ export declare function runDefinitionPropertiesExtractor(extractor: DefinitionPr
 /** Provider metadata is additive; graph identity and source-location fields
  * supplied by the worker remain authoritative. */
 export declare function mergeCanonicalDefinitionProperties<TCanonical extends Readonly<Record<string, unknown>>>(providerProperties: Readonly<Record<string, unknown>>, canonicalProperties: TCanonical): Record<string, unknown> & TCanonical;
+export interface ProviderSemanticNode {
+    readonly id: string;
+    readonly label: NodeLabel;
+    readonly properties: {
+        readonly name: string;
+        readonly filePath: string;
+        readonly startLine: number;
+        readonly endLine: number;
+        readonly language: SupportedLanguages;
+        readonly isExported: boolean;
+        readonly qualifiedName?: string;
+        readonly parameterCount?: number;
+        readonly requiredParameterCount?: number;
+        readonly parameterTypes?: readonly string[];
+        readonly parameterTypeClasses?: readonly ParameterTypeClass[];
+        readonly returnType?: string;
+        readonly declaredType?: string;
+        readonly visibility?: string;
+        readonly isStatic?: boolean;
+        readonly isReadonly?: boolean;
+        readonly [key: string]: unknown;
+    };
+}
+export type ProviderSemanticRelationshipType = Extract<RelationshipType, 'DECLARES' | 'DEFINES' | 'HAS_METHOD' | 'HAS_PROPERTY'>;
+export interface ProviderSemanticRelationship {
+    readonly id: string;
+    readonly sourceId: string;
+    readonly targetId: string;
+    readonly type: ProviderSemanticRelationshipType;
+    readonly confidence: number;
+    readonly reason: string;
+}
+export interface ProviderSemanticSymbol {
+    readonly filePath: string;
+    readonly name: string;
+    readonly nodeId: string;
+    readonly type: NodeLabel;
+    readonly qualifiedName?: string;
+    readonly parameterCount?: number;
+    readonly requiredParameterCount?: number;
+    readonly parameterTypes?: readonly string[];
+    readonly parameterTypeClasses?: readonly ParameterTypeClass[];
+    readonly returnType?: string;
+    readonly declaredType?: string;
+    readonly ownerId?: string;
+    readonly visibility?: string;
+    readonly isStatic?: boolean;
+    readonly isReadonly?: boolean;
+}
+export interface ProviderSemanticGraph {
+    readonly nodes: readonly ProviderSemanticNode[];
+    readonly relationships: readonly ProviderSemanticRelationship[];
+    readonly symbols: readonly ProviderSemanticSymbol[];
+}
 /** Configuration for AST-based framework detection patterns. */
 export interface AstFrameworkPatternConfig {
     framework: string;
@@ -156,6 +210,27 @@ interface LanguageProviderConfig {
      * and language-specific callable compatibility.
      */
     readonly runtimeSymbolStrategy?: RuntimeSymbolStrategy;
+    /**
+     * Optional content-based language classifier. The filename detector remains
+     * the default source of truth; this hook lets a provider claim ambiguous
+     * files only when the source text carries language-specific evidence.
+     *
+     * Used for extensions shared by several languages, where mapping the suffix
+     * globally would steal files from an existing provider. Implementations must
+     * be deterministic and conservative: false negatives are acceptable, false
+     * positives change which parser and resolver consumes the file.
+     *
+     * Default: undefined (provider never overrides filename detection).
+     */
+    readonly classifyFileContent?: (filePath: string, sourceText: string) => boolean;
+    /**
+     * Cheap path-only prefilter for `classifyFileContent`. When supplied, callers
+     * can avoid loading source text for files this provider would never claim.
+     *
+     * Default: undefined (only callers that already have content invoke
+     * `classifyFileContent`).
+     */
+    readonly shouldClassifyFileContent?: (filePath: string) => boolean;
     /** Type extraction: declarations, initializers, for-loop bindings */
     readonly typeConfig: LanguageTypeConfig;
     /** Export detection: is this AST node a public/exported symbol? */
@@ -513,6 +588,18 @@ interface LanguageProviderConfig {
      * language-agnostic operand fold).
      */
     readonly foldRoutePathOperands?: (filePath: string, operands: readonly Operand[], repo: RepoConstants) => string | null;
+    /**
+     * Optional provider-owned semantic graph extraction for languages whose
+     * stable symbol identities cannot be represented by the generic query
+     * pipeline's `(label, filePath, qualifiedName)` rule.
+     *
+     * Runs in the parse worker after tree-sitter has parsed the file and after
+     * `extractParsedFile` has produced the scope-resolution artifact. The hook is
+     * deterministic and AST-based: it receives the already-parsed tree and must
+     * return plain graph nodes/relationships/symbol-table rows. Existing
+     * providers leave it undefined, preserving the generic capture path exactly.
+     */
+    readonly extractSemanticGraph?: (tree: Parser.Tree, filePath: string, sourceText: string) => ProviderSemanticGraph;
     /** Built-in/stdlib names that should be filtered from the call graph for this language.
      *  Default: undefined (no language-specific filtering). */
     readonly builtInNames?: ReadonlySet<string>;

package/dist/core/ingestion/languages/index.d.ts

@@ -20,6 +20,7 @@ export declare const providers: {
     csharp: LanguageProvider;
     c: LanguageProvider;
     cpp: LanguageProvider;
+    "objective-c": LanguageProvider;
     php: LanguageProvider;
     ruby: LanguageProvider;
     swift: LanguageProvider;
@@ -33,3 +34,9 @@ export declare function getProvider(language: SupportedLanguages): LanguageProvi
 /** Look up a language provider from a file path by extension.
  *  Returns null if the file extension is not recognized. */
 export declare function getProviderForFile(filePath: string): LanguageProvider | null;
+/** Return the provider whose content classifier confidently claims this file. */
+export declare function getProviderForFileContent(filePath: string, content: string): LanguageProvider | null;
+/** True when at least one provider wants source text before language bucketing. */
+export declare function needsContentLanguageClassification(filePath: string): boolean;
+/** Return the effective language for a file, optionally using source content. */
+export declare function getLanguageForFileContent(filePath: string, content: string): SupportedLanguages | null;