onadit 0.0.1 → 1.0.0

package/dist/src/providers/voyage.js

@@ -0,0 +1,179 @@
+/**
+ * Voyage-3-lite embedding provider.
+ *
+ * Calls the Voyage AI embeddings API with retry + exponential backoff.
+ * Supports optional disk caching to reduce API calls.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import crypto from "node:crypto";
+import { abortableSleep, joinShared } from "./shared-request.js";
+import { DEFAULT_RETRY_CONFIG, EMBEDDING_DIMENSIONS } from "./types.js";
+/** Voyage's own API. Atlas-issued keys use https://ai.mongodb.com/v1 instead. */
+export const VOYAGE_DEFAULT_BASE_URL = "https://api.voyageai.com/v1";
+/** Read config.embedding into provider options. Unset fields keep the defaults. */
+export function voyageEndpoint(embedding) {
+    return {
+        model: embedding.model,
+        ...(embedding.base_url ? { baseUrl: embedding.base_url } : {}),
+        ...(embedding.output_dimension ? { outputDimension: embedding.output_dimension } : {}),
+    };
+}
+/** The embeddings URL for a base, tolerating a trailing slash. */
+export function voyageEmbeddingsUrl(baseUrl = VOYAGE_DEFAULT_BASE_URL) {
+    return `${baseUrl.replace(/\/+$/, "")}/embeddings`;
+}
+export class VoyageEmbeddingProvider {
+    name = "voyage";
+    apiKey;
+    model;
+    url;
+    outputDimension;
+    retry;
+    cachePath;
+    requestTimeoutMs;
+    /**
+     * Concurrent identical texts share one API call. It is cancelled only when
+     * every caller has aborted; a caller without a signal keeps it alive.
+     */
+    inflight = new Map();
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this.model = opts.model ?? "voyage-3-lite";
+        this.url = voyageEmbeddingsUrl(opts.baseUrl);
+        this.outputDimension = opts.outputDimension;
+        this.retry = { ...DEFAULT_RETRY_CONFIG, ...opts.retry };
+        this.cachePath = opts.cachePath;
+        this.requestTimeoutMs = opts.requestTimeoutMs;
+        if (this.cachePath) {
+            fs.mkdirSync(this.cachePath, { recursive: true });
+        }
+    }
+    async embed(text, opts = {}) {
+        const cached = this.readCache(text);
+        if (cached)
+            return cached;
+        return joinShared(this.inflight, this.cacheKey(text), async (signal) => {
+            const [result] = await this.callApi([text], signal);
+            if (!result)
+                throw new Error("Voyage API returned empty embeddings");
+            this.writeCache(text, result);
+            return result;
+        }, opts.signal);
+    }
+    async embedBatch(texts) {
+        // Check cache for each text; collect cache misses.
+        const results = texts.map((t) => this.readCache(t));
+        const misses = [];
+        for (let i = 0; i < texts.length; i++) {
+            if (results[i] === null) {
+                misses.push({ index: i, text: texts[i] });
+            }
+        }
+        if (misses.length > 0) {
+            const embeddings = await this.callApi(misses.map((m) => m.text));
+            for (let i = 0; i < misses.length; i++) {
+                const miss = misses[i];
+                const embedding = embeddings[i];
+                results[miss.index] = embedding;
+                this.writeCache(miss.text, embedding);
+            }
+        }
+        return results;
+    }
+    /** Call Voyage API with retry + exponential backoff. `signal` stops it, including between retries. */
+    async callApi(texts, signal) {
+        let lastError;
+        for (let attempt = 0; attempt <= this.retry.maxRetries; attempt++) {
+            if (attempt > 0) {
+                const delay = Math.min(this.retry.baseDelayMs * 2 ** (attempt - 1), this.retry.maxDelayMs);
+                await abortableSleep(delay, signal);
+            }
+            signal?.throwIfAborted();
+            try {
+                const res = await fetch(this.url, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                        Authorization: `Bearer ${this.apiKey}`,
+                    },
+                    body: JSON.stringify({
+                        input: texts,
+                        model: this.model,
+                        ...(this.outputDimension ? { output_dimension: this.outputDimension } : {}),
+                    }),
+                    ...requestSignal(signal, this.requestTimeoutMs),
+                });
+                if (res.status === 429 || res.status >= 500) {
+                    lastError = new Error(`Voyage API ${res.status}: ${await res.text()}`);
+                    continue; // Transient — retry
+                }
+                if (!res.ok) {
+                    throw new Error(`Voyage API ${res.status}: ${await res.text()}`);
+                }
+                const body = (await res.json());
+                return body.data.map((d) => d.embedding);
+            }
+            catch (err) {
+                // Cancelled by the caller: stop, never retry.
+                if (signal?.aborted)
+                    throw signal.reason ?? err;
+                if (err instanceof TypeError || isTimeout(err)) {
+                    // Network error or per-attempt deadline — transient, retry
+                    lastError = err;
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw lastError;
+    }
+    // --- Disk cache ---
+    cacheKey(text) {
+        return crypto
+            .createHash("sha256")
+            // A requested size is part of the key, so vectors of different sizes
+            // never share a cache entry. Default keys are unchanged.
+            .update(this.outputDimension
+            ? `${this.model}:${this.outputDimension}:${text}`
+            : `${this.model}:${text}`)
+            .digest("hex");
+    }
+    readCache(text) {
+        if (!this.cachePath)
+            return null;
+        const file = path.join(this.cachePath, this.cacheKey(text) + ".json");
+        try {
+            const raw = fs.readFileSync(file, "utf-8");
+            const parsed = JSON.parse(raw);
+            if (Array.isArray(parsed) && parsed.length === EMBEDDING_DIMENSIONS) {
+                return parsed;
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    writeCache(text, embedding) {
+        if (!this.cachePath)
+            return;
+        const file = path.join(this.cachePath, this.cacheKey(text) + ".json");
+        try {
+            fs.writeFileSync(file, JSON.stringify(embedding));
+        }
+        catch {
+            // Cache write failure is non-fatal.
+        }
+    }
+}
+function requestSignal(caller, timeoutMs) {
+    const signals = [caller, timeoutMs ? AbortSignal.timeout(timeoutMs) : undefined].filter((s) => s !== undefined);
+    if (signals.length === 0)
+        return {};
+    return { signal: signals.length === 1 ? signals[0] : AbortSignal.any(signals) };
+}
+function isTimeout(err) {
+    return err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+}
+//# sourceMappingURL=voyage.js.map

package/dist/src/providers/voyage.js.map

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

package/dist/src/retrieval/brief.d.ts

@@ -0,0 +1,26 @@
+import { type ProjectIndex } from "./project-index.js";
+export declare const BRIEF_MAX_BYTES = 2048;
+export interface ProjectBrief {
+    root: string;
+    worktree: string;
+    text: string;
+    bytes: number;
+    generated_at: string;
+    fingerprint: string;
+    truncated: boolean;
+}
+export type BriefResult = {
+    available: true;
+    brief: ProjectBrief;
+    cached: boolean;
+} | {
+    available: false;
+    reason: string;
+};
+export declare function getProjectBrief(opts: {
+    cwd: string;
+    dataDir: string;
+    index: ProjectIndex | null;
+    now?: Date;
+}): Promise<BriefResult>;
+//# sourceMappingURL=brief.d.ts.map

package/dist/src/retrieval/brief.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"brief.d.ts","sourceRoot":"","sources":["../../../src/retrieval/brief.ts"],"names":[],"mappings":"AAyBA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAG3E,eAAO,MAAM,eAAe,OAAQ,CAAC;AAMrC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,SAAS,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,YAAY,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GACzD;IAAE,SAAS,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAuNzC,wBAAsB,eAAe,CAAC,IAAI,EAAE;IAC1C,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3B,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,GAAG,OAAO,CAAC,WAAW,CAAC,CA0CvB"}

package/dist/src/retrieval/brief.js

@@ -0,0 +1,268 @@
+/**
+ * Small, source-backed project brief (~2 KB) for session start.
+ *
+ * Deterministic — no model call. Built from:
+ *   - the live trackers in the working tree (PROJECT_STATE.md: Current focus,
+ *     Recent decisions, Open questions; TODO.md: Now, Blocked), uncommitted
+ *     edits included;
+ *   - the project's latest captured sessions (triage summaries), via the
+ *     project index.
+ * Every line carries its source (file:line or conversation id + date).
+ * Project rules (AGENTS.md / CLAUDE.md) are pointed to, not copied: hosts
+ * already load them.
+ *
+ * Freshness: the brief is cached under `<data_dir>/briefs/` with a
+ * fingerprint of everything it read — tracker contents, git HEAD and
+ * the dirty-file count, the worktree path, and the project's latest captured
+ * conversation. Any change rebuilds it; a failed build returns "unavailable"
+ * so callers fall back to retrieval instead of serving stale text.
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { execFileSync } from "node:child_process";
+import { getTable } from "../storage/tables.js";
+import { inFilter } from "../storage/filter.js";
+import { resolveProjectRoot } from "./project-index.js";
+import { RECALL_HINT } from "./recall-hint.js";
+export const BRIEF_MAX_BYTES = 2_048;
+// 3: the brief names the tools and the server by their new names.
+const BRIEF_VERSION = 3;
+const ITEM_MAX = 140;
+const TRACKERS = ["PROJECT_STATE.md", "TODO.md"];
+function git(cwd, args) {
+    try {
+        return execFileSync("git", ["-C", cwd, ...args], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 3_000,
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function clip(text, max = ITEM_MAX) {
+    const t = text.replace(/\s+/g, " ").trim();
+    return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+}
+/** Top-level bullets of every `## <prefix>…` section, with line numbers and dates. */
+function sectionBullets(md, prefix) {
+    const out = [];
+    const lines = md.split("\n");
+    let inSection = false;
+    let headingDate;
+    lines.forEach((raw, i) => {
+        if (/^##\s/.test(raw)) {
+            inSection = raw.replace(/^##\s+/, "").toLowerCase().startsWith(prefix.toLowerCase());
+            headingDate = /\d{4}-\d{2}-\d{2}/.exec(raw)?.[0];
+            return;
+        }
+        if (/^#\s/.test(raw)) {
+            inSection = false;
+            return;
+        }
+        if (!inSection || !/^[-*]\s+/.test(raw))
+            return;
+        const text = raw.replace(/^[-*]\s+/, "");
+        const own = /\d{4}-\d{2}-\d{2}/.exec(text.slice(0, 40))?.[0];
+        const date = own ?? headingDate;
+        out.push({ n: i + 1, text, ...(date ? { date, dateFromHeading: !own } : {}) });
+    });
+    return out;
+}
+/**
+ * Newest decisions first. Dated bullets sort by date; on a tie, a bullet
+ * carrying its own date is a log entry (later line = newer), while bullets
+ * dated by their section heading are points of one decision (keep order).
+ * Undated trackers append, so their last bullets are the newest.
+ */
+function recentDecisions(md, count) {
+    const bullets = sectionBullets(md, "Recent decisions");
+    if (bullets.length && bullets.every((b) => b.date)) {
+        return [...bullets]
+            .sort((a, b) => {
+            if (a.date !== b.date)
+                return a.date < b.date ? 1 : -1;
+            return a.dateFromHeading ? a.n - b.n : b.n - a.n;
+        })
+            .slice(0, count);
+    }
+    return bullets.slice(-count).reverse();
+}
+async function readSources(cwd, root, index) {
+    const worktree = git(cwd, ["rev-parse", "--show-toplevel"]) ?? path.resolve(cwd);
+    const files = new Map();
+    for (const name of TRACKERS) {
+        const p = path.join(worktree, name);
+        try {
+            files.set(name, { text: fs.readFileSync(p, "utf8") });
+        }
+        catch {
+            // absent tracker: nothing to read
+        }
+    }
+    const porcelain = git(worktree, ["status", "--porcelain"]);
+    let conversations = [];
+    const ids = index ? (await index.rowsByProject()).byRoot.get(root) ?? [] : [];
+    if (ids.length) {
+        conversations = (await getTable("conversations_hot")
+            .query()
+            .select(["id", "summary", "indexed_at", "source"])
+            .where(inFilter("id", ids, { validateAsRowId: true }))
+            .toArray());
+        conversations.sort((a, b) => (a.indexed_at < b.indexed_at ? 1 : -1));
+    }
+    return {
+        root,
+        worktree,
+        branch: git(worktree, ["rev-parse", "--abbrev-ref", "HEAD"]),
+        head: git(worktree, ["rev-parse", "--short", "HEAD"]),
+        dirty: porcelain === null ? null : porcelain ? porcelain.split("\n").length : 0,
+        files,
+        conversations,
+    };
+}
+function fingerprintOf(s) {
+    return crypto
+        .createHash("sha256")
+        .update(JSON.stringify({
+        v: BRIEF_VERSION,
+        root: s.root,
+        worktree: s.worktree,
+        head: s.head,
+        branch: s.branch,
+        dirty: s.dirty,
+        files: [...s.files].map(([name, f]) => [name, crypto.createHash("sha1").update(f.text).digest("hex")]),
+        conv: [s.conversations.length, s.conversations[0]?.id ?? null, s.conversations[0]?.indexed_at ?? null],
+    }))
+        .digest("hex")
+        .slice(0, 16);
+}
+function render(s, now) {
+    const name = path.basename(s.root);
+    const state = s.head
+        ? `${s.branch ?? "detached"} @ ${s.head}${s.dirty ? `, ${s.dirty} uncommitted file${s.dirty === 1 ? "" : "s"}` : ""}`
+        : "not a git repository";
+    const header = `Onadit project brief — ${name} (${state}). Built ${now.toISOString().slice(0, 16)}Z from the live files ` +
+        `and captured sessions cited below; re-read a file before relying on its exact current state.`;
+    const sections = [];
+    const state_md = s.files.get("PROJECT_STATE.md")?.text;
+    const todo_md = s.files.get("TODO.md")?.text;
+    if (state_md) {
+        const focus = sectionBullets(state_md, "Current focus").slice(0, 2);
+        const plain = focus.length
+            ? focus
+            : (() => {
+                // Focus is often prose, not bullets: take the section's first lines.
+                const lines = state_md.split("\n");
+                const at = lines.findIndex((l) => /^##\s+current focus/i.test(l));
+                if (at < 0)
+                    return [];
+                return lines
+                    .slice(at + 1, at + 6)
+                    .map((text, i) => ({ n: at + 2 + i, text }))
+                    .filter((l) => l.text.trim() && !/^#/.test(l.text))
+                    .slice(0, 2);
+            })();
+        if (plain.length) {
+            sections.push(["Current focus:", ...plain.map((l) => `- ${clip(l.text)} (PROJECT_STATE.md:${l.n})`)]);
+        }
+    }
+    if (todo_md) {
+        const now_ = sectionBullets(todo_md, "Now").filter((l) => !/^\[x\]/i.test(l.text)).slice(0, 3);
+        if (now_.length)
+            sections.push(["Open now:", ...now_.map((l) => `- ${clip(l.text)} (TODO.md:${l.n})`)]);
+    }
+    if (state_md) {
+        const decisions = recentDecisions(state_md, 3);
+        if (decisions.length) {
+            sections.push(["Recent decisions:", ...decisions.map((l) => `- ${clip(l.text)} (PROJECT_STATE.md:${l.n})`)]);
+        }
+    }
+    if (s.conversations.length) {
+        sections.push([
+            "Latest captured sessions here (triage summaries):",
+            ...s.conversations.slice(0, 3).map((c) => `- ${c.indexed_at.slice(0, 10)} ${c.source}: ${clip(c.summary, 150)} (onadit id ${c.id})`),
+        ]);
+    }
+    const questions = [
+        ...(state_md ? sectionBullets(state_md, "Open questions").slice(0, 2).map((l) => `- ${clip(l.text)} (PROJECT_STATE.md:${l.n})`) : []),
+        ...(todo_md ? sectionBullets(todo_md, "Blocked").slice(0, 2).map((l) => `- ${clip(l.text)} (TODO.md:${l.n})`) : []),
+    ];
+    if (questions.length)
+        sections.push(["Unresolved / blocked:", ...questions]);
+    // The brief is built before the task is known, so it cannot hold the rule
+    // that matters for it. It says how to get it.
+    const footer = `Rules: AGENTS.md / CLAUDE.md (your host loads them). ${RECALL_HINT}`;
+    // Fill in priority order; drop whole trailing items to stay under budget.
+    let truncated = false;
+    const out = [header];
+    const bytes = (lines) => Buffer.byteLength([...lines, footer].join("\n"), "utf8");
+    for (const section of sections) {
+        const [title, ...items] = section;
+        const taken = [];
+        for (const item of items) {
+            if (bytes([...out, title, ...taken, item]) > BRIEF_MAX_BYTES) {
+                truncated = true;
+                break;
+            }
+            taken.push(item);
+        }
+        if (taken.length)
+            out.push(title, ...taken);
+    }
+    out.push(footer);
+    return { text: out.join("\n"), truncated };
+}
+function cachePath(dataDir, worktree) {
+    const key = crypto.createHash("sha1").update(worktree).digest("hex").slice(0, 16);
+    return path.join(dataDir, "briefs", `${key}.json`);
+}
+export async function getProjectBrief(opts) {
+    const root = resolveProjectRoot(opts.cwd);
+    if (!root)
+        return { available: false, reason: "not inside a project directory" };
+    let sources;
+    try {
+        sources = await readSources(opts.cwd, root, opts.index);
+    }
+    catch (err) {
+        return { available: false, reason: `could not read project sources: ${err instanceof Error ? err.message : String(err)}` };
+    }
+    if (sources.files.size === 0 && sources.conversations.length === 0) {
+        return { available: false, reason: "no trackers or captured sessions for this project" };
+    }
+    const fingerprint = fingerprintOf(sources);
+    const file = cachePath(opts.dataDir, sources.worktree);
+    try {
+        const cached = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (cached.fingerprint === fingerprint)
+            return { available: true, brief: cached, cached: true };
+    }
+    catch {
+        // no cache or unreadable: build
+    }
+    const now = opts.now ?? new Date();
+    const { text, truncated } = render(sources, now);
+    const brief = {
+        root,
+        worktree: sources.worktree,
+        text,
+        bytes: Buffer.byteLength(text, "utf8"),
+        generated_at: now.toISOString(),
+        fingerprint,
+        truncated,
+    };
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        const tmp = `${file}.tmp-${process.pid}`;
+        fs.writeFileSync(tmp, JSON.stringify(brief));
+        fs.renameSync(tmp, file);
+    }
+    catch {
+        // cache is an optimisation; the fresh brief is still correct
+    }
+    return { available: true, brief, cached: false };
+}
+//# sourceMappingURL=brief.js.map

package/dist/src/retrieval/brief.js.map

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

package/dist/src/retrieval/canonical-files.d.ts

@@ -0,0 +1,79 @@
+import type { EvidenceInput } from "./current-truth.js";
+/** Whether the read-only canonical-file lane is enabled. Default ON. */
+export declare function canonicalFilesEnabled(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Tracker-tier canonical files (slice 1). Relative names, resolved against the
+ * project root. Deliberately small — this is NOT "index every tracker"; it is a
+ * curated allow-list of files whose live contents are authoritative current
+ * state. Both match `TRACKER_FILE_PATTERNS` in current-truth.ts → `tracker` tier.
+ */
+export declare const CANONICAL_FILES: readonly string[];
+/** The tracker headings a state question can ask for. */
+export type HeadingGroup = "focus" | "now" | "next" | "blocked" | "decision";
+/**
+ * Whether a short text answers the question: the same subject-word test a
+ * tracker section must pass, for evidence that has no corpus to weigh terms
+ * against. A question with no subject word is answered by nothing.
+ */
+export declare function holdsQuestionSubject(text: string, query: string): boolean;
+export interface CanonicalSection {
+    /** First non-empty line (heading or list item), for display/title. */
+    heading: string;
+    /** Full section text (heading + body up to the next boundary). */
+    text: string;
+    /** Text of the nearest `#` heading at or above the section; "" before the first. */
+    parent: string;
+    /** 1-based line of the section's first non-empty line, for source links. */
+    line: number;
+}
+/**
+ * Split markdown into sections at heading lines (`#`..`######`) and TOP-LEVEL
+ * list items (`- ` / `* `, no leading indent). Each decision bullet, TODO item,
+ * or heading block becomes one section; nested/indented bullets stay with their
+ * parent. Content before the first boundary (e.g. the `Last touched:` preamble)
+ * forms the leading section.
+ */
+export declare function splitIntoSections(content: string): CanonicalSection[];
+export interface CanonicalFileEvidenceOptions {
+    /** Absolute project root; canonical files are resolved relative to it. */
+    projectRoot: string;
+    /** The user's task/query. */
+    query: string;
+    /** Max sections returned across all files (default 3). */
+    maxSections?: number;
+    /** Minimum distinct discriminating-term matches to surface (default 1). */
+    minScore?: number;
+    /** Allow-list override (tests). Defaults to {@link CANONICAL_FILES}. */
+    files?: readonly string[];
+    /** Injectable reader; returns undefined when missing. Defaults to fs. */
+    readFile?: (absPath: string) => string | undefined;
+    /** Injectable clock — live reads are current as of `now`. Defaults to new Date(). */
+    now?: Date;
+}
+/** One selected tracker section, with what the context pack needs to route it. */
+export interface CanonicalMatch {
+    fileName: string;
+    section: CanonicalSection;
+    /** The tracker heading the section sits under, when it is a known one. */
+    group: HeadingGroup | null;
+    score: number;
+}
+/**
+ * Read the canonical files and return the sections that answer the query,
+ * best first. A section answers when it holds the question's subject, or when
+ * the question asks only for project state and the section sits under an
+ * asked heading. Anything else is left out, so a tracker section never
+ * stands in for evidence that is actually about the question. Empty when the
+ * query has no discriminating terms, no file matches, or nothing answers.
+ */
+export declare function selectCanonicalSections(opts: CanonicalFileEvidenceOptions): CanonicalMatch[];
+/** Turn selected sections into synthetic tracker-tier {@link EvidenceInput}s. */
+export declare function canonicalEvidenceInputs(matches: readonly CanonicalMatch[], now?: Date): EvidenceInput[];
+/**
+ * {@link selectCanonicalSections} as evidence inputs, so the caller can prepend
+ * unconditionally.
+ */
+export declare function buildCanonicalFileEvidence(opts: CanonicalFileEvidenceOptions): EvidenceInput[];
+/** A tracker item without its list marker and checkbox. */
+export declare function cleanItemText(text: string): string;
+//# sourceMappingURL=canonical-files.d.ts.map

package/dist/src/retrieval/canonical-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-files.d.ts","sourceRoot":"","sources":["../../../src/retrieval/canonical-files.ts"],"names":[],"mappings":"AAoCA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,wEAAwE;AACxE,wBAAgB,qBAAqB,CACnC,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAET;AAED;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,SAAS,MAAM,EAAoC,CAAC;AAuClF,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,SAAS,GAAG,UAAU,CAAC;AAoD7E;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAczE;AAED,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,OAAO,EAAE,MAAM,CAAC;IAChB,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,oFAAoF;IACpF,MAAM,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB,EAAE,CAiCrE;AAED,MAAM,WAAW,4BAA4B;IAC3C,0EAA0E;IAC1E,WAAW,EAAE,MAAM,CAAC;IACpB,6BAA6B;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,yEAAyE;IACzE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACnD,qFAAqF;IACrF,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,kFAAkF;AAClF,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,gBAAgB,CAAC;IAC1B,0EAA0E;IAC1E,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;CACf;AAUD;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE,4BAA4B,GACjC,cAAc,EAAE,CAsIlB;AAED,iFAAiF;AACjF,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,SAAS,cAAc,EAAE,EAClC,GAAG,GAAE,IAAiB,GACrB,aAAa,EAAE,CAGjB;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,4BAA4B,GACjC,aAAa,EAAE,CAEjB;AAED,2DAA2D;AAC3D,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKlD"}