@cairn-tool/cairn 2.0.0

package/dist/archive/progress.js

@@ -0,0 +1,151 @@
+/**
+ * Progress reporting for a long archive run.
+ *
+ * A full run is tens of thousands of files and several gigabytes, and without
+ * this it printed nothing at all until it finished. Two levels, because they
+ * answer different questions:
+ *
+ * - the **transient line** answers "is it still going, and how far in" — it
+ *   rewrites itself in place, so it belongs only on a terminal
+ * - **verbose** answers "what exactly did it do to which file" — one durable
+ *   line per artifact, so it is worth redirecting to a file and grepping later
+ *
+ * The transient line is gated the same way the update notifier is: stderr must
+ * be a TTY, the format must not be machine-readable, and `CI` must be unset.
+ * Those gates exist because a `\r`-rewritten line is corruption in a log file
+ * and noise in a CI transcript. Verbose has no such gate — being redirectable is
+ * the whole point of it.
+ */
+function formatBytes(value) {
+    if (value >= 1_000_000_000)
+        return `${(value / 1_000_000_000).toFixed(1)}G`;
+    if (value >= 1_000_000)
+        return `${(value / 1_000_000).toFixed(1)}M`;
+    if (value >= 1_000)
+        return `${(value / 1_000).toFixed(1)}k`;
+    return `${value}B`;
+}
+function formatDuration(ms) {
+    const seconds = Math.round(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`;
+}
+/**
+ * Trims a path to fit, keeping its end.
+ *
+ * From the left, because the tail of a path is what identifies it — the head is
+ * a project root repeated on every line.
+ */
+function fitPath(text, width) {
+    if (width <= 1)
+        return "";
+    if (text.length <= width)
+        return text;
+    return `…${text.slice(text.length - width + 1)}`;
+}
+/**
+ * Decides whether the transient line may be drawn.
+ *
+ * Kept separate from the reporter so the command can report the decision, and
+ * so the rule is testable without a terminal.
+ */
+export function progressAllowed(format, stream = process.stderr, env = process.env) {
+    if (format === "json")
+        return false;
+    if (env.CI)
+        return false;
+    return stream.isTTY === true;
+}
+export function createReporter(options) {
+    const stream = options.stream ?? process.stderr;
+    const now = options.now ?? (() => Date.now());
+    // Verbose owns the terminal when both are on: a transient line would be
+    // overwritten by the next verbose line and leave fragments behind.
+    const drawLine = options.progress && !options.verbose;
+    if (!drawLine && !options.verbose)
+        return {};
+    const started = now();
+    let totalFiles = 0;
+    let totalBytes = 0;
+    let seenFiles = 0;
+    let seenBytes = 0;
+    let storedBytes = 0;
+    let segments = 0;
+    let lastDraw = 0;
+    let dirty = false;
+    const width = () => Math.max(40, Math.min(stream.columns ?? 100, 160));
+    const clear = () => {
+        if (dirty) {
+            stream.write(`\r${" ".repeat(width() - 1)}\r`);
+            dirty = false;
+        }
+    };
+    const draw = (label, force = false) => {
+        if (!drawLine)
+            return;
+        const at = now();
+        // Throttled: redrawing per file over 24k files is most of the work.
+        if (!force && at - lastDraw < 100)
+            return;
+        lastDraw = at;
+        const elapsed = at - started;
+        const rate = elapsed > 0 ? (seenBytes / elapsed) * 1000 : 0;
+        const percent = totalBytes > 0 ? Math.floor((seenBytes / totalBytes) * 100) : 0;
+        const head = `  ${percent}% ${seenFiles}/${totalFiles} files · ` +
+            `${formatBytes(seenBytes)}/${formatBytes(totalBytes)} · ` +
+            `${segments} seg · ${formatBytes(rate)}/s · ${formatDuration(elapsed)} · `;
+        // The counters survive a narrow terminal and the path gives way, rather than
+        // the other way round: how far along it is matters more than which file.
+        const room = width() - 1 - head.length;
+        const line = room > 1 ? head + fitPath(label, room) : head.slice(0, width() - 1);
+        stream.write(`\r${line}`);
+        dirty = true;
+    };
+    return {
+        start(total) {
+            totalFiles = total.files;
+            totalBytes = total.bytes;
+            if (options.verbose) {
+                stream.write(`archiving ${total.files} artifacts, ${formatBytes(total.bytes)} uncompressed\n`);
+            }
+            draw("", true);
+        },
+        file(event) {
+            seenFiles += 1;
+            seenBytes += event.size;
+            if (event.disposition === "stored")
+                storedBytes += event.size;
+            if (options.verbose) {
+                const hash = event.sha256 ? event.sha256.slice(0, 12) : "-".repeat(12);
+                stream.write(`${event.disposition.padEnd(9)} ${event.class.padEnd(10)} ` +
+                    `${formatBytes(event.size).padStart(8)}  ${hash}  ${event.path}\n`);
+            }
+            draw(event.path);
+        },
+        segment(event) {
+            segments += 1;
+            if (options.verbose) {
+                clear();
+                stream.write(`sealed    ${event.name}  ${formatBytes(event.bytes)}  ${event.blobs} blobs\n`);
+            }
+            draw("", true);
+        },
+        failure(event) {
+            // Always durable, at either level: a file that could not be read is the
+            // one thing in a run nobody should have to scroll back for.
+            clear();
+            stream.write(`unreadable ${event.file}: ${event.reason}\n`);
+            draw("", true);
+        },
+        finish() {
+            clear();
+            if (options.verbose) {
+                stream.write(`archived ${formatBytes(storedBytes)} of new content in ` +
+                    `${formatDuration(now() - started)}\n`);
+            }
+        },
+    };
+}
+//# sourceMappingURL=progress.js.map

package/dist/archive/progress.js.map

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

package/dist/archive/query.d.ts

@@ -0,0 +1,86 @@
+import type { SqliteDatabase } from "../sqlite.js";
+/** Reading the archive: what it holds, and getting a file back out of it. */
+export interface ArchiveStatus {
+    root: string;
+    present: boolean;
+    schemaVersion: number;
+    segments: number;
+    blobs: number;
+    artifacts: number;
+    /** Distinct paths, which is fewer than `artifacts` once anything has changed. */
+    paths: number;
+    /** Uncompressed bytes of stored content. */
+    bytes: number;
+    /** Bytes the segments actually occupy. */
+    compressedBytes: number;
+    updatedAt: string | null;
+    byClass: Record<string, {
+        artifacts: number;
+        bytes: number;
+    }>;
+    byProvider: Record<string, number>;
+}
+export declare function archiveStatus(root: string): ArchiveStatus;
+export interface ListFilter {
+    providers?: readonly string[];
+    class?: string;
+    /** Inclusive lower bound on `last_seen`, as an ISO day. */
+    since?: string;
+    limit?: number;
+}
+export interface ArchivedFile {
+    provider: string;
+    set: string;
+    class: string;
+    path: string;
+    sha256: string;
+    size: number;
+    firstSeen: string;
+    lastSeen: string;
+    /** How many distinct versions of this path the archive holds. */
+    versions: number;
+}
+export declare function listArtifacts(db: SqliteDatabase, filter: ListFilter): ArchivedFile[];
+export interface ResolvedBlob {
+    sha256: string;
+    size: number;
+    offset: number;
+    segment: string;
+    path: string;
+}
+/**
+ * Finds what to extract, by hash or by original path.
+ *
+ * A path may have several versions; the newest wins unless a hash was given,
+ * which is how an older one is reached. A hash prefix is accepted because a full
+ * sha256 is not something anyone types.
+ */
+export declare function resolve(db: SqliteDatabase, target: string): ResolvedBlob[];
+export interface ExtractResult {
+    path: string;
+    sha256: string;
+    bytes: number;
+    written: string;
+}
+/** Writes one resolved blob into `outDir`, under its original basename. */
+export declare function extract(root: string, blob: ResolvedBlob, outDir: string): ExtractResult;
+export interface VerifyFinding {
+    segment: string;
+    issue: string;
+}
+export interface VerifyResult {
+    segments: number;
+    blobs: number;
+    checked: number;
+    findings: VerifyFinding[];
+    deep: boolean;
+}
+/**
+ * Checks the archive against its index.
+ *
+ * The default pass hashes each segment file, which catches a truncated or
+ * corrupted archive for the cost of reading it. `--deep` also decompresses every
+ * segment and re-hashes each member, which additionally catches an index whose
+ * offsets no longer point where it claims.
+ */
+export declare function verify(root: string, deep: boolean): VerifyResult;

package/dist/archive/query.js

@@ -0,0 +1,241 @@
+import fs from "node:fs";
+import path from "node:path";
+import { closeQuietly } from "../sqlite-store.js";
+import { LATEST_VERSION, indexPath, openArchive, segmentsDirectory } from "./db.js";
+import { extractBlob, hashBuffer, readSegment } from "./segments.js";
+function emptyStatus(root) {
+    return {
+        root,
+        present: false,
+        schemaVersion: LATEST_VERSION,
+        segments: 0,
+        blobs: 0,
+        artifacts: 0,
+        paths: 0,
+        bytes: 0,
+        compressedBytes: 0,
+        updatedAt: null,
+        byClass: {},
+        byProvider: {},
+    };
+}
+export function archiveStatus(root) {
+    if (!fs.existsSync(indexPath(root)))
+        return emptyStatus(root);
+    let opened;
+    try {
+        opened = openArchive({ root, readOnly: true, migrate: false });
+    }
+    catch {
+        return emptyStatus(root);
+    }
+    try {
+        const db = opened.db;
+        const one = (sql) => Number(db.prepare(sql).get()?.n ?? 0);
+        const byClass = {};
+        for (const row of db
+            .prepare(`SELECT a.class, COUNT(*) AS n, COALESCE(SUM(b.size), 0) AS bytes
+           FROM artifact a JOIN blob b ON b.sha256 = a.sha256
+          GROUP BY a.class ORDER BY a.class`)
+            .all()) {
+            byClass[String(row.class)] = { artifacts: Number(row.n), bytes: Number(row.bytes) };
+        }
+        const byProvider = {};
+        for (const row of db
+            .prepare("SELECT provider, COUNT(*) AS n FROM artifact GROUP BY provider ORDER BY provider")
+            .all()) {
+            byProvider[String(row.provider)] = Number(row.n);
+        }
+        const updated = db.prepare("SELECT MAX(last_seen) AS at FROM artifact").get()?.at;
+        return {
+            root,
+            present: true,
+            schemaVersion: Number(db.prepare("PRAGMA user_version").get()?.user_version ?? 0),
+            segments: one("SELECT COUNT(*) AS n FROM segment"),
+            blobs: one("SELECT COUNT(*) AS n FROM blob"),
+            artifacts: one("SELECT COUNT(*) AS n FROM artifact"),
+            paths: one("SELECT COUNT(*) AS n FROM (SELECT DISTINCT provider, path FROM artifact)"),
+            bytes: one("SELECT COALESCE(SUM(size), 0) AS n FROM blob"),
+            compressedBytes: one("SELECT COALESCE(SUM(bytes), 0) AS n FROM segment"),
+            updatedAt: typeof updated === "string" ? updated : null,
+            byClass,
+            byProvider,
+        };
+    }
+    catch {
+        return emptyStatus(root);
+    }
+    finally {
+        closeQuietly(opened.db);
+    }
+}
+export function listArtifacts(db, filter) {
+    // Only the newest row per path is listed; older rows are that path's history
+    // and are reported as `versions` rather than as separate lines.
+    const conditions = ["a.id IN (SELECT MAX(id) FROM artifact GROUP BY provider, path)"];
+    const parameters = [];
+    if (filter.providers && filter.providers.length > 0) {
+        conditions.push(`a.provider IN (${filter.providers.map(() => "?").join(",")})`);
+        parameters.push(...filter.providers);
+    }
+    if (filter.class) {
+        conditions.push("a.class = ?");
+        parameters.push(filter.class);
+    }
+    if (filter.since) {
+        conditions.push("a.last_seen >= ?");
+        parameters.push(filter.since);
+    }
+    // The limit is interpolated because SQLite will not bind a LIMIT, and is
+    // floored to an integer here rather than trusted from the caller.
+    const limit = filter.limit && filter.limit > 0 ? `LIMIT ${Math.floor(filter.limit)}` : "";
+    const rows = db
+        .prepare(`SELECT a.provider, a.set_id, a.class, a.path, a.sha256, a.size,
+              a.first_seen, a.last_seen,
+              (SELECT COUNT(*) FROM artifact v
+                WHERE v.provider = a.provider AND v.path = a.path) AS versions
+         FROM artifact a
+        WHERE ${conditions.join(" AND ")}
+        ORDER BY a.last_seen DESC, a.path ASC
+        ${limit}`)
+        .all(...parameters);
+    return rows.map((row) => ({
+        provider: String(row.provider),
+        set: String(row.set_id),
+        class: String(row.class),
+        path: String(row.path),
+        sha256: String(row.sha256),
+        size: Number(row.size),
+        firstSeen: String(row.first_seen),
+        lastSeen: String(row.last_seen),
+        versions: Number(row.versions),
+    }));
+}
+/**
+ * Finds what to extract, by hash or by original path.
+ *
+ * A path may have several versions; the newest wins unless a hash was given,
+ * which is how an older one is reached. A hash prefix is accepted because a full
+ * sha256 is not something anyone types.
+ */
+export function resolve(db, target) {
+    const byHash = db
+        .prepare(`SELECT b.sha256, b.size, b.offset, s.name AS segment,
+              (SELECT path FROM artifact WHERE sha256 = b.sha256 ORDER BY id DESC LIMIT 1) AS path
+         FROM blob b JOIN segment s ON s.id = b.segment_id
+        WHERE b.sha256 = ? OR b.sha256 LIKE ?`)
+        .all(target, `${target}%`);
+    if (byHash.length > 0) {
+        return byHash.map((row) => ({
+            sha256: String(row.sha256),
+            size: Number(row.size),
+            offset: Number(row.offset),
+            segment: String(row.segment),
+            path: String(row.path ?? row.sha256),
+        }));
+    }
+    const byPath = db
+        .prepare(`SELECT b.sha256, b.size, b.offset, s.name AS segment, a.path
+         FROM artifact a
+         JOIN blob b ON b.sha256 = a.sha256
+         JOIN segment s ON s.id = b.segment_id
+        WHERE a.path = ?
+        ORDER BY a.id DESC LIMIT 1`)
+        .all(target);
+    return byPath.map((row) => ({
+        sha256: String(row.sha256),
+        size: Number(row.size),
+        offset: Number(row.offset),
+        segment: String(row.segment),
+        path: String(row.path),
+    }));
+}
+/** Writes one resolved blob into `outDir`, under its original basename. */
+export function extract(root, blob, outDir) {
+    const uncompressed = readSegment(segmentsDirectory(root), blob.segment);
+    const content = extractBlob(uncompressed, blob);
+    fs.mkdirSync(outDir, { recursive: true });
+    const written = path.join(outDir, path.basename(blob.path));
+    fs.writeFileSync(written, content);
+    return { path: blob.path, sha256: blob.sha256, bytes: content.length, written };
+}
+/**
+ * Checks the archive against its index.
+ *
+ * The default pass hashes each segment file, which catches a truncated or
+ * corrupted archive for the cost of reading it. `--deep` also decompresses every
+ * segment and re-hashes each member, which additionally catches an index whose
+ * offsets no longer point where it claims.
+ */
+export function verify(root, deep) {
+    const result = { segments: 0, blobs: 0, checked: 0, findings: [], deep };
+    if (!fs.existsSync(indexPath(root)))
+        return result;
+    const opened = openArchive({ root, readOnly: true, migrate: false });
+    const directory = segmentsDirectory(root);
+    try {
+        const db = opened.db;
+        const segments = db.prepare("SELECT id, name, sha256 FROM segment ORDER BY id").all();
+        result.segments = segments.length;
+        for (const segment of segments) {
+            const name = String(segment.name);
+            const file = path.join(directory, name);
+            let raw;
+            try {
+                raw = fs.readFileSync(file);
+            }
+            catch {
+                result.findings.push({ segment: name, issue: "missing from the segments directory" });
+                continue;
+            }
+            const actual = hashBuffer(raw);
+            if (actual !== String(segment.sha256)) {
+                result.findings.push({
+                    segment: name,
+                    issue: `hash mismatch: index says ${String(segment.sha256).slice(0, 12)}, file is ${actual.slice(0, 12)}`,
+                });
+                // A segment whose bytes already disagree cannot say anything useful
+                // about its members, so it is not opened further.
+                continue;
+            }
+            result.checked += 1;
+            const blobs = db
+                .prepare("SELECT sha256, size, offset FROM blob WHERE segment_id = ?")
+                .all(Number(segment.id));
+            result.blobs += blobs.length;
+            if (!deep)
+                continue;
+            let uncompressed;
+            try {
+                uncompressed = readSegment(directory, name);
+            }
+            catch (error) {
+                result.findings.push({
+                    segment: name,
+                    issue: `will not decompress: ${error.message}`,
+                });
+                continue;
+            }
+            for (const blob of blobs) {
+                try {
+                    extractBlob(uncompressed, {
+                        sha256: String(blob.sha256),
+                        size: Number(blob.size),
+                        offset: Number(blob.offset),
+                    });
+                }
+                catch (error) {
+                    result.findings.push({
+                        segment: name,
+                        issue: `${String(blob.sha256).slice(0, 12)}: ${error.message}`,
+                    });
+                }
+            }
+        }
+        return result;
+    }
+    finally {
+        closeQuietly(opened.db);
+    }
+}
+//# sourceMappingURL=query.js.map

package/dist/archive/query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"query.js","sourceRoot":"","sources":["../../src/archive/query.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AACpF,OAAO,EAAE,WAAW,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAsBrE,SAAS,WAAW,CAAC,IAAY;IAC/B,OAAO;QACL,IAAI;QACJ,OAAO,EAAE,KAAK;QACd,aAAa,EAAE,cAAc;QAC7B,QAAQ,EAAE,CAAC;QACX,KAAK,EAAE,CAAC;QACR,SAAS,EAAE,CAAC;QACZ,KAAK,EAAE,CAAC;QACR,KAAK,EAAE,CAAC;QACR,eAAe,EAAE,CAAC;QAClB,SAAS,EAAE,IAAI;QACf,OAAO,EAAE,EAAE;QACX,UAAU,EAAE,EAAE;KACf,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,IAAY;IACxC,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;IAC9D,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IACjE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IACD,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;QACrB,MAAM,GAAG,GAAG,CAAC,GAAW,EAAU,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;QAC3E,MAAM,OAAO,GAA6B,EAAE,CAAC;QAC7C,KAAK,MAAM,GAAG,IAAI,EAAE;aACjB,OAAO,CACN;;4CAEoC,CACrC;aACA,GAAG,EAAE,EAAE,CAAC;YACT,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC;QACtF,CAAC;QACD,MAAM,UAAU,GAA2B,EAAE,CAAC;QAC9C,KAAK,MAAM,GAAG,IAAI,EAAE;aACjB,OAAO,CAAC,kFAAkF,CAAC;aAC3F,GAAG,EAAE,EAAE,CAAC;YACT,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACnD,CAAC;QACD,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,2CAA2C,CAAC,CAAC,GAAG,EAAE,EAAE,EAAE,CAAC;QAClF,OAAO;YACL,IAAI;YACJ,OAAO,EAAE,IAAI;YACb,aAAa,EAAE,MAAM,CAAC,EAAE,CAAC,OAAO,CAAC,qBAAqB,CAAC,CAAC,GAAG,EAAE,EAAE,YAAY,IAAI,CAAC,CAAC;YACjF,QAAQ,EAAE,GAAG,CAAC,mCAAmC,CAAC;YAClD,KAAK,EAAE,GAAG,CAAC,gCAAgC,CAAC;YAC5C,SAAS,EAAE,GAAG,CAAC,oCAAoC,CAAC;YACpD,KAAK,EAAE,GAAG,CAAC,0EAA0E,CAAC;YACtF,KAAK,EAAE,GAAG,CAAC,8CAA8C,CAAC;YAC1D,eAAe,EAAE,GAAG,CAAC,kDAAkD,CAAC;YACxE,SAAS,EAAE,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;YACvD,OAAO;YACP,UAAU;SACX,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC;AAuBD,MAAM,UAAU,aAAa,CAAC,EAAkB,EAAE,MAAkB;IAClE,6EAA6E;IAC7E,gEAAgE;IAChE,MAAM,UAAU,GAAG,CAAC,gEAAgE,CAAC,CAAC;IACtF,MAAM,UAAU,GAAwB,EAAE,CAAC;IAC3C,IAAI,MAAM,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,UAAU,CAAC,IAAI,CAAC,kBAAkB,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAChF,UAAU,CAAC,IAAI,CAAC,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;IACvC,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,UAAU,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;QAC/B,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;QACjB,UAAU,CAAC,IAAI,CAAC,kBAAkB,CAAC,CAAC;QACpC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAChC,CAAC;IACD,yEAAyE;IACzE,kEAAkE;IAClE,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAE1F,MAAM,IAAI,GAAG,EAAE;SACZ,OAAO,CACN;;;;;gBAKU,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC;;UAE9B,KAAK,EAAE,CACZ;SACA,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC;IAEtB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;QAC9B,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QACvB,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC;QACxB,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QAC1B,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QACtB,SAAS,EAAE,MAAM,CAAC,GAAG,CAAC,UAAU,CAAC;QACjC,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC;QAC/B,QAAQ,EAAE,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;KAC/B,CAAC,CAAC,CAAC;AACN,CAAC;AAUD;;;;;;GAMG;AACH,MAAM,UAAU,OAAO,CAAC,EAAkB,EAAE,MAAc;IACxD,MAAM,MAAM,GAAG,EAAE;SACd,OAAO,CACN;;;8CAGwC,CACzC;SACA,GAAG,CAAC,MAAM,EAAE,GAAG,MAAM,GAAG,CAAC,CAAC;IAC7B,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YAC1B,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAC1B,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;YACtB,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;YAC1B,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC;YAC5B,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,MAAM,CAAC;SACrC,CAAC,CAAC,CAAC;IACN,CAAC;IAED,MAAM,MAAM,GAAG,EAAE;SACd,OAAO,CACN;;;;;mCAK6B,CAC9B;SACA,GAAG,CAAC,MAAM,CAAC,CAAC;IACf,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;QAC1B,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QAC1B,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;QACtB,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,MAAM,CAAC;QAC1B,OAAO,EAAE,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC;QAC5B,IAAI,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC;KACvB,CAAC,CAAC,CAAC;AACN,CAAC;AASD,2EAA2E;AAC3E,MAAM,UAAU,OAAO,CAAC,IAAY,EAAE,IAAkB,EAAE,MAAc;IACtE,MAAM,YAAY,GAAG,WAAW,CAAC,iBAAiB,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;IACxE,MAAM,OAAO,GAAG,WAAW,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAChD,EAAE,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1C,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5D,EAAE,CAAC,aAAa,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;AAClF,CAAC;AAeD;;;;;;;GAOG;AACH,MAAM,UAAU,MAAM,CAAC,IAAY,EAAE,IAAa;IAChD,MAAM,MAAM,GAAiB,EAAE,QAAQ,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;IACvF,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,MAAM,CAAC;IAEnD,MAAM,MAAM,GAAG,WAAW,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC;IACrE,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC1C,IAAI,CAAC;QACH,MAAM,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;QACrB,MAAM,QAAQ,GAAG,EAAE,CAAC,OAAO,CAAC,kDAAkD,CAAC,CAAC,GAAG,EAAE,CAAC;QACtF,MAAM,CAAC,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC;QAElC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;YAC/B,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YAClC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YACxC,IAAI,GAAW,CAAC;YAChB,IAAI,CAAC;gBACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;YAC9B,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,qCAAqC,EAAE,CAAC,CAAC;gBACtF,SAAS;YACX,CAAC;YACD,MAAM,MAAM,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC;YAC/B,IAAI,MAAM,KAAK,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;gBACtC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;oBACnB,OAAO,EAAE,IAAI;oBACb,KAAK,EAAE,6BAA6B,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;iBAC1G,CAAC,CAAC;gBACH,oEAAoE;gBACpE,kDAAkD;gBAClD,SAAS;YACX,CAAC;YACD,MAAM,CAAC,OAAO,IAAI,CAAC,CAAC;YAEpB,MAAM,KAAK,GAAG,EAAE;iBACb,OAAO,CAAC,4DAA4D,CAAC;iBACrE,GAAG,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;YAC3B,MAAM,CAAC,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC;YAC7B,IAAI,CAAC,IAAI;gBAAE,SAAS;YAEpB,IAAI,YAAoB,CAAC;YACzB,IAAI,CAAC;gBACH,YAAY,GAAG,WAAW,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YAC9C,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;oBACnB,OAAO,EAAE,IAAI;oBACb,KAAK,EAAE,wBAAyB,KAAe,CAAC,OAAO,EAAE;iBAC1D,CAAC,CAAC;gBACH,SAAS;YACX,CAAC;YACD,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,IAAI,CAAC;oBACH,WAAW,CAAC,YAAY,EAAE;wBACxB,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;wBAC3B,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC;wBACvB,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC;qBAC5B,CAAC,CAAC;gBACL,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC;wBACnB,OAAO,EAAE,IAAI;wBACb,KAAK,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAM,KAAe,CAAC,OAAO,EAAE;qBAC1E,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}

package/dist/archive/run.d.ts

@@ -0,0 +1,91 @@
+import type { UsageProvider } from "../usage/providers/types.js";
+import type { ArtifactClass, ArtifactSet } from "./sets.js";
+import type { RunReporter } from "./progress.js";
+/**
+ * The incremental archive walk.
+ *
+ * Two independent things make a run cheap on the second pass. A file whose
+ * `(path, size, mtime)` already matches an indexed row is never opened, so an
+ * unchanged corpus costs a stat per file; and a file that *is* opened but whose
+ * hash is already a stored blob is never written again, so a file that was
+ * merely touched, or that duplicates another, costs nothing but its row.
+ */
+export interface Candidate {
+    provider: string;
+    set: ArtifactSet;
+    /** Absolute path on disk. */
+    file: string;
+    /** Path recorded in the index: absolute, because that is what identifies it. */
+    recordPath: string;
+    size: number;
+    mtimeMs: number;
+    mode: number;
+}
+export interface RunCounters {
+    /** Files the sets matched. */
+    discovered: number;
+    /** Already indexed at this size and mtime; never opened. */
+    unchanged: number;
+    /** Opened and hashed. */
+    hashed: number;
+    /** Hashed, but the content was already stored; only a row was written. */
+    duplicate: number;
+    /** Written into a segment. */
+    stored: number;
+    /** Matched but unreadable. */
+    skipped: number;
+    /** Uncompressed bytes added. */
+    bytes: number;
+}
+export interface RunFailure {
+    file: string;
+    reason: string;
+}
+export interface RunResult {
+    counters: RunCounters;
+    failures: RunFailure[];
+    segments: {
+        name: string;
+        bytes: number;
+        blobs: number;
+    }[];
+    /** Per class, what this run took in. */
+    byClass: Record<string, {
+        discovered: number;
+        stored: number;
+        bytes: number;
+    }>;
+}
+export declare function emptyCounters(): RunCounters;
+/**
+ * Walks one set, yielding what it matches.
+ *
+ * Symbolic links are not followed. A link into a directory the sets deliberately
+ * exclude would otherwise pull it in anyway, which is the failure mode the
+ * allowlist in `sets.ts` exists to prevent.
+ */
+export declare function collectSet(root: string, provider: string, set: ArtifactSet): Candidate[];
+/** Everything the selected classes match, across the selected providers. */
+export declare function collect(sources: ReadonlyArray<{
+    provider: UsageProvider;
+    root: string;
+}>, classes: readonly ArtifactClass[]): Candidate[];
+export interface RunOptions {
+    archiveRoot: string;
+    sources: ReadonlyArray<{
+        provider: UsageProvider;
+        root: string;
+    }>;
+    classes: readonly ArtifactClass[];
+    /** Report what would be taken in, storing nothing. */
+    dryRun?: boolean;
+    segmentBytes?: number;
+    /**
+     * Told what happened as it happens.
+     *
+     * The engine reports events; how they are drawn is the command's business, so
+     * nothing here knows about terminals, colours, or `--verbose`.
+     */
+    reporter?: RunReporter;
+}
+export declare function runArchive(options: RunOptions): Promise<RunResult>;