@wrongstack/tools 0.299.0 → 0.300.0

package/dist/codebase-index/languages.d.ts

@@ -22,4 +22,28 @@ export declare const INDEXABLE_EXTENSIONS: readonly string[];
 export declare function detectLang(file: string): SymbolLang | null;
 /** True when the path is eligible for the codebase index. */
 export declare function isIndexablePath(file: string): boolean;
+/**
+ * A group of {@link SymbolLang}s whose symbols may legitimately reference each
+ * other by bare name.
+ *
+ * Ref resolution matches `to_name` against `symbols.name`. Done globally that
+ * is actively wrong once more than one language is indexed: `main`, `New`,
+ * `Get`, `String`, `__init__`, `Parse` and `Config` all exist in half a dozen
+ * languages at once, so a Go call would resolve to a TypeScript declaration and
+ * draw a Code Atlas edge between files that have nothing to do with each other.
+ * Scoping resolution to a family keeps cross-language noise out while still
+ * letting genuinely mixed families (`.ts`/`.tsx` + the script block of a
+ * `.vue`/`.svelte` file, `.java`/`.kt` on the JVM) resolve into one another.
+ */
+export type LangFamily = 'js' | 'go' | 'py' | 'rs' | 'jvm' | 'dotnet' | 'c' | 'ruby' | 'php' | 'swift' | 'dart' | 'elixir' | 'haskell' | 'zig' | 'lua' | 'r' | 'shell' | 'sql' | 'data' | 'web' | 'proto' | 'graphql' | 'other';
+/**
+ * `(lang, family)` pairs, for mirroring the mapping into SQLite so ref
+ * resolution can join on it instead of expanding a family into an IN-list of
+ * placeholders on every statement.
+ */
+export declare const LANG_FAMILY_ENTRIES: ReadonlyArray<readonly [SymbolLang, LangFamily]>;
+/** Family a language resolves within. */
+export declare function languageFamily(lang: SymbolLang): LangFamily;
+/** Every language in the same resolution family as `lang`, including itself. */
+export declare function familyMembers(lang: SymbolLang): SymbolLang[];
 //# sourceMappingURL=languages.d.ts.map

package/dist/codebase-index/module-resolver.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Resolve an import specifier to the indexed file it refers to.
+ *
+ * Runs once, after indexing, filling `refs.to_file`. Doing it here rather than
+ * in the graph readers is what makes the Code Atlas language-agnostic: the
+ * readers only ever see "this ref points at that file", and never need to know
+ * that Go import paths come from `go.mod` while Python's come from a directory
+ * chain — knowledge that is not in the database and cannot be recovered from it.
+ *
+ * Resolution is best-effort by design. An unresolved specifier (a stdlib or
+ * third-party module, or an ecosystem whose layout we don't model) simply
+ * leaves `to_file` NULL, and the graph readers fall back to the ref's resolved
+ * symbol id. Guessing would draw edges that aren't there.
+ */
+import { type ProjectStructure } from './module-roots.js';
+import type { SymbolLang } from './schema.js';
+export declare class ModuleResolver {
+    private readonly structure;
+    /** Lowercased portable path → the path as indexed (case is preserved). */
+    private readonly byPath;
+    /** Lowercased portable directory → files directly inside it, as indexed. */
+    private readonly byDir;
+    /** Normalized namespace → the file declaring it (first by path, stable). */
+    private readonly byNamespace;
+    constructor(structure: ProjectStructure, files: readonly string[], namespaces?: ReadonlyArray<{
+        name: string;
+        file: string;
+    }>);
+    /**
+     * Resolve `specifier` as written in `fromFile`.
+     * Returns the indexed target path, or `undefined` when it is external or
+     * cannot be located.
+     */
+    resolve(fromFile: string, lang: SymbolLang, specifier: string): string | undefined;
+    /**
+     * Resolve a namespace specifier to the file declaring it.
+     *
+     * Tried whole first, then with the trailing segment dropped: `using Foo.Bar`
+     * names a namespace outright, while PHP's `use App\Models\User` names a
+     * *class* inside `App\Models`, so the prefix is what was declared.
+     */
+    private resolveNamespace;
+    private lookup;
+    /**
+     * Try `base` verbatim, then `base` + each extension, then each directory
+     * entry point inside `base`.
+     */
+    private lookupWithExtensions;
+    /**
+     * A representative indexed file inside `dir`, for ecosystems whose import
+     * unit is a directory rather than a file (Go packages, JVM wildcard imports).
+     *
+     * The choice is deterministic — a file named after the directory, else the
+     * first by name — so the same import always produces the same edge. Package
+     * grouping is unaffected either way: every file in the directory carries the
+     * same package label, so the package-level edge is exact regardless of which
+     * member represents it.
+     */
+    private representativeIn;
+    /** Relative specifiers, then workspace package names and their subpaths. */
+    private resolveJs;
+    /** Go import paths are absolute module paths; a package is a directory. */
+    private resolveGo;
+    /**
+     * `import a.b.c` / `from a.b import c`, plus PEP 328 relative imports whose
+     * leading dots the extractor preserves (`.sibling`, `..parent.mod`).
+     */
+    private resolvePython;
+    /** `use crate::a::b`, `use super::x`, `use self::y`, `use other_crate::z`. */
+    private resolveRust;
+    /** `com.example.Thing` and `com.example.*` against JVM source roots. */
+    private resolveJvm;
+    /** `#include "foo/bar.h"` — quoted form only; `<…>` is a system header. */
+    private resolveInclude;
+    /** `require_relative 'x'` is relative; `require 'x'` is looked up under lib/. */
+    private resolveRuby;
+}
+//# sourceMappingURL=module-resolver.d.ts.map

package/dist/codebase-index/module-roots.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Ecosystem-aware project structure detection.
+ *
+ * The Code Atlas groups files into "packages". That grouping used to be two
+ * hardcoded npm-monorepo rules (`packages/<x>` → `@wrongstack/<x>`, `apps/<x>` →
+ * `app:<x>`), which put every Go, Python, Rust or JVM file of any other repo
+ * into a single `(root)` blob with no internal structure.
+ *
+ * This module derives the grouping from the markers each ecosystem actually
+ * uses, and — importantly — at the granularity that ecosystem's developers
+ * think in:
+ *
+ * | ecosystem | marker                      | one package node is…            |
+ * |-----------|-----------------------------|---------------------------------|
+ * | npm       | `package.json`              | the package (marker directory)  |
+ * | Cargo     | `Cargo.toml`                | the crate (marker directory)    |
+ * | Go        | `go.mod`                    | **a directory** — Go's own unit |
+ * | Python    | `pyproject.toml`/`setup.py` | the dotted package (`a.b.c`)    |
+ * | Maven     | `pom.xml`                   | the project                     |
+ * | Gradle    | `build.gradle[.kts]`        | the project                     |
+ * | .NET      | `*.csproj`                  | the project                     |
+ *
+ * Detection runs once per index over the already-discovered (and already
+ * gitignore-filtered) file list, so it costs a bounded number of reads rather
+ * than a second tree walk.
+ */
+/** Package-manager ecosystem a module root belongs to. */
+export type ModuleRootKind = 'npm' | 'cargo' | 'go' | 'python' | 'maven' | 'gradle' | 'dotnet';
+export interface ModuleRoot {
+    /** Absolute directory holding the marker file, forward-slash normalized. */
+    dir: string;
+    kind: ModuleRootKind;
+    /** Human-facing grouping label, e.g. `@scope/pkg`, `crate:parser`. */
+    name: string;
+    /**
+     * Import prefix this root owns, when its ecosystem has one:
+     * the `module` line of `go.mod`, the crate name for Cargo, the distribution
+     * name for Python. `undefined` when imports are not prefixed by the root.
+     */
+    importPath?: string | undefined;
+    /**
+     * Directories imports resolve against, forward-slash normalized absolute
+     * paths. JVM layouts put this at `src/main/java`; Python projects commonly
+     * use `src/`; most ecosystems just use the root directory itself.
+     */
+    sourceRoots: string[];
+}
+/** Everything the resolver and the package labeller need, computed once. */
+export interface ProjectStructure {
+    projectRoot: string;
+    /** Sorted longest-dir-first so a nearest-ancestor lookup is a linear scan. */
+    roots: ModuleRoot[];
+}
+/** Normalize to forward slashes; every path in this module is compared this way. */
+export declare function toPortablePath(file: string): string;
+/**
+ * Detect every module root reachable from the indexed file set.
+ *
+ * Candidate directories are the ancestors of directories that actually contain
+ * files of the relevant language, so a repo with no Go code never stats a
+ * single `go.mod`.
+ */
+export declare function detectModuleRoots(projectRoot: string, files: readonly string[]): Promise<ProjectStructure>;
+/** Nearest module root that contains `file`, preferring the deepest match. */
+export declare function findOwningRoot(structure: ProjectStructure, file: string, kinds?: readonly ModuleRootKind[]): ModuleRoot | undefined;
+/**
+ * Legacy npm-monorepo fallback, kept for repos with no manifest at all (and for
+ * the existing tests that assert on it). Only consulted when marker detection
+ * finds no owning root.
+ */
+export declare function derivePackageFromLayout(filePath: string): string | undefined;
+/**
+ * Assign every indexed file its Code Atlas package label.
+ *
+ * Go is grouped per directory because that is Go's compilation unit — one node
+ * per module would collapse an entire repository into a single dot. Python is
+ * grouped by its dotted package for the same reason. Every other ecosystem is
+ * grouped by its manifest directory.
+ */
+export declare function assignPackageLabels(structure: ProjectStructure, files: readonly string[]): Map<string, string>;
+//# sourceMappingURL=module-roots.d.ts.map

package/dist/codebase-index/parser-output.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Shared decoding for the out-of-process parsers (Go's `go/ast`, Python's
+ * `ast`).
+ *
+ * Both emit `{"symbols": [...], "refs": [...]}` from a single run, so symbols
+ * and cross-references cost one child process rather than two — the same
+ * one-walk-yields-both shape the in-process TypeScript parser has.
+ *
+ * The older array-only payload (`[{name, kind, …}]`) is still accepted: parser
+ * scripts are written to a temp file that can outlive the process that wrote
+ * it, and a stale script must degrade to "symbols but no edges", never to a
+ * hard parse failure that drops the file from the index entirely.
+ */
+import type { Ref, SymbolLang } from './schema.js';
+export interface RawParsedSymbol {
+    name: string;
+    kind: string;
+    line: number;
+    col: number;
+    signature: string;
+    scope: string;
+}
+export interface ParsedParserOutput {
+    symbols: RawParsedSymbol[];
+    refs: Ref[];
+}
+/** Decode a parser child process's stdout. Never throws. */
+export declare function parseParserOutput(stdout: string, lang: SymbolLang): ParsedParserOutput;
+//# sourceMappingURL=parser-output.d.ts.map