@crvouga/atlas 0.4.0 → 0.6.0

package/dist/reports/src/completion-order.d.ts

@@ -1,10 +1,23 @@
 /**
- * Run `tasks` at most `limit` at a time and yield each result the moment it
- * settles, so one slow read never holds back faster siblings. A rejection
- * is rethrown to the consumer once every started task has settled.
+ * @module Bounded concurrency
+ *
+ * Small helpers that run async work with a cap on how many tasks are in flight, used for reading and writing many
+ * store objects without flooding the backend. They differ from `Promise.all` in three ways: the cap, results in
+ * completion order (not input order), and failure handling: once one task rejects, no new task is started,
+ * those already started are allowed to finish, and then the first error is rethrown.
+ */
+/**
+ * Runs `tasks` at most `limit` at a time (at least 1) and yields each result the moment it
+ * settles, so one slow read never holds back faster siblings. Results come in completion order, not input
+ * order. A rejection is rethrown to the consumer once every started task has settled; no results are yielded
+ * after the first failure.
  */
 export declare function inCompletionOrder<T>(tasks: readonly (() => Promise<T>)[], limit: number): AsyncGenerator<T>;
-/** Apply `work` to every item, at most `limit` at a time. */
+/** Applies `work` to every item, at most `limit` at a time, and resolves when all are done; rejects with the first error as {@link inCompletionOrder} does. */
 export declare function eachLimited<T>(items: readonly T[], limit: number, work: (item: T) => Promise<void>): Promise<void>;
-/** Consume a lazy input with backpressure, draining started work before failure. */
+/**
+ * Consumes a lazy (async) input with backpressure: it pulls the next item only while fewer than `limit` works are
+ * running, so a huge or generated input is never held in memory at once. After a failure it stops pulling,
+ * waits for the started work to settle, then rethrows the first error.
+ */
 export declare function eachLimitedStream<T>(items: AsyncIterable<T>, limit: number, work: (item: T) => Promise<void>): Promise<void>;

package/dist/reports/src/completion-order.js

@@ -1,7 +1,16 @@
 /**
- * Run `tasks` at most `limit` at a time and yield each result the moment it
- * settles, so one slow read never holds back faster siblings. A rejection
- * is rethrown to the consumer once every started task has settled.
+ * @module Bounded concurrency
+ *
+ * Small helpers that run async work with a cap on how many tasks are in flight, used for reading and writing many
+ * store objects without flooding the backend. They differ from `Promise.all` in three ways: the cap, results in
+ * completion order (not input order), and failure handling: once one task rejects, no new task is started,
+ * those already started are allowed to finish, and then the first error is rethrown.
+ */
+/**
+ * Runs `tasks` at most `limit` at a time (at least 1) and yields each result the moment it
+ * settles, so one slow read never holds back faster siblings. Results come in completion order, not input
+ * order. A rejection is rethrown to the consumer once every started task has settled; no results are yielded
+ * after the first failure.
  */
 export async function* inCompletionOrder(tasks, limit) {
     const width = Math.max(1, Math.floor(limit));
@@ -42,14 +51,18 @@ export async function* inCompletionOrder(tasks, limit) {
     if (outcome.failure !== null)
         throw outcome.failure.error;
 }
-/** Apply `work` to every item, at most `limit` at a time. */
+/** Applies `work` to every item, at most `limit` at a time, and resolves when all are done; rejects with the first error as {@link inCompletionOrder} does. */
 export async function eachLimited(items, limit, work) {
     const tasks = items.map((item) => () => work(item));
     for await (const _ of inCompletionOrder(tasks, limit)) {
         // Results are void; draining is the point.
     }
 }
-/** Consume a lazy input with backpressure, draining started work before failure. */
+/**
+ * Consumes a lazy (async) input with backpressure: it pulls the next item only while fewer than `limit` works are
+ * running, so a huge or generated input is never held in memory at once. After a failure it stops pulling,
+ * waits for the started work to settle, then rethrows the first error.
+ */
 export async function eachLimitedStream(items, limit, work) {
     const width = Math.max(1, Math.floor(limit));
     const running = new Set();

package/dist/reports/src/compose.d.ts

@@ -0,0 +1,80 @@
+import type { BackendInfo, LayerHeader, StatusCounts } from './evidence-types.js';
+import { type CombinedEvidence, type EvidenceResult } from './layer-merge.js';
+import type { ReportOutline } from './layer-types.js';
+import type { ObjectStore } from './object-store.js';
+/** A store that contributes layers. Any {@link ObjectStore} is one: a directory, a bucket, a device lab. */
+export type BackendInput = {
+    /** Stable and unique: lowercase letters, digits and hyphens. It names where a result came from. */
+    readonly id: string;
+    /** What a person sees in notices and in the viewer. Defaults to `id`. */
+    readonly label?: string;
+    /** Where the layers are. Only read from. */
+    readonly store: ObjectStore;
+};
+/** Options of {@link combineBackends}. */
+export type CombineOptions = {
+    /** The specs the report is laid out against. When omitted, the specs the layers recorded. */
+    readonly outline?: ReportOutline;
+    /** Layers read at once, across all backends. Default 16. */
+    readonly concurrency?: number;
+    /**
+     * Leave layers out, to see what earlier ones said (a layer for which this returns false takes no part: not in the
+     * results, the layer list, the counts, or the recorded specs). Layers are still read; this filters after reading.
+     */
+    readonly include?: (layer: LayerHeader) => boolean;
+};
+/** What a report says in numbers. Timings that only qualify a check are not counted as checks. */
+export type ReportSummary = {
+    /** Counts of the winning results by status, and their total. */
+    readonly checks: StatusCounts & {
+        readonly total: number;
+    };
+    /** The same counts per environment slug, keys sorted; results with no environment are under `unspecified`. */
+    readonly byEnvironment: Readonly<Record<string, StatusCounts & {
+        readonly total: number;
+    }>>;
+    /** Specs in the outline with no result at all. */
+    readonly specsWithoutEvidence: readonly string[];
+};
+/** A report: the results laid over the specs, with what was read and what could not be. */
+export type CombinedReport = {
+    /** Every spec in the outline with the winning result of each of its slots, plus results that belong to no spec in the outline. */
+    readonly combined: CombinedEvidence;
+    /** Every distinct layer that was read, newest first. A layer several backends hold is one layer. */
+    readonly layers: readonly LayerHeader[];
+    /** Every backend given, sorted by id, with whether it could be read. */
+    readonly backends: readonly BackendInfo[];
+    /** What could not be read. A gate treats any of these as unknown, never as a pass. */
+    readonly notices: readonly string[];
+    /** The numbers of `combined`, computed once for the gate and the viewer. */
+    readonly summary: ReportSummary;
+};
+/**
+ * Counts results by status. Diagnostic results (parts of kind `performance`, which only qualify a check) are left out
+ * whenever any other result is present; if only diagnostics exist, they are counted so the report is not empty.
+ */
+export declare function countResults(results: readonly EvidenceResult[]): StatusCounts & {
+    total: number;
+};
+/** Counts a combined report's winning results in total and per environment, and lists the specs that have no result at all. */
+export declare function summarize(combined: CombinedEvidence): ReportSummary;
+/**
+ * Reads every layer of every backend and lays them over the specs. Layers are the only input:
+ * a report is a function of the set of layers, so the order of backends and layers, and how they
+ * were split across machines, branches and runs, does not change it.
+ *
+ * A backend that cannot be read, or a layer that cannot be understood, is named in `notices` and
+ * leaves everything else usable; a gate must treat any notice as unknown, never as a pass. A layer held by
+ * several backends is one layer. Only an invalid backend `id` (not lowercase letters, digits and hyphens, or
+ * repeated) throws, before anything is read. Backends are only read from.
+ *
+ * When `options.outline` is omitted, the specs are the ones the included layers recorded (the newest
+ * recording of each spec path wins), with no commit sha.
+ *
+ * @example
+ * const outline = await loadDirectoryOutline('./specs'); // optional: without it the layers' own specs are used
+ * const report = await combineBackends([{ id: 'ci', store: directoryStore('./atlas-reports') }], { outline });
+ * report.summary.checks.failed; // number of slots whose winner failed
+ * report.notices; // non-empty means something could not be read
+ */
+export declare function combineBackends(backends: readonly BackendInput[], options?: CombineOptions): Promise<CombinedReport>;

package/dist/reports/src/compose.js

@@ -0,0 +1,117 @@
+/**
+ * @module Combining backends into one report
+ *
+ * The entry point that turns stores of layers into a report: it reads every layer from every {@link BackendInput},
+ * lays them over the specs, and counts the outcome. It owns reading and failure reporting (an unreadable backend or
+ * layer becomes a notice, never a pass); the rule for which result wins a slot lives in `layer-merge.ts`. A report
+ * is computed, never stored, and is a function of the set of layers: the order and split of backends does not
+ * change it.
+ *
+ * @see docs/report-contract.md (how layers compose, guarantees)
+ */
+import { eachLimited } from './completion-order.js';
+import { catalogEntries, catalogLayers } from './layer-catalog.js';
+import { combineEvidence, distinctHeaders, emptyCounts, isDiagnosticKind, layerEvidence, specPath } from './layer-merge.js';
+const BACKEND_ID = /^[a-z0-9-]+$/;
+/**
+ * Counts results by status. Diagnostic results (parts of kind `performance`, which only qualify a check) are left out
+ * whenever any other result is present; if only diagnostics exist, they are counted so the report is not empty.
+ */
+export function countResults(results) {
+    const outcomes = results.some(result => !isDiagnosticKind(result.row.kind)) ? results.filter(result => !isDiagnosticKind(result.row.kind)) : results;
+    const counts = emptyCounts();
+    for (const result of outcomes)
+        counts[result.row.status] += 1;
+    return { ...counts, total: outcomes.length };
+}
+/** Counts a combined report's winning results in total and per environment, and lists the specs that have no result at all. */
+export function summarize(combined) {
+    const results = [...combined.specs.flatMap(entry => entry.results), ...combined.unassigned];
+    const environments = new Map();
+    for (const result of results) {
+        const key = result.layer.environment ?? 'unspecified';
+        const group = environments.get(key);
+        if (group)
+            group.push(result);
+        else
+            environments.set(key, [result]);
+    }
+    return {
+        checks: countResults(results),
+        byEnvironment: Object.fromEntries([...environments].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([key, value]) => [key, countResults(value)])),
+        specsWithoutEvidence: combined.specs.filter(entry => entry.results.length === 0).map(entry => entry.spec.path)
+    };
+}
+/**
+ * Reads every layer of every backend and lays them over the specs. Layers are the only input:
+ * a report is a function of the set of layers, so the order of backends and layers, and how they
+ * were split across machines, branches and runs, does not change it.
+ *
+ * A backend that cannot be read, or a layer that cannot be understood, is named in `notices` and
+ * leaves everything else usable; a gate must treat any notice as unknown, never as a pass. A layer held by
+ * several backends is one layer. Only an invalid backend `id` (not lowercase letters, digits and hyphens, or
+ * repeated) throws, before anything is read. Backends are only read from.
+ *
+ * When `options.outline` is omitted, the specs are the ones the included layers recorded (the newest
+ * recording of each spec path wins), with no commit sha.
+ *
+ * @example
+ * const outline = await loadDirectoryOutline('./specs'); // optional: without it the layers' own specs are used
+ * const report = await combineBackends([{ id: 'ci', store: directoryStore('./atlas-reports') }], { outline });
+ * report.summary.checks.failed; // number of slots whose winner failed
+ * report.notices; // non-empty means something could not be read
+ */
+export async function combineBackends(backends, options = {}) {
+    const seen = new Set();
+    for (const backend of backends) {
+        if (!BACKEND_ID.test(backend.id) || seen.has(backend.id))
+            throw new Error(`Invalid report backend id: "${backend.id}". Use unique lowercase letters, digits and hyphens`);
+        seen.add(backend.id);
+    }
+    const notices = [];
+    const info = [];
+    const entries = [];
+    await Promise.all(backends.map(async (backend) => {
+        try {
+            for (const entry of await catalogEntries(backend.store))
+                entries.push({ backend, entry });
+            info.push({ id: backend.id, label: backend.label ?? backend.id, live: false, available: true });
+        }
+        catch (error) {
+            info.push({ id: backend.id, label: backend.label ?? backend.id, live: false, available: false });
+            notices.push(`${backend.label ?? backend.id} is unavailable: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }));
+    entries.sort((a, b) => (a.backend.id < b.backend.id ? -1 : a.backend.id > b.backend.id ? 1 : a.entry < b.entry ? -1 : a.entry > b.entry ? 1 : 0));
+    const loaded = [];
+    await eachLimited(entries, options.concurrency ?? 16, async ({ backend, entry }) => {
+        try {
+            for (const summary of await catalogLayers(backend.store, entry)) {
+                loaded.push({ evidence: layerEvidence(summary, backend.id), specs: summary.specs });
+            }
+        }
+        catch (error) {
+            notices.push(`${backend.label ?? backend.id}: a layer could not be read, so its outcome is unknown (${error instanceof Error ? error.message : String(error)})`);
+        }
+    });
+    const include = options.include;
+    const kept = include ? loaded.filter(item => include(item.evidence.layer)) : loaded;
+    const layers = kept.map(item => item.evidence);
+    // The specs a report is laid over come from the layers that are in it, not from ones left out.
+    const recorded = new Map();
+    if (!options.outline) {
+        for (const { evidence, specs } of kept) {
+            for (const spec of specs) {
+                const key = specPath(spec.path);
+                const prior = recorded.get(key);
+                const at = evidence.layer.recordedAtMs;
+                if (!prior || at > prior.at || (at === prior.at && (spec.fingerprint ?? '') > (prior.entry.fingerprint ?? '')))
+                    recorded.set(key, { entry: { ...spec, path: key }, at });
+            }
+        }
+    }
+    const outline = options.outline ?? { specs: [...recorded.values()].map(item => item.entry).sort((a, b) => (a.path < b.path ? -1 : 1)), sha: null, changedFiles: [] };
+    const combined = combineEvidence(outline, layers);
+    const headers = distinctHeaders(layers.map(evidence => evidence.layer)).sort((a, b) => b.recordedAtMs - a.recordedAtMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+    return { combined, layers: headers, backends: info.sort((a, b) => (a.id < b.id ? -1 : 1)), notices: [...new Set(notices)].sort(), summary: summarize(combined) };
+}

package/dist/reports/src/copy-store.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @module Copying layers between stores
+ *
+ * `copyStore` copies the layers one store has and another lacks: how partial reports meet (each CI node publishes to its own
+ * store; copying them together is the aggregate). It is idempotent, commutative and safe to repeat, because layers are
+ * immutable and named by their content, and it writes in dependency order (files, then documents, then catalog entries) so a
+ * reader of the destination, or a server that checks, never sees something before what it names.
+ *
+ * @see docs/report-contract.md
+ */
+import type { ObjectStore } from './object-store.js';
+/**
+ * Copy every layer object (`layers/…`) of `from` that `to` does not have. Only layers: they are
+ * immutable, so an object that exists is already right. Commit-keyed legacy objects are mutable and
+ * are left where they are. This is how partial reports meet: each CI
+ * node publishes into its own store, and copying them together is the aggregate, because layers are
+ * immutable, addressed by content, and never share a key with different bytes. It is idempotent,
+ * commutative and safe to repeat after a failure.
+ *
+ * A layer's catalog entry is copied last, and its manifest after its files, so a reader of `to` never sees an
+ * entry for a layer whose content has not arrived.
+ */
+export declare function copyStore(from: ObjectStore, to: ObjectStore, options?: {
+    readonly concurrency?: number;
+}): Promise<{
+    readonly copied: number;
+    readonly skipped: number;
+    readonly ignored: number;
+}>;

package/dist/reports/src/copy-store.js

@@ -0,0 +1,52 @@
+/**
+ * @module Copying layers between stores
+ *
+ * `copyStore` copies the layers one store has and another lacks: how partial reports meet (each CI node publishes to its own
+ * store; copying them together is the aggregate). It is idempotent, commutative and safe to repeat, because layers are
+ * immutable and named by their content, and it writes in dependency order (files, then documents, then catalog entries) so a
+ * reader of the destination, or a server that checks, never sees something before what it names.
+ *
+ * @see docs/report-contract.md
+ */
+import { eachLimited } from './completion-order.js';
+import { readBytes } from './object-io.js';
+/**
+ * What is copied after what it names, so a reader (or a server that checks) never sees one without its content:
+ * files first, then the documents that name files (a layer's manifest, a spec set, a run's manifest), then the
+ * catalog entries that make a document visible.
+ */
+const isCatalog = (key) => key.includes('/index/');
+const isDocument = (key) => /^layers\/(manifests\/|specs\/sets\/|runs\/[^/]+\/manifest\.json$)/.test(key);
+/**
+ * Copy every layer object (`layers/…`) of `from` that `to` does not have. Only layers: they are
+ * immutable, so an object that exists is already right. Commit-keyed legacy objects are mutable and
+ * are left where they are. This is how partial reports meet: each CI
+ * node publishes into its own store, and copying them together is the aggregate, because layers are
+ * immutable, addressed by content, and never share a key with different bytes. It is idempotent,
+ * commutative and safe to repeat after a failure.
+ *
+ * A layer's catalog entry is copied last, and its manifest after its files, so a reader of `to` never sees an
+ * entry for a layer whose content has not arrived.
+ */
+export async function copyStore(from, to, options = {}) {
+    const everything = await from.listKeys();
+    const keys = everything.filter(key => key.startsWith('layers/'));
+    const width = options.concurrency ?? 16;
+    let copied = 0, skipped = 0;
+    const copy = async (key) => {
+        if (await to.head(key)) {
+            skipped += 1;
+            return;
+        }
+        const stored = await from.get(key);
+        if (!stored)
+            return;
+        await to.put(key, await readBytes(stored.body), stored.contentType);
+        copied += 1;
+    };
+    await eachLimited(keys.filter(key => !isCatalog(key) && !isDocument(key)), width, copy);
+    await eachLimited(keys.filter(key => !isCatalog(key) && isDocument(key)), width, copy);
+    await eachLimited(keys.filter(isCatalog), width, copy);
+    // Said, not silent: whatever is not a layer was left where it is.
+    return { copied, skipped, ignored: everything.length - keys.length };
+}

package/dist/reports/src/directory-outline.d.ts

@@ -0,0 +1,38 @@
+import type { ReportOutline } from './layer-types.js';
+/** Every file the viewer reads from a specs directory: charts, journeys, notations and notes. */
+export declare function isSpecFile(file: string): boolean;
+/** The notation of a spec file. Anything else is named by its extension. */
+export declare function specKindOf(file: string): string;
+/** The title of a spec: the `Feature:` line of a `.feature`, the `module` name of a `.qnt`, otherwise the file's base name. */
+export declare function specTitleOf(file: string, text: string): string;
+/** One spec file: its `specs/<relative path>` name and its UTF-8 text. */
+export type SpecFileText = {
+    readonly path: string;
+    readonly text: string;
+};
+/**
+ * The spec files of a directory, named `specs/<path inside it>`: the one definition of what a spec is,
+ * shared by the outline a report is laid over and by the specs that are published. Hidden files and
+ * folders, `node_modules`, `dist`, files over 2 MiB and files of other types (pictures, build output) are
+ * left out. Sorted by path. Rejects if `directory` does not exist.
+ */
+export declare function collectSpecFiles(directory: string): Promise<SpecFileText[]>;
+/**
+ * The specs of a directory as the outline a report is laid over. Each spec is named
+ * `specs/<its path inside the directory>`: that is the `specPath` a check uses to say which spec it
+ * belongs to. `domain` groups specs in the viewer; it defaults to the project's folder name.
+ *
+ * `repoRoot` is where `git rev-parse HEAD` is asked for the outline's `sha` (default: `directory`); the `sha` is
+ * null outside git. `changedFiles` is always empty. The returned `readSpec(specPath)` answers the text read here,
+ * or null for a path that is not in the outline.
+ *
+ * @example
+ * const outline = await loadDirectoryOutline('./specs', { repoRoot: process.cwd() });
+ * outline.specs.map(spec => spec.path); // ['specs/join.feature', ...]
+ */
+export declare function loadDirectoryOutline(directory: string, options?: {
+    readonly domain?: string;
+    readonly repoRoot?: string;
+}): Promise<ReportOutline & {
+    readSpec: (specPath: string) => Promise<string | null>;
+}>;

package/dist/reports/src/directory-outline.js

@@ -0,0 +1,103 @@
+/**
+ * @module Spec outline from a directory
+ *
+ * Defines what a spec file is and reads a specs directory into the outline a report is laid over: one entry per
+ * spec, named `specs/<path inside the directory>`, with its notation, title and a fingerprint of its text. The same
+ * definition feeds the specs that are published, so the outline and the published spec set agree. Node-only
+ * (reads the file system and asks `git` for the commit); nothing is written.
+ *
+ * @see docs/report-contract.md (the layer document's `specs`, and `specPath`)
+ */
+import { execFile } from 'node:child_process';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { isStatechartFile } from '../../schema/src/spec.js';
+import { textFingerprint } from './layer-merge.js';
+const exec = promisify(execFile);
+const SKIPPED = new Set(['node_modules', 'dist', '.git', '.cache']);
+const MAX_BYTES = 2 * 1024 * 1024;
+/** Every file the viewer reads from a specs directory: charts, journeys, notations and notes. */
+export function isSpecFile(file) {
+    return /\.scxml$/i.test(file) || /(^|\/)([\w.-]+\.)?machine\.(ya?ml|json)$/.test(file) || isStatechartFile(file) || /\.(feature|qnt|dmn|als|md|ya?ml|json|xml|csv|txt)$/i.test(file);
+}
+/** The notation of a spec file. Anything else is named by its extension. */
+export function specKindOf(file) {
+    if (/\.feature$/i.test(file))
+        return 'gherkin';
+    if (/\.qnt$/i.test(file))
+        return 'quint';
+    if (/\.dmn$/i.test(file))
+        return 'dmn';
+    if (/\.als$/i.test(file))
+        return 'alloy';
+    if (/\.openslo\.ya?ml$/i.test(file))
+        return 'openslo';
+    const extension = file.split('.').at(-1);
+    return extension && extension !== file ? extension.toLowerCase() : 'document';
+}
+/** The title of a spec: the `Feature:` line of a `.feature`, the `module` name of a `.qnt`, otherwise the file's base name. */
+export function specTitleOf(file, text) {
+    if (/\.feature$/i.test(file))
+        return /^\s*Feature:\s*(.+)$/m.exec(text)?.[1]?.trim() || path.posix.basename(file);
+    if (/\.qnt$/i.test(file))
+        return /^\s*module\s+(\w+)/m.exec(text)?.[1] || path.posix.basename(file);
+    return path.posix.basename(file);
+}
+/**
+ * The spec files of a directory, named `specs/<path inside it>`: the one definition of what a spec is,
+ * shared by the outline a report is laid over and by the specs that are published. Hidden files and
+ * folders, `node_modules`, `dist`, files over 2 MiB and files of other types (pictures, build output) are
+ * left out. Sorted by path. Rejects if `directory` does not exist.
+ */
+export async function collectSpecFiles(directory) {
+    const root = path.resolve(directory);
+    const found = [];
+    async function walk(dir) {
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            if (entry.name.startsWith('.') || SKIPPED.has(entry.name))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory())
+                await walk(full);
+            else if (entry.isFile()) {
+                const relative = path.relative(root, full).split(path.sep).join('/');
+                if (isSpecFile(relative) && (await stat(full)).size <= MAX_BYTES)
+                    found.push({ path: `specs/${relative}`, text: await readFile(full, 'utf8') });
+            }
+        }
+    }
+    await walk(root);
+    return found.sort((a, b) => (a.path < b.path ? -1 : 1));
+}
+async function git(cwd, args) {
+    try {
+        return (await exec('git', args, { cwd })).stdout.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The specs of a directory as the outline a report is laid over. Each spec is named
+ * `specs/<its path inside the directory>`: that is the `specPath` a check uses to say which spec it
+ * belongs to. `domain` groups specs in the viewer; it defaults to the project's folder name.
+ *
+ * `repoRoot` is where `git rev-parse HEAD` is asked for the outline's `sha` (default: `directory`); the `sha` is
+ * null outside git. `changedFiles` is always empty. The returned `readSpec(specPath)` answers the text read here,
+ * or null for a path that is not in the outline.
+ *
+ * @example
+ * const outline = await loadDirectoryOutline('./specs', { repoRoot: process.cwd() });
+ * outline.specs.map(spec => spec.path); // ['specs/join.feature', ...]
+ */
+export async function loadDirectoryOutline(directory, options = {}) {
+    const root = path.resolve(directory);
+    const files = await collectSpecFiles(root);
+    const texts = new Map(files.map(file => [file.path, file.text]));
+    const domain = options.domain ?? (path.basename(options.repoRoot ?? root) || 'product');
+    const specs = files.map(file => ({ path: file.path, domain, kind: specKindOf(file.path), title: specTitleOf(file.path, file.text), fingerprint: textFingerprint(file.text) }));
+    const cwd = options.repoRoot ?? root;
+    const sha = await git(cwd, ['rev-parse', 'HEAD']);
+    return { specs, sha: sha && /^[0-9a-f]{40}$/.test(sha) ? sha : null, changedFiles: [], readSpec: async (specPath) => texts.get(specPath) ?? null };
+}

package/dist/reports/src/directory-store.d.ts

@@ -0,0 +1,20 @@
+import type { ObjectStore, PagedListing } from './object-store.js';
+/**
+ * Creates an {@link ObjectStore} on a directory: one file per key, its content type in a sidecar file. The
+ * backend for a CI workspace, a downloaded artifact or a laptop. Writes are atomic, listing reads
+ * only the directories a prefix can reach, and two stores over copies of the same layers can be
+ * merged with `cp -R` because layers are immutable and addressed by content.
+ *
+ * The directory need not exist yet: `put` creates it, and `get`/`head`/`listKeys` on a missing one answer
+ * null/false/`[]`. A missing sidecar reads as `application/octet-stream`. `put` writes the content type before
+ * the bytes, so an object is never visible without its type. `listKeys` returns keys in code-unit order, skips
+ * temporary and sidecar files, and throws on a prefix that is absolute, contains a backslash or `..`. `getUri`
+ * is a `file://` URL. Also implements `listPage` (`after` is exclusive, `limit` defaults to 1000, `next` is the
+ * last returned key while more remain).
+ *
+ * @example
+ * const store = directoryStore('./atlas-reports');
+ * await store.put('layers/blobs/x', new TextEncoder().encode('hi'), 'text/plain');
+ * await store.listKeys('layers/'); // ['layers/blobs/x']
+ */
+export declare function directoryStore(root: string): ObjectStore & PagedListing;