looply-cli 0.0.0-stage → 0.2.0

package/dist/project-index-builder.js

@@ -0,0 +1,298 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_INDEXED_BYTES = void 0;
+exports.packageFor = packageFor;
+exports.extractFrom = extractFrom;
+exports.resolveSpecifier = resolveSpecifier;
+exports.buildProjectIndex = buildProjectIndex;
+const core_1 = require("@looply/core");
+/**
+ * BUILDING THE INDEX FROM WHAT GIT ALREADY KNOWS.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 NO PARSER, AND THAT IS A SHIPPING CONSTRAINT RATHER THAN A PREFERENCE
+ *
+ * `typescript` is NOT a dependency of this package. It resolves inside this
+ * monorepo only because the root has a hoisted dev copy — the published
+ * `looply-cli` declares three runtime dependencies and TypeScript is not among
+ * them. A `require('typescript')` here would pass every test in this repository
+ * and throw MODULE_NOT_FOUND for every real `npx looply-cli` user, and the
+ * committed-tree certifier could not catch it either: it borrows `node_modules`
+ * from the working tree, which HAS the hoisted copy.
+ *
+ * So extraction is dependency-free and deliberately CONSERVATIVE. It finds what
+ * it can state plainly and records everything else as unparsed WITH A REASON.
+ * A guessed symbol would be structural truth invented by pattern-matching,
+ * which is precisely what a deterministic index exists not to contain.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHAT IT FINDS, AND WHAT IT DOES NOT
+ *
+ *   finds       top-level `export` declarations and static import specifiers
+ *   does not    private symbols, re-export chains, dynamic imports, anything
+ *               inside a namespace or a conditional block
+ *
+ * The boundary is chosen so that a false POSITIVE is nearly impossible: every
+ * pattern is anchored to the start of a line, so a match is a real top-level
+ * declaration or nothing. Missing something is recoverable — a later phase can
+ * widen it. Inventing something is not, because a graph built on it looks
+ * exactly like a graph built on evidence.
+ */
+/**
+ * Files above this are recorded as `unparsed`, not read.
+ *
+ * A megabyte of source is a generated file or a vendored blob, and reading it
+ * would spend the whole budget on something no dependency question is about.
+ * Recorded rather than skipped, so a reader knows the index HAS an opinion
+ * about that path and the opinion is "I did not look".
+ */
+exports.MAX_INDEXED_BYTES = 512 * 1024;
+/**
+ * The package a file belongs to.
+ *
+ * Longest prefix wins, so a nested package inside another is attributed to the
+ * nearer one rather than to whichever happened to be checked first — an order
+ * dependence would be exactly the kind of non-determinism this phase is about.
+ */
+function packageFor(path, packages) {
+    let best = null;
+    for (const p of packages) {
+        if (path === p.dir || path.startsWith(`${p.dir}/`)) {
+            if (best === null || p.dir.length > best.dir.length)
+                best = p;
+        }
+    }
+    return best === null ? null : best.name;
+}
+/**
+ * Split source into lines, tolerating either line ending.
+ *
+ * ⚠️ CRLF IS THE DEFAULT IN THIS REPOSITORY, NOT AN EDGE CASE. A line-anchored
+ * pattern written for `\n` matches nothing in a CRLF file and the extractor
+ * silently reports an empty file — the failure reads as "this file declares
+ * nothing" rather than as an error.
+ */
+function lines(text) {
+    return text.split(/\r?\n/);
+}
+const DECLARATION = /^export\s+(?:declare\s+)?(?:default\s+)?(?:async\s+)?(function|class|interface|type|const|let|var|enum)\s+([A-Za-z_$][A-Za-z0-9_$]*)/;
+const KIND_OF = {
+    function: 'function',
+    class: 'class',
+    interface: 'interface',
+    type: 'type',
+    const: 'const',
+    let: 'const',
+    var: 'const',
+    enum: 'enum',
+};
+/** A static import or re-export, as written. Anchored: no match, no claim. */
+const IMPORT = /^(?:import|export)\b[^'"]*from\s+['"]([^'"]+)['"]/;
+const BARE_IMPORT = /^import\s+['"]([^'"]+)['"]/;
+/**
+ * A statement that OPENS a braced import list without closing it on this line.
+ *
+ * 🔴 THE LINE-ANCHORED PATTERNS ABOVE CANNOT SEE A MULTI-LINE IMPORT AT ALL,
+ * AND THIS REPOSITORY IS FULL OF THEM.
+ *
+ * Measured at the Phase-13 freeze, over every tracked `.ts`/`.tsx`: the
+ * extractor saw 1,839 single-line imports and MISSED 164 multi-line ones, of
+ * which 105 were relative — that is, real edges. They are spread over 144 of
+ * 454 files, so a third of the repository had at least one dependency the index
+ * silently did not have.
+ *
+ * That was survivable while nothing consumed the index. Phase 13 consumes it to
+ * answer "what depends on this", where a missing edge is not a gap in a cache —
+ * it is a wrong answer to the question the phase exists to answer. Phase 12 said
+ * of exactly this: `Missing something is recoverable — a later phase can widen
+ * it.` This is that phase.
+ *
+ * ⚠️ WIDENED WITHOUT LOOSENING. The statement must still START at the beginning
+ * of a line, and the brace must follow `import`/`export` immediately — so
+ * `export function foo() {` cannot match, because what follows `export ` there
+ * is `function`. A false positive is still nearly impossible, which was the
+ * property worth keeping.
+ */
+const OPENS_LIST = /^(?:import|export)\s+(?:type\s+)?\{[^}]*$/;
+/** The line that closes one, carrying the specifier. */
+const CLOSES_LIST = /^\s*\}\s*from\s+['"]([^'"]+)['"]/;
+/**
+ * How far to look for the close.
+ *
+ * Bounded so a malformed file cannot make extraction quadratic. The longest
+ * real import list in this repository is well inside it; a statement longer
+ * than this is not recorded, which is the same conservative failure the rest of
+ * this extractor makes.
+ */
+const MAX_IMPORT_LINES = 200;
+/**
+ * Read one TypeScript file's exported declarations and imports.
+ *
+ * Line-anchored on purpose: a pattern that could match mid-line would find
+ * `export` inside a string or a comment and invent a symbol from it.
+ */
+function extractFrom(path, source) {
+    const symbols = [];
+    const imports = [];
+    const seen = new Set();
+    const all = lines(source);
+    /**
+     * Lines that are the INTERIOR of a multi-line import, and so must not be
+     * read as anything else. Without this a name inside a braced list could
+     * match a pattern meant for a statement.
+     */
+    const consumed = new Set();
+    for (let i = 0; i < all.length; i += 1) {
+        const line = all[i] ?? '';
+        if (IMPORT.test(line) || BARE_IMPORT.test(line) || !OPENS_LIST.test(line))
+            continue;
+        for (let j = i + 1; j < Math.min(i + MAX_IMPORT_LINES, all.length); j += 1) {
+            const next = all[j] ?? '';
+            const close = CLOSES_LIST.exec(next);
+            if (close !== null) {
+                const spec = close[1];
+                imports.push({ from: path, specifier: spec, resolved: resolveSpecifier(path, spec) });
+                for (let k = i; k <= j; k += 1)
+                    consumed.add(k);
+                i = j;
+                break;
+            }
+            // A new statement began before this one closed: the open was not an
+            // import list after all, and nothing is claimed.
+            if (/^(?:import|export)\b/.test(next))
+                break;
+        }
+    }
+    all.forEach((line, i) => {
+        if (consumed.has(i))
+            return;
+        const decl = DECLARATION.exec(line);
+        if (decl !== null) {
+            const [, keyword, name] = decl;
+            const kind = KIND_OF[keyword ?? ''];
+            if (kind !== undefined && name !== undefined) {
+                const id = `${path}#${name}`;
+                // One declaration per name per file: an overload set is one symbol, and
+                // a duplicate id would make the index depend on how many times a name
+                // happened to appear.
+                if (!seen.has(id)) {
+                    seen.add(id);
+                    symbols.push({ id, name, kind, file: path, line: i + 1 });
+                }
+            }
+        }
+        const spec = IMPORT.exec(line)?.[1] ?? BARE_IMPORT.exec(line)?.[1];
+        if (spec !== undefined) {
+            imports.push({ from: path, specifier: spec, resolved: resolveSpecifier(path, spec) });
+        }
+    });
+    return { symbols, imports };
+}
+/**
+ * Where a specifier points, when that can be answered without guessing.
+ *
+ * 🔴 RELATIVE SPECIFIERS ONLY. A bare specifier may be a package OR a path
+ * alias configured in a tsconfig this extractor does not read, and inventing a
+ * target would put a relationship in the index that nothing established.
+ * `null` means NOT RESOLVED — it does not mean external.
+ *
+ * ⚠️ THE EXTENSION IS NOT GUESSED EITHER. `./foo` could be `foo.ts`, `foo.tsx`
+ * or `foo/index.ts`, and choosing one would be right most of the time, which is
+ * the worst possible property for a fact somebody builds on. The caller
+ * resolves against the real file list; this reports the normalised path only.
+ */
+function resolveSpecifier(from, specifier) {
+    if (!specifier.startsWith('.'))
+        return null;
+    const dir = from.includes('/') ? from.slice(0, from.lastIndexOf('/')) : '';
+    const joined = `${dir}/${specifier}`;
+    const parts = [];
+    for (const part of joined.split('/')) {
+        if (part === '' || part === '.')
+            continue;
+        if (part === '..') {
+            if (parts.length === 0)
+                return null; // escapes the project; not ours
+            parts.pop();
+            continue;
+        }
+        parts.push(part);
+    }
+    return parts.length === 0 ? null : parts.join('/');
+}
+/** Attach a real file to a normalised specifier, or leave it unresolved. */
+function bindImports(imports, known) {
+    const candidates = (base) => [
+        base,
+        `${base}.ts`,
+        `${base}.tsx`,
+        `${base}/index.ts`,
+        `${base}/index.tsx`,
+    ];
+    return imports.map((i) => {
+        if (i.resolved === null)
+            return i;
+        const hit = candidates(i.resolved).find((c) => known.has(c));
+        // Unresolved stays unresolved: a specifier pointing at a file that is not
+        // in the index is a fact about the index, not a licence to invent one.
+        return { ...i, resolved: hit ?? null };
+    });
+}
+/**
+ * Build the whole index for a revision.
+ *
+ * Every collection is sorted before it is returned, so the caller cannot
+ * accidentally depend on the order git happened to emit.
+ */
+async function buildProjectIndex(input) {
+    const treeSha = input.treeSha ?? (await input.git.headTreeSha());
+    const entries = await input.git.listTree(treeSha);
+    const files = [];
+    const rawSymbols = [];
+    const rawImports = [];
+    for (const entry of entries) {
+        const path = (0, core_1.canonicalPath)(entry.path);
+        const language = (0, core_1.languageOf)(path);
+        const base = {
+            path,
+            blobSha: entry.blobSha,
+            bytes: entry.bytes,
+            language,
+            packageName: packageFor(path, input.packages),
+            isTest: (0, core_1.isTestPath)(path),
+        };
+        if (language !== 'typescript') {
+            files.push({ ...base, status: { kind: 'unparsed', because: 'unsupported-language' } });
+            continue;
+        }
+        if (entry.bytes > exports.MAX_INDEXED_BYTES) {
+            files.push({ ...base, status: { kind: 'unparsed', because: 'too-large' } });
+            continue;
+        }
+        let source;
+        try {
+            source = await input.git.readBlob(entry.blobSha);
+        }
+        catch {
+            // One unreadable blob does not fail the index. It is recorded as a fact
+            // about that file, and every other file is still described.
+            files.push({ ...base, status: { kind: 'unparsed', because: 'unreadable' } });
+            continue;
+        }
+        const { symbols, imports } = extractFrom(path, source);
+        rawSymbols.push(...symbols);
+        rawImports.push(...imports);
+        files.push({ ...base, status: { kind: 'indexed' } });
+    }
+    const known = new Set(files.map((f) => f.path));
+    return {
+        schema: core_1.PROJECT_INDEX_SCHEMA,
+        extractor: core_1.INDEX_EXTRACTOR_VERSION,
+        treeSha,
+        files: (0, core_1.sortFiles)(files),
+        symbols: (0, core_1.sortSymbols)(rawSymbols),
+        imports: (0, core_1.sortImports)(bindImports(rawImports, known)),
+        packages: [...input.packages.map((p) => p.name)].sort(),
+    };
+}
+//# sourceMappingURL=project-index-builder.js.map

package/dist/project-index-builder.js.map

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

package/dist/project-index-facts.d.ts

@@ -0,0 +1,51 @@
+import type { ProjectIndexSnapshot } from '@looply/core';
+import type { MemoryDraft } from './project-memory-store';
+/**
+ * WHAT THE INDEX ESTABLISHES, AS MEMORY A PLANNER CAN READ.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THIS CLOSES TWO GAPS AT ONCE, AND BOTH WERE RECORDED AS KNOWN LIMITS
+ *
+ * Phase 11 froze with `fact` having NO PRODUCTION PRODUCER — the machinery was
+ * proven and unfed, which is exactly the shape Phase 9 shipped and had to fix.
+ * Phase 12 then built an index that nothing consumed. Each was the other's
+ * missing half.
+ *
+ * 🔴 THE DIRECTION IS ONE-WAY AND MUST STAY THAT WAY. The repository produces
+ * the index; the index may produce memory. Memory NEVER produces index truth —
+ * an inference that could become a structural fact would be a model writing the
+ * map, which is the thing both phases are built to prevent.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY SO FEW FACTS
+ *
+ * The index knows about hundreds of files and thousands of symbols. Almost none
+ * of that belongs in memory: memory is BOUNDED, a planner reads a handful of
+ * lines, and flooding it with per-file facts would push out the decisions and
+ * the failed approaches that are the reason it exists.
+ *
+ * So this records only what is true of the PROJECT rather than of a file — the
+ * shape of the workspace, which is small, stable across revisions, and the sort
+ * of thing a plan is actually written against. Per-file questions are what the
+ * index QUERY is for; memory is for what a person would say out loud.
+ */
+/**
+ * A ceiling, not a target.
+ *
+ * If a repository somehow declared fifty packages, the answer is still that a
+ * planner reads a handful of lines. The bound is here rather than at the caller
+ * because a caller that forgot it would flood memory silently.
+ */
+export declare const MAX_INDEX_FACTS = 12;
+/**
+ * The facts the index establishes about a project.
+ *
+ * Every one is:
+ *   - `deterministic`, because it came from committed content, not a model
+ *   - stamped with the tree it was observed at, so it goes stale honestly when
+ *     the repository changes shape
+ *   - about the project rather than about a file, so it stays true long enough
+ *     to be worth remembering
+ */
+export declare function factsFromIndex(snapshot: ProjectIndexSnapshot, projectKey: string): MemoryDraft[];
+//# sourceMappingURL=project-index-facts.d.ts.map

package/dist/project-index-facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-index-facts.d.ts","sourceRoot":"","sources":["../src/project-index-facts.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,oBAAoB,EAC9B,UAAU,EAAE,MAAM,GACjB,WAAW,EAAE,CA2Bf"}

package/dist/project-index-facts.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_INDEX_FACTS = void 0;
+exports.factsFromIndex = factsFromIndex;
+/**
+ * WHAT THE INDEX ESTABLISHES, AS MEMORY A PLANNER CAN READ.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * THIS CLOSES TWO GAPS AT ONCE, AND BOTH WERE RECORDED AS KNOWN LIMITS
+ *
+ * Phase 11 froze with `fact` having NO PRODUCTION PRODUCER — the machinery was
+ * proven and unfed, which is exactly the shape Phase 9 shipped and had to fix.
+ * Phase 12 then built an index that nothing consumed. Each was the other's
+ * missing half.
+ *
+ * 🔴 THE DIRECTION IS ONE-WAY AND MUST STAY THAT WAY. The repository produces
+ * the index; the index may produce memory. Memory NEVER produces index truth —
+ * an inference that could become a structural fact would be a model writing the
+ * map, which is the thing both phases are built to prevent.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * WHY SO FEW FACTS
+ *
+ * The index knows about hundreds of files and thousands of symbols. Almost none
+ * of that belongs in memory: memory is BOUNDED, a planner reads a handful of
+ * lines, and flooding it with per-file facts would push out the decisions and
+ * the failed approaches that are the reason it exists.
+ *
+ * So this records only what is true of the PROJECT rather than of a file — the
+ * shape of the workspace, which is small, stable across revisions, and the sort
+ * of thing a plan is actually written against. Per-file questions are what the
+ * index QUERY is for; memory is for what a person would say out loud.
+ */
+/**
+ * A ceiling, not a target.
+ *
+ * If a repository somehow declared fifty packages, the answer is still that a
+ * planner reads a handful of lines. The bound is here rather than at the caller
+ * because a caller that forgot it would flood memory silently.
+ */
+exports.MAX_INDEX_FACTS = 12;
+/**
+ * The facts the index establishes about a project.
+ *
+ * Every one is:
+ *   - `deterministic`, because it came from committed content, not a model
+ *   - stamped with the tree it was observed at, so it goes stale honestly when
+ *     the repository changes shape
+ *   - about the project rather than about a file, so it stays true long enough
+ *     to be worth remembering
+ */
+function factsFromIndex(snapshot, projectKey) {
+    const revision = { treeSha: snapshot.treeSha };
+    const drafts = [];
+    for (const name of snapshot.packages) {
+        const dir = directoryOf(snapshot, name);
+        if (dir === null)
+            continue;
+        drafts.push({
+            kind: 'fact',
+            source: 'deterministic',
+            subject: `package ${name}`,
+            content: `lives at ${dir}`,
+            /**
+             * The index snapshot is the evidence, named by the revision it describes.
+             * A reader can rebuild that exact index and check the claim, which is what
+             * separates a fact from a sentence.
+             */
+            provenance: { via: 'project-index', refs: [snapshot.treeSha] },
+            // NOT scoped to a path: this is about a package, and a `path` scope would
+            // make it expire whenever that one file changed.
+            scope: { projectKey },
+            revision,
+        });
+        if (drafts.length >= exports.MAX_INDEX_FACTS)
+            break;
+    }
+    return drafts;
+}
+/**
+ * Where a package's files live, derived from the files attributed to it.
+ *
+ * ⚠️ THE COMMON PREFIX OF ITS OWN FILES, NOT A GUESS FROM ITS NAME. A package
+ * called `@looply/core` need not live in `core` — this repository's own
+ * `looply-cli` lives in `packages/cli`, where the name and the directory do not
+ * match at all. Deriving the directory from the name would be right often
+ * enough to look correct and wrong exactly where it matters.
+ */
+function directoryOf(snapshot, packageName) {
+    /**
+     * The DIRECTORIES, not the paths — a test caught this. With a single file,
+     * the common prefix of the full paths is the file itself, and the fact would
+     * read "package X lives at packages/core/src/a.ts", which names a file and
+     * calls it a home.
+     */
+    const mine = snapshot.files
+        .filter((f) => f.packageName === packageName)
+        .map((f) => (f.path.includes('/') ? f.path.slice(0, f.path.lastIndexOf('/')) : ''));
+    if (mine.length === 0)
+        return null;
+    const first = mine[0].split('/');
+    let common = first.length;
+    for (const path of mine) {
+        const parts = path.split('/');
+        let i = 0;
+        while (i < common && i < parts.length && parts[i] === first[i])
+            i += 1;
+        common = i;
+    }
+    // A package whose files share no directory — because they sit at the
+    // repository root, or diverge immediately — is not describable this way.
+    // "lives at " is worse than silence, and "lives at the repository root" is
+    // true and useless.
+    const dir = first.slice(0, common).join('/');
+    return dir === '' ? null : dir;
+}
+//# sourceMappingURL=project-index-facts.js.map

package/dist/project-index-facts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-index-facts.js","sourceRoot":"","sources":["../src/project-index-facts.ts"],"names":[],"mappings":";;;AAoDA,wCA8BC;AA/ED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;GAMG;AACU,QAAA,eAAe,GAAG,EAAE,CAAC;AAElC;;;;;;;;;GASG;AACH,SAAgB,cAAc,CAC5B,QAA8B,EAC9B,UAAkB;IAElB,MAAM,QAAQ,GAAG,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,EAAE,CAAC;IAC/C,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,WAAW,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QACxC,IAAI,GAAG,KAAK,IAAI;YAAE,SAAS;QAC3B,MAAM,CAAC,IAAI,CAAC;YACV,IAAI,EAAE,MAAM;YACZ,MAAM,EAAE,eAAe;YACvB,OAAO,EAAE,WAAW,IAAI,EAAE;YAC1B,OAAO,EAAE,YAAY,GAAG,EAAE;YAC1B;;;;eAIG;YACH,UAAU,EAAE,EAAE,GAAG,EAAE,eAAe,EAAE,IAAI,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;YAC9D,0EAA0E;YAC1E,iDAAiD;YACjD,KAAK,EAAE,EAAE,UAAU,EAAE;YACrB,QAAQ;SACT,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,MAAM,IAAI,uBAAe;YAAE,MAAM;IAC9C,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,WAAW,CAAC,QAA8B,EAAE,WAAmB;IACtE;;;;;OAKG;IACH,MAAM,IAAI,GAAG,QAAQ,CAAC,KAAK;SACxB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,KAAK,WAAW,CAAC;SAC5C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IACtF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAEnC,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAClC,IAAI,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC;IAC1B,KAAK,MAAM,IAAI,IAAI,IAAI,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC9B,IAAI,CAAC,GAAG,CAAC,CAAC;QACV,OAAO,CAAC,GAAG,MAAM,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC;YAAE,CAAC,IAAI,CAAC,CAAC;QACvE,MAAM,GAAG,CAAC,CAAC;IACb,CAAC;IACD,qEAAqE;IACrE,yEAAyE;IACzE,2EAA2E;IAC3E,oBAAoB;IACpB,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7C,OAAO,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC;AACjC,CAAC"}

package/dist/project-index-store.d.ts

@@ -0,0 +1,97 @@
+import { type ProjectIndexSnapshot } from '@looply/core';
+import type { LedgerFs } from './ledger-store';
+/**
+ * THE INDEX ON DISK — `.looply/state/project-index-<tree>.json`.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * 🔴 A CACHE, NOT AN AUTHORITY
+ *
+ * The repository is the truth and this is derived from it. Losing every
+ * snapshot costs a rebuild and nothing else, which is why this store is allowed
+ * to be simpler than the memory ledger: there is no history to protect, no
+ * concurrent writer whose record could be lost, and no claim that outlives its
+ * evidence. If it disagrees with the repository, it is wrong and it is thrown
+ * away.
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * KEYED ON THE TREE, WHICH IS WHAT "INCREMENTAL" MEANS HERE
+ *
+ * The phase permits an incremental rebuild provided its output equals a clean
+ * one. This takes the other road and does not patch a snapshot at all: because
+ * enumeration comes from the git index rather than a directory walk, a full
+ * rebuild is already cheap, and a patching path that must PROVE it equals a
+ * clean rebuild is pure risk for a saving nobody needs.
+ *
+ * So the cache is content-addressed by tree. Same tree, reuse. Different tree,
+ * rebuild whole. There is no third state in which a snapshot describes a mix of
+ * two revisions, which is the failure a patching implementation would have to
+ * work to avoid.
+ *
+ * ⚠️ THIS IS ALSO WHY THERE IS NO FILE WATCHER. A watcher would be an
+ * optimisation whose correctness depended on never missing an event; the tree
+ * sha is a question that can simply be asked, and a missed answer is not
+ * possible.
+ */
+export type IndexStoreState = 'ok' | 'unreadable';
+/**
+ * How many snapshots to keep.
+ *
+ * Small on purpose: a snapshot is worth keeping only while somebody might
+ * still be on that revision, and a rebuild is cheap. The alternative — an
+ * unbounded directory of derived files — is the defect that arrives months
+ * later on somebody else's machine, which this codebase has already met once.
+ */
+export declare const MAX_SNAPSHOTS = 4;
+export declare class ProjectIndexStore {
+    private readonly stateDir;
+    private readonly fs;
+    private state;
+    constructor(stateDir: string, fs: LedgerFs & {
+        readDir?: (path: string) => Promise<string[]>;
+    });
+    private pathFor;
+    status(): IndexStoreState;
+    /**
+     * The snapshot for a tree, or null.
+     *
+     * 🔴 REFUSES A SNAPSHOT THAT DOES NOT DESCRIBE THE TREE ASKED FOR. The file
+     * name says which revision it is, and so does the content; if they disagree,
+     * something copied a file or a write was interrupted, and the honest answer
+     * is "I do not have one" rather than a plausible index of the wrong revision.
+     * A stale index is worse than no index, because a reader cannot tell.
+     */
+    load(treeSha: string, 
+    /**
+     * 🔴 THE PACKAGE SET THE CALLER WILL BUILD WITH, AND WITHOUT IT THIS CACHE
+     * IS KEYED ON LESS THAN THE SNAPSHOT DEPENDS ON.
+     *
+     * Found by an adversarial review during Phase 13, and it is a fourth class
+     * of staleness none of the checks below can see. A snapshot is a function
+     * of (tree, packages) — `run-cmd.ts` builds it with
+     * `workspacePackages(config)`, derived from `config.scope.free`, which is
+     * read from a WORKING-TREE config file that no tree sha covers. That value
+     * reaches the snapshot twice: every file’s `packageName`, and the signed
+     * `packages` array.
+     *
+     * So a person adding a workspace to their config, without committing and
+     * without any code changing, got the previous package set back for ever
+     * under a matching key — and `factsFromIndex` then wrote "package X lives
+     * at Y" from it. No version bump is even conceptually available for that
+     * class: nothing about the CODE changed.
+     *
+     * ⚠️ OPTIONAL, SO EVERY EXISTING CALLER KEEPS WORKING — but a caller that
+     * omits it is asking to be handed a snapshot built under a package set
+     * nobody compared. The two production callers both pass it.
+     */
+    expectedPackages?: readonly string[]): Promise<ProjectIndexSnapshot | null>;
+    /**
+     * Write a snapshot for its own tree.
+     *
+     * Temp-then-rename, so a reader never sees half a file — the same contract
+     * every other durable write in this repository uses, and the reason `load`
+     * can treat unparseable JSON as merely absent rather than as corruption to
+     * reason about.
+     */
+    save(snapshot: ProjectIndexSnapshot): Promise<void>;
+}
+//# sourceMappingURL=project-index-store.d.ts.map

package/dist/project-index-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-index-store.d.ts","sourceRoot":"","sources":["../src/project-index-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,oBAAoB,EAC1B,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,MAAM,eAAe,GAAG,IAAI,GAAG,YAAY,CAAC;AAElD;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,IAAI,CAAC;AAE/B,qBAAa,iBAAiB;IAI1B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,EAAE;IAJrB,OAAO,CAAC,KAAK,CAAyB;gBAGnB,QAAQ,EAAE,MAAM,EAChB,EAAE,EAAE,QAAQ,GAAG;QAAE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;KAAE;IAGnF,OAAO,CAAC,OAAO;IAIf,MAAM,IAAI,eAAe;IAIzB;;;;;;;;OAQG;IACG,IAAI,CACR,OAAO,EAAE,MAAM;IACf;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,gBAAgB,CAAC,EAAE,SAAS,MAAM,EAAE,GACnC,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IA2CvC;;;;;;;OAOG;IACG,IAAI,CAAC,QAAQ,EAAE,oBAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;CAsB1D"}