gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/core/ingestion/import-resolvers/zig.js

@@ -0,0 +1,193 @@
+/**
+ * Zig module import resolution — internal helpers.
+ *
+ * Zig imports take three shapes:
+ *   const std = @import("std");                  → stdlib, unresolvable
+ *   const builtin = @import("builtin");          → compiler builtin, unresolvable
+ *   const root = @import("root");                → user's main module, unresolvable here
+ *   const foo = @import("./foo.zig");            → relative path
+ *   const foo = @import("foo.zig");              → also relative (Zig treats unprefixed
+ *                                                  paths with a `.zig` extension as
+ *                                                  filesystem-relative to the importer)
+ *   const lp = @import("lightpanda");            → the repo's OWN module, declared by
+ *                                                  its root build.zig (`b.addModule`)
+ *   const bar = @import("bar");                  → package dep declared in build.zig.zon
+ *
+ * Bare-name resolution is handled when a parsed ZigBuildZonConfig is
+ * supplied (see `loadZigBuildConfig`). The import table of the build module
+ * the importer belongs to comes first (`buildModules` — per-module
+ * `addImport` aliases, see `zigModulesContaining`), then the root
+ * build.zig's named modules flattened repo-wide (`rootModules`, name → root
+ * file — a repo with no build.zig.zon still resolves them). `.url`-based deps unpack into a build cache outside
+ * the repo and so are returned as null; `.path`-based deps are resolved
+ * through the root the dep's own build.zig declares, then the conventional
+ * `<dep_root>/src/root.zig`, `<dep_root>/src/<name>.zig`,
+ * `<dep_root>/src/main.zig` layouts.
+ */
+import { normalizeZigDepPath, } from '../language-config.js';
+const ZIG_STDLIB_NAMES = new Set(['std', 'builtin', 'root']);
+/**
+ * The build module(s) a source file belongs to: the module whose ROOT the
+ * file is, else the module(s) whose root's directory is the deepest prefix
+ * of the file's path. Membership is not declared anywhere static — a module
+ * is its root plus whatever that root reaches through relative imports —
+ * so the directory is the proxy, and several modules may share one
+ * (`src/main.zig` executable beside `src/root.zig` library is the `zig init`
+ * layout). A root file is unambiguous by construction: it is its own module.
+ */
+function zigModulesContaining(currentFile, modules) {
+    const own = modules.filter((m) => m.root === currentFile);
+    if (own.length > 0)
+        return own;
+    let best = -1;
+    let out = [];
+    for (const mod of modules) {
+        const slash = mod.root.lastIndexOf('/');
+        const dir = slash === -1 ? '' : mod.root.slice(0, slash);
+        if (dir !== '' && !currentFile.startsWith(`${dir}/`))
+            continue;
+        if (dir.length > best) {
+            best = dir.length;
+            out = [mod];
+        }
+        else if (dir.length === best) {
+            out.push(mod);
+        }
+    }
+    return out;
+}
+/**
+ * A bare `@import("<name>")` through the containing module(s)' own import
+ * tables. `undefined` when no containing module binds the name (the caller
+ * falls back to the repo-wide tables); `null` when the containing modules
+ * DISAGREE — two same-directory modules that bind one alias to different
+ * roots — or when ANY containing module binds the alias to a root that is
+ * not indexed (a generated or skipped file), including the mixed case
+ * where a sibling module's target *is* indexed. Both are fail-closed on purpose: the module's
+ * own table is the authority for the alias, and falling through to the
+ * repo-wide map would reintroduce the first-wins answer this table exists
+ * to remove, under a name the module never meant.
+ */
+function resolveThroughBuildModules(currentFile, importPath, allFiles, modules) {
+    const targets = new Set();
+    for (const mod of zigModulesContaining(currentFile, modules)) {
+        const target = mod.imports.get(importPath);
+        if (target === undefined)
+            continue;
+        if (!allFiles.has(target))
+            return null;
+        targets.add(target);
+    }
+    if (targets.size === 0)
+        return undefined;
+    if (targets.size > 1)
+        return null;
+    return targets.values().next().value ?? null;
+}
+/** Resolve a Zig @import argument to a file path in the repository.
+ *  Returns null when the import is a stdlib / builtin / root reference,
+ *  an unresolvable build.zig.zon package dep, or genuinely unresolvable.
+ *
+ *  `buildZon` (optional) supplies the parsed `.dependencies` map from
+ *  build.zig.zon. */
+export function resolveZigImportInternal(currentFile, importPath, allFiles, buildZon) {
+    // Stdlib / compiler builtin / root — not resolvable from source files alone.
+    if (ZIG_STDLIB_NAMES.has(importPath))
+        return null;
+    // Normalize path separators for the path arithmetic below. The `.zig`
+    // extension is kept as written: the first candidate is the path as spelled
+    // and only the fallback appends `.zig` for extension-less spellings.
+    const trimmed = importPath.replace(/\\/g, '/');
+    // Absolute paths point outside the repository (Zig itself rejects
+    // `@import("/abs.zig")` as an import outside the module path). Splitting
+    // would drop the empty leading component and read `/foo.zig` as an
+    // importer-relative `foo.zig`, fabricating an in-repo edge.
+    // A drive-qualified spelling (`C:/foo.zig`, normalized from `C:\foo.zig`)
+    // is absolute too: it carries a `/`, so without this guard it would take
+    // the importer-relative branch and probe `src/C:/foo.zig`. Same test as
+    // `normalizeZigDepPath`.
+    if (trimmed.startsWith('/') || /^[A-Za-z]:\//.test(trimmed))
+        return null;
+    // Path-bearing import: resolve relative to the current file's directory.
+    // Zig allows both "./foo.zig" and "foo.zig" — both are filesystem-relative.
+    if (trimmed.endsWith('.zig') || trimmed.includes('/')) {
+        const currentDir = currentFile.split('/').slice(0, -1);
+        const parts = trimmed.split('/');
+        for (const part of parts) {
+            if (part === '' || part === '.')
+                continue;
+            if (part === '..') {
+                // Above the repository root: the import names a file outside the
+                // repo, so it must not alias a same-named root file (`../bar.zig`
+                // from `main.zig` is NOT `bar.zig`).
+                if (currentDir.length === 0)
+                    return null;
+                currentDir.pop();
+            }
+            else {
+                currentDir.push(part);
+            }
+        }
+        const candidate = currentDir.join('/');
+        if (allFiles.has(candidate))
+            return candidate;
+        if (allFiles.has(candidate + '.zig'))
+            return candidate + '.zig';
+        return null;
+    }
+    // Bare name without extension or slashes (e.g. @import("bar")).
+    if (buildZon) {
+        // First the import table of the build module the importer belongs to:
+        // an alias is scoped to the module whose `addImport` declared it, so
+        // this is the only table that can tell `app`'s `@import("config")` from
+        // `tool`'s. A disagreement between same-directory modules is `null`
+        // here and stops the chain — the repo-wide fallbacks below would only
+        // reintroduce the first-wins answer.
+        if (buildZon.buildModules !== undefined && buildZon.buildModules.length > 0) {
+            const scoped = resolveThroughBuildModules(currentFile, importPath, allFiles, buildZon.buildModules);
+            if (scoped !== undefined)
+                return scoped;
+        }
+        // The repo's own modules, as its root build.zig names them
+        // (`b.addModule("lightpanda", .{ .root_source_file = b.path("src/lightpanda.zig") })`),
+        // take precedence: that declaration is exactly what an in-repo
+        // `@import("lightpanda")` means, whatever the zon says. `std` / `builtin`
+        // / `root` were rejected above and can never be reached from here.
+        // Authoritative when it binds the name: a root that is not indexed (a
+        // generated or skipped file) is `null`, never a fall-through to a
+        // same-named zon dep — that would be a different declaration answering
+        // under the name (gitnexus-check on fe24b37f; same rule as the
+        // build-module tables above).
+        const rootModule = buildZon.rootModules?.get(importPath);
+        if (rootModule !== undefined)
+            return allFiles.has(rootModule) ? rootModule : null;
+        // Then build.zig.zon `.path` deps.
+        const depPath = buildZon.pathDeps.get(importPath);
+        if (depPath) {
+            const normalized = normalizeZigDepPath(depPath);
+            if (normalized !== null) {
+                // What the dep's own build.zig declares comes first (its
+                // `addModule` root_source_file — see `parseZigBuildModuleRoots`), then
+                // the conventional layouts: `src/root.zig` (the `zig init` library
+                // root since 0.12), `src/<name>.zig` (older name-matched convention),
+                // `src/main.zig` (executables / older inits). A dep at `.path = "."`
+                // (the repo itself) normalizes to '' and must not grow a leading slash
+                // — `allFiles` keys are repo-relative.
+                const prefix = normalized === '' ? '' : `${normalized}/`;
+                const candidates = [
+                    ...(buildZon.moduleRoots?.get(importPath) ?? []),
+                    `${prefix}src/root.zig`,
+                    `${prefix}src/${importPath}.zig`,
+                    `${prefix}src/main.zig`,
+                ];
+                for (const c of candidates) {
+                    if (allFiles.has(c))
+                        return c;
+                }
+            }
+        }
+    }
+    // Bare name with no resolution (no build.zig / build.zig.zon, .url-based dep, generated module, or
+    // unconventional layout).
+    return null;
+}

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

@@ -68,6 +68,67 @@ export interface SwiftPackageConfig {
     /** Map of target name -> source directory path (e.g., "SiuperModel" -> "Package/Sources/SiuperModel") */
     targets: Map<string, string>;
 }
+/** 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.
+     */
+    pathDeps: Map<string, string>;
+    /**
+     * Per path-dep: repo-relative root source files the dep's own `build.zig`
+     * declares (`b.addModule("name", .{ .root_source_file = b.path("src/x.zig")
+     * })`), keyed by dep name, in file order. Entries whose module name matches
+     * the dep name come first — that is the module a consumer's
+     * `@import("<dep>")` maps to under the ecosystem convention that the zon key
+     * and the module name agree. Absent (or empty) when the dep has no readable
+     * `build.zig`; the resolver then falls back to the conventional layouts.
+     */
+    moduleRoots?: Map<string, readonly string[]>;
+    /**
+     * Modules the repo's OWN root `build.zig` declares under an importable
+     * name, module name → repo-relative root source file
+     * (`b.addModule("lp", .{ .root_source_file = b.path("src/lp.zig") })`, or a
+     * `createModule` binding later named through `addImport("lp", binding)`).
+     * These are what an in-repo `@import("lp")` means — the most common shape in
+     * single-package repos, where every file imports the package's own root
+     * module by name. Independent of `build.zig.zon`: a repo with a `build.zig`
+     * and no zon still resolves them. See `parseZigRootModules`.
+     */
+    rootModules?: Map<string, string>;
+    /**
+     * Every build module the root `build.zig` declares, each with ITS OWN
+     * import table — `addModule` / `createModule` roots and the root modules of
+     * `addExecutable` / `addLibrary` / `addTest` artifacts, with the aliases
+     * their `addImport("<alias>", …)` calls and `.imports = &.{ … }` fields
+     * bind. `rootModules` flattens all of those into one first-wins map, which
+     * is wrong as soon as two modules bind one alias to different roots (an
+     * `app` and a `tool` executable that each `addImport("config", …)` their
+     * own `config.zig`): the second module's files resolved to the first
+     * module's target. The resolver walks a source file to its containing
+     * module(s) and consults their tables first — see
+     * `resolveZigImportInternal` / `parseZigBuildModules`.
+     */
+    buildModules?: readonly ZigBuildModule[];
+}
+/** One build module of the root `build.zig` — see `ZigBuildZonConfig.buildModules`. */
+export interface ZigBuildModule {
+    /** The `addModule("<name>", …)` name; absent for `createModule` bindings
+     *  and artifact root modules, which are reachable only through aliases. */
+    readonly name?: string;
+    /** Repo-relative root source file (`b.path("src/x.zig")`). */
+    readonly root: string;
+    /** Alias → repo-relative root source file, as this module's own
+     *  `addImport` calls and `.imports` field declare it. Includes aliases to
+     *  a path dep's module (`addImport("api", dep.module("core"))`) when the
+     *  dep's build.zig declares that module. */
+    readonly imports: ReadonlyMap<string, string>;
+}
 /**
  * Parse tsconfig.json to extract path aliases.
  * Tries tsconfig.json, tsconfig.app.json, tsconfig.base.json in order.
@@ -93,6 +154,119 @@ export declare function loadComposerConfig(repoRoot: string): Promise<ComposerCo
  */
 export declare function scanCSharpProject(repoRoot: string): Promise<CSharpProjectScan>;
 export declare function loadSwiftPackageConfig(repoRoot: string): Promise<SwiftPackageConfig | null>;
+/**
+ * Load the Zig build configuration a repo's `build.zig.zon` + root `build.zig`
+ * declare: `.path` deps (and the roots their own build.zig names) from the
+ * zon, and the repo's own named modules from the root build.zig. Either file
+ * may be missing — a repo with a `build.zig` but no `build.zig.zon` still
+ * resolves `@import("<own module>")`. Null only when neither contributes.
+ *
+ * `build.zig.zon` is Zig source (an anonymous-struct literal), not JSON.
+ * Rather than pull in a tree-sitter parse for one file, we use a small
+ * regex-based extractor that handles the common shapes:
+ *
+ *   .dependencies = .{
+ *       .ziggit_pkg = .{
+ *           .url = "https://...",
+ *           .hash = "1220...",
+ *       },
+ *       .local_dep = .{
+ *           .path = "../local_dep",
+ *       },
+ *   },
+ *
+ * Limitations (intentional — bail to null on anything weirder):
+ *   - Only the top-level `.dependencies = .{ ... }` block is parsed (brace
+ *     depth 1); a same-named field nested in another struct is ignored.
+ *   - Each dep entry is matched by a single shape: `.<name> = .{ ... }`
+ *     where `<name>` is a bare identifier (no `@"…"` quoted form).
+ *   - Only `.path = "..."` is captured. `.url` deps are left unresolved
+ *     because their unpacked location lives outside the repo
+ *     (.zig-cache/p/<hash>/ or ~/.cache/zig/p/<hash>/) and is therefore
+ *     not in our `allFilePaths` set.
+ *   - `//` line comments are stripped before scanning (string-aware, so a
+ *     `//` inside `.url = "https://…"` survives), and brace matching skips
+ *     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>;
+/**
+ * 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.
+ */
+export declare function normalizeZigDepPath(depPath: string): string | null;
+/**
+ * The `root_source_file` paths a `build.zig` declares, dep-relative, with the
+ * module whose `addModule("<name>", …)` name equals `preferredName` first.
+ *
+ * Reads two shapes, which between them cover `zig init` output and the
+ * common hand-written build scripts:
+ *   - `b.addModule("name", .{ .root_source_file = b.path("src/root.zig") })`
+ *   - any other `.root_source_file = b.path("…")` (exe/lib/test artifacts),
+ *     kept as unnamed fallbacks in file order.
+ * A `.zig` under `b.path` is required — `.{ .cwd_relative = … }` and
+ * `LazyPath` values computed at build time are not resolvable statically and
+ * are skipped. Duplicates collapse to the first occurrence.
+ */
+export declare function parseZigBuildModuleRoots(buildZig: string, preferredName: string): string[];
+/**
+ * The importable modules a repo's ROOT `build.zig` declares, module name →
+ * repo-relative root source file. Static scan (no execution) of two shapes:
+ *
+ *   - `b.addModule("<name>", .{ .root_source_file = b.path("<p>.zig"), … })`
+ *     names the module directly;
+ *   - `const m = b.createModule(.{ .root_source_file = b.path("<p>.zig"), … })`
+ *     (or `const m = b.addModule(…)`) bound to an identifier and later named
+ *     by `x.addImport("<name>", m)` or `.imports = &.{ .{ .name = "<name>",
+ *     .module = m } }`.
+ *
+ * Deliberately NOT resolved — they are not in-repo source files: modules whose
+ * root is not a static `b.path("….zig")` (generated `opts.createModule()` from
+ * `addOptions`, `translate_c.createModule()`, `.cwd_relative` / computed
+ * LazyPaths), `addImport("<name>", dep.module("…"))` (a `.url` / path dep,
+ * handled through the zon), and aliases whose module operand is anything but a
+ * bare identifier bound above (`config.lp_module`). Comments are stripped and
+ * string literals skipped; the first declaration of a name wins.
+ */
+export declare function parseZigRootModules(buildZig: string): Map<string, string>;
+/**
+ * Every build module the ROOT `build.zig` declares, each with its OWN import
+ * table (`ZigBuildModule`). Static scan (no execution) of:
+ *
+ *   - `b.addModule("<name>", .{ .root_source_file = b.path("<p>.zig"), … })`
+ *     and `const m = b.createModule(.{ .root_source_file = … })` — a module,
+ *     bound to the identifier a preceding `const m =` names;
+ *   - `b.addExecutable` / `addLibrary` / `addStaticLibrary` /
+ *     `addSharedLibrary` / `addTest` / `addObject(.{ .root_source_file =
+ *     b.path("<p>.zig"), … })` — an artifact whose ROOT MODULE is a module of
+ *     its own (reached as `exe.root_module.addImport(…)`), or `.root_module =
+ *     m` / `.root_module = b.createModule(…)` naming one declared inline;
+ *   - `<m>.addImport("<alias>", <operand>)`, `<exe>.root_module.addImport(…)`
+ *     and the `.imports = &.{ .{ .name = "<alias>", .module = <operand> } }`
+ *     field of a module's own arguments — an entry in THAT module's table.
+ *     The operand is a module binding (`m`) or a path dep's named module,
+ *     `dep.module("<name>")` with `const dep = b.dependency("<zon name>", …)`,
+ *     looked up in `depModules` (zon dep name → module name → repo-relative
+ *     root, from the dep's own build.zig).
+ *
+ * Why per module rather than one map (`parseZigRootModules`): an alias is
+ * scoped to the module that declares it. Two executables that each
+ * `addImport("config", …)` their own `config.zig` are the ordinary
+ * multi-target layout, and a single first-wins map sent the second module's
+ * `@import("config")` to the first module's file — a confident wrong
+ * `IMPORTS` edge and every `config.*` call behind it. Deliberately NOT
+ * resolved, as in `parseZigRootModules`: generated roots
+ * (`addOptions().createModule()`, `translate_c.createModule()`, computed
+ * LazyPaths), `.url` deps, and operands that are not a bare identifier or a
+ * `dep.module("…")` on a `b.dependency` binding. Comments stripped, string
+ * literals masked; the first binding of an identifier wins.
+ */
+export declare function parseZigBuildModules(buildZig: string, depModules?: ReadonlyMap<string, ReadonlyMap<string, string>>): ZigBuildModule[];
+/** Pure parser split out for testability. Returns null when no path-deps found. */
+export declare function parseZigBuildZon(raw: string): ZigBuildZonConfig | null;
 /**
  * Bundled language-specific configs loaded once per ingestion run — the
  * result of {@link loadImportConfigs}, and every field's type is declared
@@ -112,6 +286,9 @@ export interface ImportConfigs {
     csharpConfigs: CSharpProjectConfig[];
     /** In-repo namespace evidence gating C# suffix-fallback resolution (#1881). */
     csharpNamespaces?: CSharpNamespaceEvidence;
+    /** Zig `.path` deps from build.zig.zon. Optional so call sites that
+     *  hand-build ImportConfigs (tests) don't have to supply it. */
+    zigBuildZon?: ZigBuildZonConfig | null;
 }
 /** Load all language-specific configs once for an ingestion run. */
 export declare function loadImportConfigs(repoRoot: string): Promise<ImportConfigs>;