@mka-rainmaker/ama 0.1.0

package/dist/indexer/debouncer.js

@@ -0,0 +1,81 @@
+/**
+ * Collapses bursts of file-change events into batched syncs. Each `notify(rel)`
+ * adds the path to a pending set and (re)arms a trailing timer; when the window
+ * elapses quietly, every pending path is synced once. A single flush runs at a
+ * time — paths that arrive while one is in progress are batched into the next —
+ * and a failing sync is isolated so the rest of the batch still runs.
+ *
+ * The debounce window collapses the several `fs.watch` events a single save can
+ * emit into one re-index. Drives ama-gd5.3's auto-sync; reusable anywhere a
+ * stream of keyed events should settle before acting.
+ */
+export class Debouncer {
+    sync;
+    windowMs;
+    pending = new Set();
+    timer;
+    flushing = false;
+    constructor(sync, windowMs) {
+        this.sync = sync;
+        this.windowMs = windowMs;
+    }
+    /** Record a changed path and (re)start the trailing window. */
+    notify(rel) {
+        this.pending.add(rel);
+        this.arm();
+    }
+    /** Pending paths not yet synced — for surfacing sync status (ama-gd5.6). */
+    get pendingCount() {
+        return this.pending.size;
+    }
+    /** The actual queued paths — for naming stale files in a banner (ama-gd5.5). */
+    pendingPaths() {
+        return [...this.pending];
+    }
+    /** Cancel the pending window. Does not flush — stopping accepts staleness. */
+    stop() {
+        if (this.timer !== undefined) {
+            clearTimeout(this.timer);
+            this.timer = undefined;
+        }
+    }
+    arm() {
+        if (this.timer !== undefined)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            void this.flush();
+        }, this.windowMs);
+    }
+    async flush() {
+        // A flush is already running; let it pick up what arrived, or re-arm so the
+        // next window drains anything it could not.
+        if (this.flushing) {
+            if (this.pending.size > 0)
+                this.arm();
+            return;
+        }
+        if (this.pending.size === 0)
+            return;
+        this.flushing = true;
+        const batch = [...this.pending];
+        this.pending.clear();
+        try {
+            for (const rel of batch) {
+                try {
+                    await this.sync(rel);
+                }
+                catch (err) {
+                    console.error(`[ama] auto-sync failed for ${rel}:`, err);
+                }
+            }
+        }
+        finally {
+            this.flushing = false;
+            // Edits that landed during the flush get their own window.
+            if (this.pending.size > 0)
+                this.arm();
+        }
+    }
+}
+//# sourceMappingURL=debouncer.js.map

package/dist/indexer/debouncer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debouncer.js","sourceRoot":"","sources":["../../src/indexer/debouncer.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,SAAS;IAMD;IACA;IANF,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,CAAiC;IACtC,QAAQ,GAAG,KAAK,CAAC;IAEzB,YACmB,IAAY,EACZ,QAAgB;QADhB,SAAI,GAAJ,IAAI,CAAQ;QACZ,aAAQ,GAAR,QAAQ,CAAQ;IAChC,CAAC;IAEJ,+DAA+D;IAC/D,MAAM,CAAC,GAAW;QAChB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,GAAG,EAAE,CAAC;IACb,CAAC;IAED,4EAA4E;IAC5E,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC;IAC3B,CAAC;IAED,gFAAgF;IAChF,YAAY;QACV,OAAO,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;IAC3B,CAAC;IAED,8EAA8E;IAC9E,IAAI;QACF,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;YAC7B,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACzB,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;QACzB,CAAC;IACH,CAAC;IAEO,GAAG;QACT,IAAI,IAAI,CAAC,KAAK,KAAK,SAAS;YAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvD,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC3B,IAAI,CAAC,KAAK,GAAG,SAAS,CAAC;YACvB,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACpB,CAAC;IAEO,KAAK,CAAC,KAAK;QACjB,4EAA4E;QAC5E,4CAA4C;QAC5C,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC;gBAAE,IAAI,CAAC,GAAG,EAAE,CAAC;YACtC,OAAO;QACT,CAAC;QACD,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,KAAK,CAAC;YAAE,OAAO;QACpC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,MAAM,KAAK,GAAG,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QAChC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;QACrB,IAAI,CAAC;YACH,KAAK,MAAM,GAAG,IAAI,KAAK,EAAE,CAAC;gBACxB,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACvB,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,OAAO,CAAC,KAAK,CAAC,8BAA8B,GAAG,GAAG,EAAE,GAAG,CAAC,CAAC;gBAC3D,CAAC;YACH,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;YACtB,2DAA2D;YAC3D,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,CAAC;gBAAE,IAAI,CAAC,GAAG,EAAE,CAAC;QACxC,CAAC;IACH,CAAC;CACF"}

package/dist/indexer/ignore.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Directories never worth indexing or watching. Dot-entries (`.git`, `.beads`,
+ * `.vscode`, …) are skipped separately. Shared by the indexer's file discovery
+ * and the file watcher so the set of files we *watch* matches what we *index*.
+ */
+export declare const IGNORED_DIRS: Set<string>;
+/**
+ * Files larger than this are skipped by both discovery and the watcher — a
+ * minified bundle or data blob isn't worth parsing and risks a memory blowup.
+ * Shared so the initial index and the watcher agree on what's too big; without
+ * it a huge file would be indexed on first build but skipped on re-index.
+ */
+export declare const MAX_FILE_SIZE_BYTES: number;
+/** Resolved ignore patterns for one root: exact segment names and name globs. */
+export interface IgnoreRules {
+    /** Dir/file names ignored at any depth (IGNORED_DIRS + .gitignore bare names). */
+    names: Set<string>;
+    /** Name globs from .gitignore (e.g. `*.gen.ts`), each anchored to a full segment. */
+    globs: RegExp[];
+    /** Root-anchored patterns (a leading or embedded slash, e.g. `/build`,
+     *  `pkg/internal`), matched against the full repo-relative path. (ama-yhu) */
+    anchored: RegExp[];
+    /** `!` negation patterns (full-path regexes): a path matched by an ignore rule
+     *  is re-included if it also matches one of these. A negation always wins (so a
+     *  rare re-ignore-after-negation over-includes rather than over-excludes —
+     *  fail-toward-inclusion); nested .gitignore is a follow-up. (ama-d28) */
+    negations: RegExp[];
+}
+/** The built-in ignores, used when no `.gitignore` has been loaded. */
+export declare const BASE_IGNORE_RULES: IgnoreRules;
+/**
+ * Read `<root>/.gitignore` and fold a *safe subset* of its patterns into the
+ * built-in ignores. Blank lines and `#` comments are skipped; nested `.gitignore`
+ * files are a follow-up (ama-d28). A bare `name`/`name/` ignores that segment at
+ * any depth; a glob like `*.ext` matches a segment; a pattern with a slash or `**`
+ * is anchored to the root and matched against the full path; a `!` line re-includes
+ * a path an earlier ignore excluded. (ama-2eu, ama-yhu, ama-dd9, ama-d28)
+ */
+export declare function loadIgnoreRules(root: string): IgnoreRules;
+/**
+ * Augment ignore rules with a subdirectory's own `.gitignore`, rebased so its
+ * patterns match the subtree relative to that directory — git applies a nested
+ * `.gitignore` to its own subtree, dir-relative (so `/build` means `<dir>/build`,
+ * not the repo root). Returns the parent rules unchanged when the directory has
+ * none. The root `.gitignore` is folded in by {@link loadIgnoreRules}; this is for
+ * the nested directories the discovery walk descends into. (ama-pyk)
+ */
+export declare function withNestedIgnore(dir: string, dirRel: string, parent: IgnoreRules): IgnoreRules;
+/** Whether a single path segment (a file or directory name) is ignored. */
+export declare function isIgnoredSegment(name: string, rules?: IgnoreRules): boolean;
+/** Whether a repo-relative path is ignored: any segment matches an any-depth
+ *  name/glob, or the full path matches a root-anchored pattern — unless a `!`
+ *  negation re-includes it. (ama-yhu, ama-d28) */
+export declare function isIgnoredPath(rel: string, rules?: IgnoreRules): boolean;
+//# sourceMappingURL=ignore.d.ts.map

package/dist/indexer/ignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignore.d.ts","sourceRoot":"","sources":["../../src/indexer/ignore.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,eAAO,MAAM,YAAY,aAAyD,CAAC;AAEnF;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,QAAc,CAAC;AAE/C,iFAAiF;AACjF,MAAM,WAAW,WAAW;IAC1B,kFAAkF;IAClF,KAAK,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACnB,qFAAqF;IACrF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;kFAC8E;IAC9E,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB;;;8EAG0E;IAC1E,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,uEAAuE;AACvE,eAAO,MAAM,iBAAiB,EAAE,WAK/B,CAAC;AA0CF;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,CAkCzD;AAYD;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,WAAW,GAAG,WAAW,CAsB9F;AAED,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,WAA+B,GAAG,OAAO,CAE9F;AAED;;kDAEkD;AAClD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,WAA+B,GAAG,OAAO,CAO1F"}

package/dist/indexer/ignore.js

@@ -0,0 +1,170 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+/**
+ * Directories never worth indexing or watching. Dot-entries (`.git`, `.beads`,
+ * `.vscode`, …) are skipped separately. Shared by the indexer's file discovery
+ * and the file watcher so the set of files we *watch* matches what we *index*.
+ */
+export const IGNORED_DIRS = new Set(["node_modules", "dist", "build", "coverage"]);
+/**
+ * Files larger than this are skipped by both discovery and the watcher — a
+ * minified bundle or data blob isn't worth parsing and risks a memory blowup.
+ * Shared so the initial index and the watcher agree on what's too big; without
+ * it a huge file would be indexed on first build but skipped on re-index.
+ */
+export const MAX_FILE_SIZE_BYTES = 1024 * 1024; // 1 MB
+/** The built-in ignores, used when no `.gitignore` has been loaded. */
+export const BASE_IGNORE_RULES = {
+    names: IGNORED_DIRS,
+    globs: [],
+    anchored: [],
+    negations: [],
+};
+/** A gitignore name glob (`*.ext`, `build-*`) as a whole-segment regex. (ama-2eu) */
+function globToSegmentRegExp(glob) {
+    const body = glob
+        .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+        .replace(/\*/g, "[^/]*")
+        .replace(/\?/g, "[^/]");
+    return new RegExp(`^${body}$`);
+}
+/** A root-anchored gitignore pattern (`build`, `pkg/internal`, `src/*.gen.ts`,
+ *  `**​/*.log`, `a/**​/b` — with any leading/trailing slash already stripped) as a
+ *  regex over the full repo-relative (posix) path, matching the entry and
+ *  everything under it. `*`/`?` stay within a path segment; `**` spans segments —
+ *  a leading or mid `**​/` matches zero or more directories, a trailing `/**`
+ *  matches everything under the prefix. (ama-yhu, ama-dd9) */
+function anchoredToRegExp(pattern) {
+    // A trailing `/**` matches everything under the prefix — the `(?:/|$)` suffix
+    // already does, so drop it.
+    const trimmed = pattern.replace(/\/\*\*$/, "");
+    // Expand glob tokens and escape regex specials in one pass — the alternation
+    // tries `**/` and `**` before a single `*`, so a deep glob isn't mis-expanded,
+    // and the expansions' own regex syntax is never re-escaped.
+    const body = trimmed.replace(/\*\*\/|\*\*|\*|\?|[.+^${}()|[\]\\]/g, (m) => {
+        if (m === "**/")
+            return "(?:.*/)?"; // zero or more directories
+        if (m === "**")
+            return ".*"; // any run, across path segments
+        if (m === "*")
+            return "[^/]*"; // within one segment
+        if (m === "?")
+            return "[^/]";
+        return `\\${m}`; // a regex special — escape it
+    });
+    return new RegExp(`^${body}(?:/|$)`);
+}
+/** A `!` negation pattern (the `!` already stripped) as a full-path regex: a bare
+ *  name / segment glob matches that segment at any depth (like `**​/name`); a
+ *  pattern with a slash or `**` is root-anchored. (ama-d28) */
+function negationToRegExp(pattern) {
+    const anchored = pattern.includes("/") || pattern.includes("**");
+    return anchoredToRegExp(anchored ? pattern.replace(/^\/+/, "") : `**/${pattern}`);
+}
+/**
+ * Read `<root>/.gitignore` and fold a *safe subset* of its patterns into the
+ * built-in ignores. Blank lines and `#` comments are skipped; nested `.gitignore`
+ * files are a follow-up (ama-d28). A bare `name`/`name/` ignores that segment at
+ * any depth; a glob like `*.ext` matches a segment; a pattern with a slash or `**`
+ * is anchored to the root and matched against the full path; a `!` line re-includes
+ * a path an earlier ignore excluded. (ama-2eu, ama-yhu, ama-dd9, ama-d28)
+ */
+export function loadIgnoreRules(root) {
+    const names = new Set(IGNORED_DIRS);
+    const globs = [];
+    const anchored = [];
+    const negations = [];
+    let text;
+    try {
+        text = fs.readFileSync(path.join(root, ".gitignore"), "utf8");
+    }
+    catch {
+        return { names, globs, anchored, negations };
+    }
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (line.startsWith("!")) {
+            // A negation re-includes a path an earlier rule excluded. (ama-d28)
+            const neg = line.slice(1).replace(/\/+$/, "");
+            if (neg)
+                negations.push(negationToRegExp(neg));
+            continue;
+        }
+        const body = line.replace(/\/+$/, ""); // a trailing slash only marks dir-only
+        if (!body)
+            continue;
+        if (body.includes("/") || body.includes("**")) {
+            // A leading/embedded slash or a `**` deep glob anchors the pattern to this
+            // .gitignore's directory (the root) — match it root-relatively, against the
+            // full path, not at any depth. (ama-yhu, ama-dd9)
+            anchored.push(anchoredToRegExp(body.replace(/^\/+/, "")));
+        }
+        else if (/[*?]/.test(body)) {
+            globs.push(globToSegmentRegExp(body));
+        }
+        else {
+            names.add(body);
+        }
+    }
+    return { names, globs, anchored, negations };
+}
+/** A nested-`.gitignore` line as a full-path regex relative to its own directory
+ *  (`baseRel`): a bare name/glob matches at any depth under it (`baseRel/**​/name`);
+ *  a slash/`**` pattern is anchored to it (`baseRel/pattern`). Reuses the root
+ *  matcher's compiler, just rooted one directory deeper. (ama-pyk) */
+function scopedToRegExp(pattern, baseRel) {
+    const rel = pattern.includes("/") || pattern.includes("**") ? pattern.replace(/^\/+/, "") : `**/${pattern}`;
+    return anchoredToRegExp(`${baseRel}/${rel}`);
+}
+/**
+ * Augment ignore rules with a subdirectory's own `.gitignore`, rebased so its
+ * patterns match the subtree relative to that directory — git applies a nested
+ * `.gitignore` to its own subtree, dir-relative (so `/build` means `<dir>/build`,
+ * not the repo root). Returns the parent rules unchanged when the directory has
+ * none. The root `.gitignore` is folded in by {@link loadIgnoreRules}; this is for
+ * the nested directories the discovery walk descends into. (ama-pyk)
+ */
+export function withNestedIgnore(dir, dirRel, parent) {
+    let text;
+    try {
+        text = fs.readFileSync(path.join(dir, ".gitignore"), "utf8");
+    }
+    catch {
+        return parent;
+    }
+    const base = dirRel.split(path.sep).join("/"); // repo-relative, posix
+    const anchored = [...parent.anchored];
+    const negations = [...parent.negations];
+    for (const raw of text.split("\n")) {
+        const line = raw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        if (line.startsWith("!")) {
+            const neg = line.slice(1).replace(/\/+$/, "");
+            if (neg)
+                negations.push(scopedToRegExp(neg, base));
+            continue;
+        }
+        const body = line.replace(/\/+$/, "");
+        if (body)
+            anchored.push(scopedToRegExp(body, base));
+    }
+    return { ...parent, anchored, negations };
+}
+/** Whether a single path segment (a file or directory name) is ignored. */
+export function isIgnoredSegment(name, rules = BASE_IGNORE_RULES) {
+    return name.startsWith(".") || rules.names.has(name) || rules.globs.some((re) => re.test(name));
+}
+/** Whether a repo-relative path is ignored: any segment matches an any-depth
+ *  name/glob, or the full path matches a root-anchored pattern — unless a `!`
+ *  negation re-includes it. (ama-yhu, ama-d28) */
+export function isIgnoredPath(rel, rules = BASE_IGNORE_RULES) {
+    const segments = rel.split(path.sep);
+    const posix = segments.join("/");
+    const ignored = segments.some((seg) => isIgnoredSegment(seg, rules)) ||
+        rules.anchored.some((re) => re.test(posix));
+    return ignored && !rules.negations.some((re) => re.test(posix));
+}
+//# sourceMappingURL=ignore.js.map

package/dist/indexer/ignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ignore.js","sourceRoot":"","sources":["../../src/indexer/ignore.ts"],"names":[],"mappings":"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"}

package/dist/indexer/indexer.d.ts

@@ -0,0 +1,112 @@
+import { AnalyzerRegistry } from "../analyzers/registry.js";
+import type { ResolutionStats } from "../analyzers/types.js";
+import type { Tier } from "../graph/index.js";
+import type { FileMeta, Store } from "../store/types.js";
+export interface LanguageCoverage {
+    language: string;
+    tier: Tier;
+    files: number;
+}
+export interface IndexStats {
+    /** Absolute root that was indexed. */
+    root: string;
+    nodeCount: number;
+    edgeCount: number;
+    /** Number of source files actually analyzed. */
+    fileCount: number;
+    /** Per-language coverage, each carrying the analyzer's tier. */
+    languages: LanguageCoverage[];
+    /** Aggregate call-resolution coverage across deep analyzers, when measured. */
+    resolution?: ResolutionStats;
+}
+/** What a catch-up {@link Indexer.sync} reconciled. */
+export interface SyncResult {
+    /** Repo-relative paths re-indexed because they were new or modified. */
+    changed: string[];
+    /** Repo-relative paths dropped because they no longer exist (or analyze). */
+    removed: string[];
+}
+/** Throw if `root` resolves to the filesystem root, the user's home directory,
+ *  or a well-known system directory — a guardrail so a stray `index_repository`
+ *  call (an agent, a typo) can't walk the whole machine. (ama-m8k.10) */
+export declare function assertSafeRoot(root: string): void;
+/**
+ * Turns a directory into a graph: discover source files, hand each to the
+ * analyzer that claims its extension, and collect the resulting nodes/edges
+ * into a store. All files for one analyzer are analyzed together so it can
+ * resolve cross-file references (e.g. an import's call target).
+ */
+export declare class Indexer {
+    private readonly registry;
+    /** How to create the backing store for a (resolved) project root — swap this to
+     *  persist to SQLite. The root is passed so a multi-project session can give each
+     *  project an independent store; a factory that ignores it and returns one shared
+     *  store would alias every project onto the last index. (ama-mnj) */
+    private readonly createStore;
+    constructor(registry: AnalyzerRegistry, 
+    /** How to create the backing store for a (resolved) project root — swap this to
+     *  persist to SQLite. The root is passed so a multi-project session can give each
+     *  project an independent store; a factory that ignores it and returns one shared
+     *  store would alias every project onto the last index. (ama-mnj) */
+    createStore?: (root: string) => Store);
+    /** The (language, tier) that owns a file, or undefined if no analyzer claims it.
+     *  Lets a caller recompute per-language coverage live from the current file set,
+     *  so index_status's census stays correct after incremental syncs — not only
+     *  after a full index, which is the only thing that writes the cached coverage
+     *  metadata. (ama-okg) */
+    languageOf(rel: string): {
+        language: string;
+        tier: Tier;
+    } | undefined;
+    index(root: string): Promise<{
+        store: Store;
+        stats: IndexStats;
+    }>;
+    /**
+     * Reopen a previously-persisted index without re-analyzing: open the store and,
+     * if it holds a usable index for `root` (matching schema version and root, with
+     * nodes present), reconstruct its {@link IndexStats} from the persisted
+     * coverage metadata. Returns undefined — and closes the freshly-opened store —
+     * when there is nothing usable (an empty in-memory store, a different root, or
+     * an incompatible schema), so the caller falls back to a full {@link index}.
+     */
+    open(root: string): Promise<{
+        store: Store;
+        stats: IndexStats;
+    } | undefined>;
+    /**
+     * Re-index a single changed file into an existing store, in place. Re-analyzes
+     * just `rel` and reconciles its delta (so an edit churns only what changed);
+     * if `rel` was deleted or is no longer analyzable, its data is dropped instead.
+     * Edges from `rel` into files this pass never walks still resolve, because the
+     * analyzer falls back to location-derived ids for nodes already in the store.
+     */
+    reindexFile(store: Store, root: string, rel: string): Promise<void>;
+    /**
+     * Catch-up reconcile: compare the tree on disk against the stored fingerprints
+     * and re-index everything that drifted — files added or modified since the
+     * last index, and files that have since vanished. Detection is cheap
+     * (size + mtime, with a content hash only as the tiebreaker), and unchanged
+     * files are skipped entirely. The manual counterpart to the live watcher.
+     */
+    sync(store: Store, root: string): Promise<SyncResult>;
+}
+/**
+ * An indexer wired with the analyzers Ama ships today. Pass a `createStore`
+ * factory to persist into SQLite instead of the default in-memory store.
+ */
+export declare function createDefaultIndexer(createStore?: (root: string) => Store): Indexer;
+/** Fingerprint a file for staleness tracking: size, mtime, and content hash.
+ *  Returns null when the file has vanished (gone between discovery and now — an
+ *  editor's atomic save or temp file) so the caller can drop it instead of
+ *  crashing the index. (ama-7r5) */
+export declare function fingerprint(root: string, rel: string): FileMeta | null;
+/**
+ * Whether a file differs from its recorded fingerprint. Size and mtime are the
+ * cheap first check; the content hash is consulted only when they are
+ * inconclusive (mtime can change without the bytes changing), so an unchanged
+ * file is never re-hashed. A file that has vanished counts as stale, so the
+ * caller reindexes it and its `existsSync` check reconciles the removal. (ama-7r5)
+ */
+export declare function isStale(root: string, rel: string, meta: FileMeta): boolean;
+//# sourceMappingURL=indexer.d.ts.map

package/dist/indexer/indexer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"indexer.d.ts","sourceRoot":"","sources":["../../src/indexer/indexer.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,KAAK,EAA4B,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGvF,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,mBAAmB,CAAC;AAE9C,OAAO,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AASzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,IAAI,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,UAAU;IACzB,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,SAAS,EAAE,gBAAgB,EAAE,CAAC;IAC9B,+EAA+E;IAC/E,UAAU,CAAC,EAAE,eAAe,CAAC;CAC9B;AASD,uDAAuD;AACvD,MAAM,WAAW,UAAU;IACzB,wEAAwE;IACxE,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,6EAA6E;IAC7E,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAqBD;;yEAEyE;AACzE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAOjD;AAED;;;;;GAKG;AACH,qBAAa,OAAO;IAEhB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB;;;yEAGqE;IACrE,OAAO,CAAC,QAAQ,CAAC,WAAW;gBALX,QAAQ,EAAE,gBAAgB;IAC3C;;;yEAGqE;IACpD,WAAW,GAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAiC;IAGnF;;;;8BAI0B;IAC1B,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,GAAG,SAAS;IAK/D,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,CAAC;IA+FvE;;;;;;;OAOG;IACG,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,UAAU,CAAA;KAAE,GAAG,SAAS,CAAC;IAwClF;;;;;;OAMG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBzE;;;;;;OAMG;IACG,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;CAqB5D;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,KAAK,GAAG,OAAO,CAiBnF;AAeD;;;oCAGoC;AACpC,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAStE;AAED;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,OAAO,CAe1E"}