dsh-plugin-codegraph-tree-sitter 0.1.0

package/lib/gitignore.js

@@ -0,0 +1,107 @@
+/**
+ * A deliberately small subset of `.gitignore` pattern syntax, just enough to keep the indexer's
+ * exclusion set in step with what a project's own build tooling already hides from version control —
+ * without a new dependency on a full gitignore-matching library.
+ *
+ * Only the project root's `.gitignore` is read; per-directory `.gitignore` files nested below it are
+ * not consulted, matching the walk's own root-relative worldview.
+ *
+ * Supported:
+ *  - Blank lines and lines starting with `#` are comments.
+ *  - A leading `!` negates: a later matching rule re-includes a path an earlier rule excluded.
+ *  - A pattern containing `/` (leading or internal) is anchored to the project root; one with no `/`
+ *    at all matches at any depth, by basename.
+ *  - A trailing `/` restricts the rule to directories.
+ *  - `*` matches any run of characters other than `/`, within one path segment.
+ *
+ * Not supported. Each is treated as a literal character (or, for `**`, as two literal `*` globs),
+ * which only ever makes a pattern *more* specific than a real gitignore would — it degrades toward
+ * "excludes nothing extra" rather than toward "excludes too much":
+ *  - `**` (explicit multi-segment wildcards — plain unanchored patterns already cross depths)
+ *  - character classes (`[abc]`), `?`, and backslash escapes
+ *  - git's rule that a negation cannot resurrect a path inside an already-excluded directory: here,
+ *    a negation re-includes whatever it matches regardless of ancestor exclusions.
+ * @module dsh-plugin-codegraph-tree-sitter/gitignore
+ */
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+/** Regex-escape everything except the one wildcard this subset understands. */
+function toRegExp(pattern, anchored) {
+    const escaped = pattern
+        .split('*')
+        .map(part => part.replace(/[.+^${}()|[\]\\]/g, '\\$&'))
+        .join('[^/]*');
+    // Anchored: the pattern must match the whole relative path. Unanchored: it must match the whole
+    // final path segment, at any depth — either the entire path (top level) or whatever follows the
+    // last `/` before it.
+    const body = anchored ? escaped : `(?:^|.*/)${escaped}`;
+    return new RegExp(`^${body}$`);
+}
+/**
+ * Parse `.gitignore` file content into an ordered rule list.
+ * @param content - the raw file text.
+ * @returns rules in file order. Matching must apply them in order and keep the last match, per
+ *   git's own precedence — a later line overrides an earlier one it conflicts with.
+ */
+export function parseGitignore(content) {
+    const rules = [];
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.replace(/\r$/, '');
+        if (line.trim() === '' || line.startsWith('#'))
+            continue;
+        let pattern = line;
+        let negated = false;
+        if (pattern.startsWith('!')) {
+            negated = true;
+            pattern = pattern.slice(1);
+        }
+        let directoryOnly = false;
+        if (pattern.endsWith('/')) {
+            directoryOnly = true;
+            pattern = pattern.slice(0, -1);
+        }
+        const anchored = pattern.includes('/');
+        if (pattern.startsWith('/'))
+            pattern = pattern.slice(1);
+        // A bare "/", "!", or "!/" names nothing once stripped — skip rather than build a rule that
+        // would match every path.
+        if (pattern === '')
+            continue;
+        rules.push({ pattern: toRegExp(pattern, anchored), negated, directoryOnly });
+    }
+    return rules;
+}
+/**
+ * Whether `relativePath` should be excluded per `rules`. Later rules win over earlier ones, matching
+ * git's own precedence: the loop keeps applying matches rather than stopping at the first one.
+ * @param rules - parsed rules, in file order.
+ * @param relativePath - the path to test, relative to the project root, `/`-separated.
+ * @param isDirectory - whether the path names a directory; directory-only rules skip files.
+ * @returns whether the path is excluded.
+ */
+export function matchesGitignore(rules, relativePath, isDirectory) {
+    let excluded = false;
+    for (const rule of rules) {
+        if (rule.directoryOnly && !isDirectory)
+            continue;
+        if (!rule.pattern.test(relativePath))
+            continue;
+        excluded = !rule.negated;
+    }
+    return excluded;
+}
+/**
+ * Load and parse `<projectRoot>/.gitignore`.
+ * @param projectRoot - absolute path of the project root.
+ * @returns the parsed rules, or an empty array when there is no root `.gitignore` — a missing file
+ *   means "nothing extra to exclude," not a failure, so this never throws.
+ */
+export async function loadGitignore(projectRoot) {
+    try {
+        return parseGitignore(await readFile(join(projectRoot, '.gitignore'), 'utf8'));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=gitignore.js.map

package/lib/grammar.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Lazy, process-cached grammar loading. `Parser.init()` boots one Emscripten runtime shared by every
+ * grammar; each `Language` loads from its `tree-sitter-wasms` binary only the first time a matching
+ * file is seen.
+ *
+ * Loading is lazy and per-language for a concrete reason: the reference implementation this package
+ * targets loads its full grammar set eagerly and must run its bundled Node with `--liftoff-only` to
+ * survive V8 running out of WASM code space. This harness cannot pass that flag to the Node process
+ * that runs it, so it must never load a grammar the workspace does not use.
+ * @module dsh-plugin-codegraph-tree-sitter/grammar
+ */
+import { Language, Parser } from 'web-tree-sitter';
+import type { LanguageSpec } from './languages.ts';
+/**
+ * The parsed grammar for one language, loading and caching it on first use.
+ * @param spec - the language's extraction table entry, naming its wasm file.
+ * @returns the loaded grammar, shared by every caller for the process lifetime.
+ */
+export declare function loadGrammar(spec: LanguageSpec): Promise<Language>;
+/**
+ * A parser configured for one language, built fresh per call because `Parser` carries mutable parse
+ * state a concurrent caller must not share.
+ * @param spec - the language's extraction table entry.
+ * @returns a parser ready to parse source in this language.
+ */
+export declare function createParser(spec: LanguageSpec): Promise<Parser>;
+//# sourceMappingURL=grammar.d.ts.map

package/lib/grammar.js

@@ -0,0 +1,51 @@
+/**
+ * Lazy, process-cached grammar loading. `Parser.init()` boots one Emscripten runtime shared by every
+ * grammar; each `Language` loads from its `tree-sitter-wasms` binary only the first time a matching
+ * file is seen.
+ *
+ * Loading is lazy and per-language for a concrete reason: the reference implementation this package
+ * targets loads its full grammar set eagerly and must run its bundled Node with `--liftoff-only` to
+ * survive V8 running out of WASM code space. This harness cannot pass that flag to the Node process
+ * that runs it, so it must never load a grammar the workspace does not use.
+ * @module dsh-plugin-codegraph-tree-sitter/grammar
+ */
+import { createRequire } from 'node:module';
+import { Language, Parser } from 'web-tree-sitter';
+const require = createRequire(import.meta.url);
+let initialized;
+/** Boot the shared Emscripten runtime exactly once per process. */
+function ensureInitialized() {
+    initialized ??= Parser.init();
+    return initialized;
+}
+const loaded = new Map();
+/**
+ * The parsed grammar for one language, loading and caching it on first use.
+ * @param spec - the language's extraction table entry, naming its wasm file.
+ * @returns the loaded grammar, shared by every caller for the process lifetime.
+ */
+export async function loadGrammar(spec) {
+    let pending = loaded.get(spec.language);
+    if (pending === undefined) {
+        pending = (async () => {
+            await ensureInitialized();
+            const wasmPath = require.resolve(`tree-sitter-wasms/out/${spec.wasmFile}`);
+            return Language.load(wasmPath);
+        })();
+        loaded.set(spec.language, pending);
+    }
+    return pending;
+}
+/**
+ * A parser configured for one language, built fresh per call because `Parser` carries mutable parse
+ * state a concurrent caller must not share.
+ * @param spec - the language's extraction table entry.
+ * @returns a parser ready to parse source in this language.
+ */
+export async function createParser(spec) {
+    const language = await loadGrammar(spec);
+    const parser = new Parser();
+    parser.setLanguage(language);
+    return parser;
+}
+//# sourceMappingURL=grammar.js.map

package/lib/index.d.ts

@@ -0,0 +1,112 @@
+/**
+ * Self-built code-graph indexer for `ctx.codegraph`. Parses a workspace with `web-tree-sitter` and
+ * `tree-sitter-wasms` and writes schema version 4 to `<projectRoot>/.codegraph/codegraph.db` — the
+ * same path and format `dsh-plugin-codegraph-sqlite` reads and the external `codegraph` CLI
+ * writes, so a workspace this package indexes becomes queryable through the existing store with no
+ * second graph format to disagree with the first.
+ *
+ * Registers **only an indexer**, never a store: `ctx.codegraph.index()` runs this package, and
+ * `ctx.codegraph.query()` is answered by whichever store claims the root afterward. Indexing never
+ * runs implicitly from a query — it is a caller-initiated, potentially multi-minute operation, kept
+ * out of the seam's read-only query path on purpose.
+ *
+ * Namespace plugin (named exports, no default export). Grammars load lazily, one per language, on
+ * first sight of a matching file, and stay cached for the process — never eagerly for every grammar
+ * this package ships with.
+ * @module dsh-plugin-codegraph-tree-sitter
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { LANGUAGE_TABLE, languageFor } from './languages.ts';
+export type { DefinitionRule, ImportRule, LanguageSpec } from './languages.ts';
+export { extractFile } from './extract.ts';
+export type { FileExtraction, RawCall, RawDefinition, RawImport } from './extract.ts';
+export { loadGitignore, matchesGitignore, parseGitignore } from './gitignore.ts';
+export type { GitignoreRule } from './gitignore.ts';
+export { resolveWorkspace } from './resolve.ts';
+export type { ExtractedFile, GraphEdge, GraphNode, ResolvedGraph, UnresolvedRef } from './resolve.ts';
+export { SCHEMA_VERSION, writeGraph } from './schema.ts';
+export { isExcluded, walkAndExtract } from './walk.ts';
+export type { WalkConfig, WalkResult } from './walk.ts';
+export { createWatcher, nodeWatch } from './watcher.ts';
+export type { DegradeReason, WatchConfig, WatchHandle, WatchPrimitive, Watcher } from './watcher.ts';
+export { decideWatch, readProcVersion } from './watch-policy.ts';
+export type { WatchDecision, WatchPolicyInput } from './watch-policy.ts';
+export { detectWorktree, execGit } from './worktree.ts';
+export type { GitExec, WorktreeInfo } from './worktree.ts';
+export { HOOK_MARKER_BEGIN, HOOK_MARKER_END, installGitHooks, uninstallGitHooks } from './git-hooks.ts';
+export type { GitHooksOptions } from './git-hooks.ts';
+/** Cordis plugin name for loader diagnostics. */
+export declare const name = "codegraph-tree-sitter";
+/** Services required by this plugin. */
+export declare const inject: string[];
+/** Path of the on-disk graph this package writes, relative to a project root. */
+export declare const DATABASE_RELATIVE_PATH = ".codegraph/codegraph.db";
+/** Default branded identity this indexer reserves on the seam. */
+export declare const DEFAULT_INDEXER_ID = "codegraph-tree-sitter";
+/** Directory segments never descended into by default. */
+export declare const DEFAULT_EXCLUDE: string[];
+/** Default ceiling on a single file's size before it is skipped. */
+export declare const DEFAULT_MAX_FILE_BYTES = 2000000;
+/** Default ceiling on how many files one run indexes. */
+export declare const DEFAULT_MAX_FILES = 50000;
+/** Default number of files parsed concurrently. */
+export declare const DEFAULT_CONCURRENCY = 4;
+/** Default quiet period after the last change before a watch-triggered refresh runs. */
+export declare const DEFAULT_WATCH_DEBOUNCE_MS = 2000;
+/** Default cap on directories watched individually, on platforms without a recursive `fs.watch`. */
+export declare const DEFAULT_MAX_WATCHED_DIRECTORIES = 4000;
+/** Plugin configuration: the indexer's identity and every deployment-varying bound on a run. */
+export interface Config {
+    /**
+     * Branded identity to reserve on `ctx.codegraph`. Give each instance its own id when mounting more
+     * than one, so a duplicate registration fails at load instead of shadowing the first indexer.
+     */
+    indexerId?: string;
+    /** Restrict indexing to these seam language labels when set (default: every grammar this package ships). */
+    languages?: string[];
+    /** Directory segment names never descended into (default: node_modules, dist, build, coverage, .git). */
+    exclude?: string[];
+    /**
+     * Also exclude whatever the project root's `.gitignore` names, unioned with `exclude` (default
+     * true). Build tooling routinely writes compiled output to a gitignored directory outside the
+     * default exclude list (`lib`, `out`, ...); indexing that output alongside its own source hands the
+     * resolver two same-named declarations of one symbol and makes "the one unique workspace-wide name
+     * wins" pick between them arbitrarily. Only a practical subset of gitignore syntax is understood —
+     * see `./gitignore.ts`. A project with no root `.gitignore` is unaffected either way.
+     */
+    respectGitignore?: boolean;
+    /** Files larger than this are skipped and counted in the report, never parsed (default 2000000). */
+    maxFileBytes?: number;
+    /** The walk stops discovering new files once this many have been found (default 50000). */
+    maxFiles?: number;
+    /** Files parsed concurrently (default 4). */
+    concurrency?: number;
+    /**
+     * Watch the workspace for file changes and refresh the index automatically after a successful
+     * `index()` call establishes a baseline (default false). A caller that never sets this sees no
+     * change from before this option existed — indexing stays purely explicit.
+     *
+     * Overridden off by default on a WSL2 kernel watching a path mounted in from the Windows host
+     * (`/mnt/<drive>/...`), since inotify does not reliably deliver events over that 9P mount — see
+     * `watch-policy.ts`. Set `CODEGRAPH_FORCE_WATCH=1` to watch there anyway, or `CODEGRAPH_NO_WATCH=1`
+     * to force watching off everywhere regardless of this option.
+     */
+    watch?: boolean;
+    /** Quiet period after the last change before a watch-triggered refresh runs, in ms (default 2000). */
+    watchDebounceMs?: number;
+    /**
+     * Hard cap on directories watched individually (default 4000). Only relevant on platforms without a
+     * recursive `fs.watch` (Linux); exceeding it degrades that root's watcher rather than covering only
+     * part of the tree.
+     */
+    maxWatchedDirectories?: number;
+}
+export declare const Config: z<Config>;
+/**
+ * Register the tree-sitter indexer.
+ * @param ctx - the plugin context (must inject `codegraph`).
+ * @param config - the resolved plugin configuration.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/index.js

@@ -0,0 +1,203 @@
+/**
+ * Self-built code-graph indexer for `ctx.codegraph`. Parses a workspace with `web-tree-sitter` and
+ * `tree-sitter-wasms` and writes schema version 4 to `<projectRoot>/.codegraph/codegraph.db` — the
+ * same path and format `dsh-plugin-codegraph-sqlite` reads and the external `codegraph` CLI
+ * writes, so a workspace this package indexes becomes queryable through the existing store with no
+ * second graph format to disagree with the first.
+ *
+ * Registers **only an indexer**, never a store: `ctx.codegraph.index()` runs this package, and
+ * `ctx.codegraph.query()` is answered by whichever store claims the root afterward. Indexing never
+ * runs implicitly from a query — it is a caller-initiated, potentially multi-minute operation, kept
+ * out of the seam's read-only query path on purpose.
+ *
+ * Namespace plugin (named exports, no default export). Grammars load lazily, one per language, on
+ * first sight of a matching file, and stay cached for the process — never eagerly for every grammar
+ * this package ships with.
+ * @module dsh-plugin-codegraph-tree-sitter
+ */
+import { stat } from 'node:fs/promises';
+import { join } from 'node:path';
+import z from '@deepseek-ai/schemastery';
+import { CodegraphIndexerId } from 'dsh-plugin-codegraph-service';
+import { LANGUAGE_TABLE } from "./languages.js";
+import { walkAndExtract } from "./walk.js";
+import { resolveWorkspace } from "./resolve.js";
+import { writeGraph } from "./schema.js";
+import { createWatcher } from "./watcher.js";
+import { decideWatch, readProcVersion } from "./watch-policy.js";
+export { LANGUAGE_TABLE, languageFor } from "./languages.js";
+export { extractFile } from "./extract.js";
+export { loadGitignore, matchesGitignore, parseGitignore } from "./gitignore.js";
+export { resolveWorkspace } from "./resolve.js";
+export { SCHEMA_VERSION, writeGraph } from "./schema.js";
+export { isExcluded, walkAndExtract } from "./walk.js";
+export { createWatcher, nodeWatch } from "./watcher.js";
+export { decideWatch, readProcVersion } from "./watch-policy.js";
+export { detectWorktree, execGit } from "./worktree.js";
+export { HOOK_MARKER_BEGIN, HOOK_MARKER_END, installGitHooks, uninstallGitHooks } from "./git-hooks.js";
+/** Cordis plugin name for loader diagnostics. */
+export const name = 'codegraph-tree-sitter';
+/** Services required by this plugin. */
+export const inject = ['codegraph'];
+/** Path of the on-disk graph this package writes, relative to a project root. */
+export const DATABASE_RELATIVE_PATH = '.codegraph/codegraph.db';
+/** Default branded identity this indexer reserves on the seam. */
+export const DEFAULT_INDEXER_ID = 'codegraph-tree-sitter';
+/** Directory segments never descended into by default. */
+export const DEFAULT_EXCLUDE = ['node_modules', 'dist', 'build', 'coverage', '.git'];
+/** Default ceiling on a single file's size before it is skipped. */
+export const DEFAULT_MAX_FILE_BYTES = 2_000_000;
+/** Default ceiling on how many files one run indexes. */
+export const DEFAULT_MAX_FILES = 50_000;
+/** Default number of files parsed concurrently. */
+export const DEFAULT_CONCURRENCY = 4;
+/** Default quiet period after the last change before a watch-triggered refresh runs. */
+export const DEFAULT_WATCH_DEBOUNCE_MS = 2_000;
+/** Default cap on directories watched individually, on platforms without a recursive `fs.watch`. */
+export const DEFAULT_MAX_WATCHED_DIRECTORIES = 4_000;
+export const Config = z.object({
+    indexerId: z.string().default(DEFAULT_INDEXER_ID),
+    languages: z.array(z.string()).default([...new Set(LANGUAGE_TABLE.map(spec => spec.language))]),
+    exclude: z.array(z.string()).default(DEFAULT_EXCLUDE),
+    respectGitignore: z.boolean().default(true),
+    maxFileBytes: z.number().default(DEFAULT_MAX_FILE_BYTES),
+    maxFiles: z.number().default(DEFAULT_MAX_FILES),
+    concurrency: z.number().default(DEFAULT_CONCURRENCY),
+    watch: z.boolean().default(false),
+    watchDebounceMs: z.number().default(DEFAULT_WATCH_DEBOUNCE_MS),
+    maxWatchedDirectories: z.number().default(DEFAULT_MAX_WATCHED_DIRECTORIES),
+});
+/**
+ * Register the tree-sitter indexer.
+ * @param ctx - the plugin context (must inject `codegraph`).
+ * @param config - the resolved plugin configuration.
+ */
+export function apply(ctx, config) {
+    const resolved = config;
+    assertPositiveInteger('maxFileBytes', resolved.maxFileBytes);
+    assertPositiveInteger('maxFiles', resolved.maxFiles);
+    assertPositiveInteger('concurrency', resolved.concurrency);
+    assertPositiveInteger('watchDebounceMs', resolved.watchDebounceMs);
+    assertPositiveInteger('maxWatchedDirectories', resolved.maxWatchedDirectories);
+    // Keyed by project root, private to this plugin instance: never registered on `ctx`, so there is no
+    // cross-plugin relation here for an invariant to describe — just process-local bookkeeping this
+    // effect's cleanup below tears down on unload.
+    const watchers = new Map();
+    /** Start (or leave running) file watching for `projectRoot`, once it has a baseline to refresh. */
+    function ensureWatching(projectRoot) {
+        if (watchers.has(projectRoot))
+            return;
+        const decision = decideWatch({
+            configuredWatch: resolved.watch,
+            root: projectRoot,
+            env: process.env,
+            platform: process.platform,
+            procVersion: readProcVersion,
+        });
+        if (!decision.enabled)
+            return;
+        const watcher = createWatcher({
+            root: projectRoot,
+            exclude: resolved.exclude,
+            respectGitignore: resolved.respectGitignore,
+            debounceMs: resolved.watchDebounceMs,
+            maxWatchedDirectories: resolved.maxWatchedDirectories,
+            sync: () => runSync(projectRoot, resolved),
+            // No diagnostics service is wired into this package's dependencies; this is the floor for
+            // "degradation must be visible" until one is, per NOTES.local.md.
+            onDegraded: (reason) => {
+                console.error(`codegraph-tree-sitter: file watching for "${projectRoot}" stopped permanently (${reason.code}); ` +
+                    'the index will no longer refresh on its own — run codegraph_index manually to update it.');
+            },
+        });
+        watchers.set(projectRoot, watcher);
+        watcher.start();
+    }
+    const indexer = {
+        id: CodegraphIndexerId(resolved.indexerId),
+        async canIndex(projectRoot) {
+            try {
+                return (await stat(projectRoot)).isDirectory();
+            }
+            catch {
+                // Only the existence probe runs in the try. Any rejection — missing path, or no permission
+                // to look — means this indexer cannot build a graph here, which is the answer the seam asked
+                // for rather than a failure to report.
+                return false;
+            }
+        },
+        async index(projectRoot, signal) {
+            const report = await runIndex(projectRoot, resolved, signal);
+            // Watching starts only after a successful index establishes the baseline it refreshes — never
+            // from a canIndex() probe or a failed run.
+            ensureWatching(projectRoot);
+            return report;
+        },
+    };
+    ctx.effect(function* () {
+        yield () => {
+            for (const watcher of watchers.values())
+                watcher.stop();
+            watchers.clear();
+        };
+        yield ctx.codegraph.registerIndexer(indexer);
+    }, 'codegraph-tree-sitter');
+}
+/**
+ * Run one watch-triggered reindex. Always a full rebuild in this version — `runIndex` has no notion of
+ * a file subset — so the watcher's own collected paths are not consulted here.
+ * @param projectRoot - absolute path of the workspace to refresh.
+ * @param config - the resolved plugin configuration.
+ * @returns how many files the rebuild indexed, and how long it took.
+ */
+async function runSync(projectRoot, config) {
+    const startedAt = Date.now();
+    const report = await runIndex(projectRoot, config);
+    return { filesChanged: report.filesIndexed, durationMs: Date.now() - startedAt };
+}
+/**
+ * One indexing run: walk, parse, resolve, and write.
+ * @param projectRoot - absolute path of the workspace to index.
+ * @param config - the resolved plugin configuration.
+ * @param signal - aborts the run.
+ * @returns the run's report.
+ */
+async function runIndex(projectRoot, config, signal) {
+    const { files, filesSkipped } = await walkAndExtract(projectRoot, {
+        exclude: config.exclude,
+        respectGitignore: config.respectGitignore,
+        maxFileBytes: config.maxFileBytes,
+        maxFiles: config.maxFiles,
+        concurrency: config.concurrency,
+        languages: config.languages,
+    }, signal);
+    signal?.throwIfAborted();
+    const indexedAt = Date.now();
+    const graph = resolveWorkspace(files, indexedAt);
+    signal?.throwIfAborted();
+    const databasePath = join(projectRoot, DATABASE_RELATIVE_PATH);
+    await writeGraph(databasePath, { files, nodes: graph.nodes, edges: graph.edges, unresolved: graph.unresolved, indexedAt });
+    const languageCounts = new Map();
+    for (const file of files)
+        languageCounts.set(file.language, (languageCounts.get(file.language) ?? 0) + 1);
+    const languages = [...languageCounts.entries()]
+        .map(([language, fileCount]) => ({ language, fileCount }))
+        .sort((left, right) => right.fileCount - left.fileCount || left.language.localeCompare(right.language));
+    return {
+        projectRoot,
+        filesIndexed: files.length,
+        filesSkipped,
+        nodeCount: graph.nodes.length,
+        edgeCount: graph.edges.length,
+        unresolvedCount: graph.unresolved.length,
+        unresolvedLikelyInternalCount: graph.unresolved.filter(ref => !ref.likelyExternal).length,
+        languages,
+    };
+}
+/** Reject a non-positive-integer config value at load, so misconfiguration fails loud. */
+function assertPositiveInteger(field, value) {
+    if (!Number.isInteger(value) || value < 1) {
+        throw new Error(`codegraph-tree-sitter: ${field} must be a positive integer`);
+    }
+}
+//# sourceMappingURL=index.js.map

package/lib/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `dsh-plugin-codegraph-tree-sitter`.
+ * @module dsh-plugin-codegraph-tree-sitter/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "codegraph-tree-sitter-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/invariant.js

@@ -0,0 +1,25 @@
+/**
+ * Package-owned invariant companion for `dsh-plugin-codegraph-tree-sitter`.
+ * @module dsh-plugin-codegraph-tree-sitter/invariant
+ */
+const PACKAGE_NAME = 'dsh-plugin-codegraph-tree-sitter';
+/** Cordis companion plugin name. */
+export const name = 'codegraph-tree-sitter-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/**
+ * No runtime invariant: an indexing run is a one-shot, caller-awaited operation, and the optional file
+ * watcher this package can start keeps its per-root state (`Watcher` instances, debounce timers,
+ * pending-path sets) private to the plugin's own closure — never registered on `ctx` or exposed to
+ * another plugin. There is no cross-plugin relation here for an invariant to describe, only
+ * process-local bookkeeping the plugin's own `ctx.effect` cleanup already tears down on unload.
+ */
+const install = () => { };
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+/* jscpd:ignore-end */
+//# sourceMappingURL=invariant.js.map

package/lib/languages.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-language extraction tables: which tree-sitter node types are definitions, which are call
+ * sites, and which anchor an import, for every grammar this package loads today.
+ *
+ * The table is deliberately small. It covers the definition/call/import core the seam's operations
+ * depend on — not every declaration shape a language can produce — because the alternative is porting
+ * the reference indexer's language-specific resolution, which the proposal this package implements
+ * defers until the core proves itself against real workspaces.
+ * @module dsh-plugin-codegraph-tree-sitter/languages
+ */
+/** One tree-sitter node type that introduces a declaration, mapped to the seam's `NODE_KINDS`. */
+export interface DefinitionRule {
+    /** The tree-sitter node type this rule matches, e.g. `function_declaration`. */
+    readonly nodeType: string;
+    /** The seam node kind to record, e.g. `function`. See `NODE_KINDS` in `dsh-plugin-codegraph-service`. */
+    readonly kind: string;
+    /** The field holding the declared name; `childForFieldName(nameField)` must be an identifier. */
+    readonly nameField: string;
+    /**
+     * Present only when this rule is conditional on the shape of a value it binds — a
+     * `variable_declarator` is a function definition when its `value` is a function expression, and is
+     * otherwise not extracted at all. Field and matching types travel together so a rule can never
+     * declare one without the other.
+     */
+    readonly value?: {
+        /** Field naming the value assigned to the binding. */
+        readonly field: string;
+        /** Node types the field must resolve to for this rule to match. */
+        readonly types: readonly string[];
+    };
+}
+/** One tree-sitter node type recording a relative-import binding, per language family. */
+export interface ImportRule {
+    /** The tree-sitter node type anchoring one import statement, e.g. `import_statement`. */
+    readonly statementType: string;
+}
+/** One language grammar this package can load and extract from. */
+export interface LanguageSpec {
+    /** The seam's language label. See `LANGUAGES` in `dsh-plugin-codegraph-service`. */
+    readonly language: string;
+    /** File extensions routed to this grammar, each including the leading dot. */
+    readonly extensions: readonly string[];
+    /** The `tree-sitter-wasms` package-relative wasm file this grammar loads from. */
+    readonly wasmFile: string;
+    /** Definition rules tried in order for every named node the walk visits. */
+    readonly definitions: readonly DefinitionRule[];
+    /** Node types whose {@link callFunctionField} names the callee. */
+    readonly callTypes: readonly string[];
+    /** Field on a call node holding the callee expression. */
+    readonly callFunctionField: string;
+    /** Node types anchoring one import statement. */
+    readonly importTypes: readonly string[];
+}
+/** Every grammar this package loads, keyed by the seam language label it produces. */
+export declare const LANGUAGE_TABLE: readonly LanguageSpec[];
+/**
+ * The grammar for a file extension, or `undefined` when this package indexes nothing for it.
+ * @param extension - the file extension, including the leading dot, e.g. `.ts`.
+ * @returns the matching language's extraction table entry, or `undefined`.
+ */
+export declare function languageFor(extension: string): LanguageSpec | undefined;
+//# sourceMappingURL=languages.d.ts.map