@crvouga/atlas 0.3.0 → 0.5.0

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;

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

@@ -0,0 +1,166 @@
+/**
+ * @module Directory-backed object store
+ *
+ * The {@link ObjectStore} implementation for a local folder: a CI workspace, a downloaded artifact, a mount or a
+ * laptop. Each key is a file under the root; its content type is kept in a sidecar `<key>.content-type`. Writes go
+ * to a temporary `.tmp-*` file and are renamed into place so a reader sees all of an object or none of it. Keys
+ * that could escape the root (`..`, absolute, backslash, empty segments) or collide with the sidecar or temporary
+ * names are rejected with an error. Node/Bun only.
+ *
+ * @see docs/report-contract.md (backends)
+ */
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ObjectStoreWithPrefix } from './store-prefix.js';
+const TYPE_SUFFIX = '.content-type';
+const TEMP_PREFIX = '.tmp-';
+function rejectKey(key) {
+    const parts = key.split('/');
+    const last = parts.at(-1) ?? '';
+    if (key.length === 0 || key.startsWith('/') || key.includes('\\') || parts.some((part) => part.length === 0 || part === '.' || part === '..') || last.endsWith(TYPE_SUFFIX) || last.startsWith(TEMP_PREFIX)) {
+        throw new Error(`Invalid object store key: ${key}`);
+    }
+}
+function fileOf(root, key) {
+    rejectKey(key);
+    const rootPath = path.resolve(root);
+    const file = path.resolve(rootPath, key);
+    if (file !== rootPath && !file.startsWith(rootPath + path.sep))
+        throw new Error(`Invalid object store key: ${key}`);
+    return file;
+}
+function missing(error) {
+    const code = error.code;
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+let counter = 0;
+/** Write beside the target and rename into place: a reader sees the whole object or none of it. */
+async function writeAtomically(file, bytes) {
+    const temporary = path.join(path.dirname(file), `${TEMP_PREFIX}${process.pid}-${Date.now().toString(36)}-${(counter += 1).toString(36)}`);
+    try {
+        await writeFile(temporary, bytes);
+        await rename(temporary, file);
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+/**
+ * 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 function directoryStore(root) {
+    const store = {
+        async get(key) {
+            const file = fileOf(root, key);
+            try {
+                // The type is beside the object: both are asked for at once.
+                const [content, contentType] = await Promise.all([readFile(file), readFile(file + TYPE_SUFFIX, 'utf8').catch(() => 'application/octet-stream')]);
+                const bytes = content;
+                return {
+                    body: new ReadableStream({
+                        start(controller) {
+                            controller.enqueue(bytes);
+                            controller.close();
+                        }
+                    }),
+                    contentType: contentType.trim() || 'application/octet-stream',
+                    size: bytes.byteLength
+                };
+            }
+            catch (error) {
+                if (missing(error))
+                    return null;
+                throw error;
+            }
+        },
+        async put(key, bytes, contentType) {
+            const file = fileOf(root, key);
+            await mkdir(path.dirname(file), { recursive: true });
+            // The type first: an object is never visible without it.
+            await writeAtomically(file + TYPE_SUFFIX, contentType);
+            await writeAtomically(file, bytes);
+        },
+        async head(key) {
+            try {
+                return (await stat(fileOf(root, key))).isFile();
+            }
+            catch (error) {
+                if (missing(error))
+                    return false;
+                throw error;
+            }
+        },
+        async delete(key) {
+            const file = fileOf(root, key);
+            await rm(file, { force: true });
+            await rm(file + TYPE_SUFFIX, { force: true });
+        },
+        async deleteMany(keys) {
+            for (const key of keys)
+                await store.delete(key);
+        },
+        async getUri(key) {
+            return (await store.head(key)) ? pathToFileURL(fileOf(root, key)).href : null;
+        },
+        async listKeys(prefix = '') {
+            const rootPath = path.resolve(root);
+            const found = [];
+            const walk = async (dir) => {
+                let entries;
+                try {
+                    entries = await readdir(dir, { withFileTypes: true });
+                }
+                catch (error) {
+                    if (missing(error))
+                        return;
+                    throw error;
+                }
+                await Promise.all(entries.map(async (entry) => {
+                    if (entry.name.startsWith(TEMP_PREFIX) || entry.name.endsWith(TYPE_SUFFIX))
+                        return;
+                    const full = path.join(dir, entry.name);
+                    if (entry.isDirectory())
+                        return walk(full);
+                    if (!entry.isFile())
+                        return;
+                    const key = path.relative(rootPath, full).split(path.sep).join('/');
+                    if (key.startsWith(prefix))
+                        found.push(key);
+                }));
+            };
+            // Only the directory a prefix names can hold its keys.
+            const slash = prefix.lastIndexOf('/');
+            if (prefix.startsWith('/') || prefix.includes('\\') || prefix.split('/').some((part) => part === '..'))
+                throw new Error(`Invalid object store prefix: ${prefix}`);
+            await walk(slash < 0 ? rootPath : path.resolve(rootPath, prefix.slice(0, slash)));
+            return found.sort();
+        },
+        async listPage(prefix, options = {}) {
+            const all = await store.listKeys(prefix);
+            const from = options.after === undefined ? 0 : all.findIndex(key => key > options.after);
+            const keys = from < 0 ? [] : all.slice(from, from + (options.limit ?? 1000));
+            return { keys, next: from >= 0 && from + keys.length < all.length ? keys.at(-1) ?? null : null };
+        },
+        withPrefix(prefix) {
+            return new ObjectStoreWithPrefix(store, prefix);
+        }
+    };
+    return store;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * @module Store doctor and IAM policy
+ *
+ * `inspectStore` checks that a store works end to end (credentials, listing, what it holds, writing and reading back a
+ * scratch object) and says what to fix when it does not; `iamPolicy` prints the least-privilege AWS policy for publishers
+ * and readers. Used by `atlas report doctor` and `atlas report policy`, for folders, S3-compatible buckets and Atlas
+ * servers alike.
+ *
+ * @see docs/deploying.md
+ */
+import type { CliBackend } from './cli-stores.js';
+/** One thing `inspectStore` checked: its `name` (`store`, `list`, `contents`, `write`, …), whether it is `ok`, what was seen, and, when it is not, what to `fix`. */
+export type Check = {
+    readonly ok: boolean;
+    readonly name: string;
+    readonly detail: string;
+    readonly fix?: string;
+};
+/** The least an account needs, as an AWS IAM policy. R2, MinIO and the rest have their own policy languages: grant the same actions. */
+export declare function iamPolicy(location: {
+    bucket: string;
+    prefix: string;
+}, role: 'publisher' | 'reader' | 'both'): object;
+/** What the account being checked is for: `publisher` (writes layers), `reader` (reads them) or `both`. It decides which checks run. */
+export type Role = 'publisher' | 'reader' | 'both';
+/** Is this store usable for Atlas, and if not, what exactly is wrong? Each step says what to do. */
+export declare function inspectStore(backend: CliBackend, options?: {
+    readonly role?: Role;
+}): Promise<Check[]>;

package/dist/reports/src/doctor.js

@@ -0,0 +1,83 @@
+/**
+ * @module Store doctor and IAM policy
+ *
+ * `inspectStore` checks that a store works end to end (credentials, listing, what it holds, writing and reading back a
+ * scratch object) and says what to fix when it does not; `iamPolicy` prints the least-privilege AWS policy for publishers
+ * and readers. Used by `atlas report doctor` and `atlas report policy`, for folders, S3-compatible buckets and Atlas
+ * servers alike.
+ *
+ * @see docs/deploying.md
+ */
+import { LAYER_INDEX } from './layer-store.js';
+import { verifyObjectStore } from './object-store-conformance.js';
+/** The least an account needs, as an AWS IAM policy. R2, MinIO and the rest have their own policy languages: grant the same actions. */
+export function iamPolicy(location, role) {
+    const base = location.prefix ? `${location.prefix}/` : '';
+    const bucketArn = `arn:aws:s3:::${location.bucket}`;
+    const statements = [];
+    if (role !== 'reader') {
+        statements.push({ Sid: 'AtlasPublish', Effect: 'Allow', Action: ['s3:PutObject', 's3:GetObject'], Resource: `${bucketArn}/${base}layers/*` }, { Sid: 'AtlasDoctorCleanup', Effect: 'Allow', Action: 's3:DeleteObject', Resource: `${bucketArn}/${base}layers/doctor-*` });
+    }
+    if (role !== 'publisher') {
+        statements.push({ Sid: 'AtlasRead', Effect: 'Allow', Action: 's3:GetObject', Resource: `${bucketArn}/${base}layers/*` });
+    }
+    // Publishers need this too: without it S3 answers 403, not 404, when asked whether a layer exists yet.
+    statements.push({ Sid: 'AtlasList', Effect: 'Allow', Action: 's3:ListBucket', Resource: bucketArn, // IfExists: a listing always carries a prefix and is held to it; a HEAD or GET of one object carries none, and
+        // must still be answered "not found" rather than "forbidden".
+        ...(base ? { Condition: { StringLikeIfExists: { 's3:prefix': [base, `${base}*`] } } } : {}) });
+    return { Version: '2012-10-17', Statement: statements };
+}
+const when = (inverted) => {
+    const time = inverted ? Number.MAX_SAFE_INTEGER - Number(inverted) : NaN;
+    return Number.isFinite(time) ? new Date(time).toISOString() : 'unknown';
+};
+/** Is this store usable for Atlas, and if not, what exactly is wrong? Each step says what to do. */
+export async function inspectStore(backend, options = {}) {
+    const role = options.role ?? 'both';
+    const checks = [];
+    const add = (check) => { checks.push(check); return check.ok; };
+    const store = backend.store;
+    const s3 = backend.s3;
+    add({ ok: true, name: 'store', detail: s3?.label ?? backend.label ?? backend.id });
+    if (s3 && role !== 'publisher') {
+        const ping = await s3.ping();
+        add(ping.ok
+            ? { ok: true, name: 'list', detail: `${ping.ms} ms${s3.credentialSource() ? `, credentials from ${s3.credentialSource()}` : ''}` }
+            : { ok: false, name: 'list', detail: ping.error ?? 'failed', fix: 'Check the bucket, region and endpoint in the store URL, and the credentials. `atlas report policy --store <url>` prints the permissions needed.' });
+        if (!ping.ok)
+            return checks;
+    }
+    if (role !== 'publisher') {
+        try {
+            const keys = await store.listKeys(LAYER_INDEX);
+            const [sets, runs] = await Promise.all([store.listKeys('layers/specs/index/'), store.listKeys('layers/runs/index/')]);
+            add({ ok: true, name: 'contents', detail: `${keys.length} layer${keys.length === 1 ? '' : 's'}${keys.length ? ` (newest ${when(/\/(\d{16})-/.exec(keys[0])?.[1])})` : ''}, ${sets.length} spec set${sets.length === 1 ? '' : 's'}, ${runs.length} run${runs.length === 1 ? '' : 's'}` });
+        }
+        catch (error) {
+            add({ ok: false, name: 'contents', detail: error instanceof Error ? error.message : String(error) });
+            return checks;
+        }
+    }
+    if (role === 'reader')
+        return checks;
+    const scratch = `layers/doctor-${Math.random().toString(36).slice(2, 10)}/`;
+    if (role === 'both') {
+        const verification = await verifyObjectStore(store, scratch);
+        add(verification.ok
+            ? { ok: true, name: 'write', detail: 'wrote, listed, read back and deleted a scratch object: the store meets the ObjectStore contract' }
+            : { ok: false, name: 'write', detail: verification.failures.join('; '), fix: 'Publishers need s3:PutObject and s3:GetObject on layers/*, and the doctor s3:DeleteObject on layers/doctor-*. To check a publisher-only or read-only account, pass --role publisher or --role reader.' });
+        return checks;
+    }
+    // A publisher cannot list: prove what it does, which is put, head and get.
+    const key = `${scratch}probe.txt`;
+    try {
+        await store.put(key, new TextEncoder().encode('atlas'), 'text/plain');
+        const found = await store.head(key);
+        await store.delete(key).catch(() => { });
+        add(found ? { ok: true, name: 'write', detail: 'wrote and found a scratch object' } : { ok: false, name: 'write', detail: 'an object was written but could not be found again', fix: 'The account needs s3:GetObject (HeadObject) on layers/*.' });
+    }
+    catch (error) {
+        add({ ok: false, name: 'write', detail: error instanceof Error ? error.message : String(error), fix: 'Publishers need s3:PutObject and s3:GetObject on layers/*, and s3:ListBucket on the bucket (S3 answers 403 instead of 404 for a missing object without it).' });
+    }
+    return checks;
+}

package/dist/reports/src/effective-delta.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @module Report deltas
+ *
+ * The client half of "send only what changed": `applyEffectiveDelta` turns the report a viewer holds and a delta from the
+ * server (`GET /api/reports/evidence/effective?since=<version>`) into the current report. Pure and free of Node APIs, so a
+ * browser bundle uses it. The server half is `ReportIndex.delta`; a test holds the two together over random runs.
+ *
+ * @see docs/server.md#reading-only-what-changed
+ */
+import type { LayerEvidence } from './evidence-types.js';
+import type { EffectiveEvidence } from './report-index.js';
+/**
+ * What a server answers when a viewer asks for the report `since` a version it holds and the server still
+ * remembers that version: only what changed. `layers` are whole layers (with the rows that win), replacing those
+ * of the same id; `removed` are layers that no longer win anything. Everything else, `backends` and `notices`
+ * and the count, is sent whole because it is small.
+ *
+ * It is an optimisation and nothing else: applying it gives exactly the report the server would have sent in
+ * full, and a server that does not know it sends the full report, which a viewer takes as it always did.
+ */
+export type EffectiveDelta = Omit<EffectiveEvidence, 'layers'> & {
+    readonly delta: true;
+    /** The version this applies to. */
+    readonly base: string;
+    readonly layers: readonly LayerEvidence[];
+    readonly removed: readonly string[];
+};
+/** Is `value` a delta (`delta: true`, a `base` version, `layers` and `removed`) and not a whole report? Decides which of the two a server answered. */
+export declare const isEffectiveDelta: (value: unknown) => value is EffectiveDelta;
+/**
+ * The report a delta leads to, or null when it does not apply to `held` (a different version): ask for the
+ * whole report then.
+ */
+export declare function applyEffectiveDelta(held: EffectiveEvidence, delta: EffectiveDelta): EffectiveEvidence | null;

package/dist/reports/src/effective-delta.js

@@ -0,0 +1,25 @@
+/**
+ * @module Report deltas
+ *
+ * The client half of "send only what changed": `applyEffectiveDelta` turns the report a viewer holds and a delta from the
+ * server (`GET /api/reports/evidence/effective?since=<version>`) into the current report. Pure and free of Node APIs, so a
+ * browser bundle uses it. The server half is `ReportIndex.delta`; a test holds the two together over random runs.
+ *
+ * @see docs/server.md#reading-only-what-changed
+ */
+/** Is `value` a delta (`delta: true`, a `base` version, `layers` and `removed`) and not a whole report? Decides which of the two a server answered. */
+export const isEffectiveDelta = (value) => typeof value === 'object' && value !== null && value.delta === true && typeof value.base === 'string' && Array.isArray(value.layers) && Array.isArray(value.removed);
+/** The report order: newest first, ties by id. */
+const byRecency = (a, b) => b.layer.recordedAtMs - a.layer.recordedAtMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+/**
+ * The report a delta leads to, or null when it does not apply to `held` (a different version): ask for the
+ * whole report then.
+ */
+export function applyEffectiveDelta(held, delta) {
+    if (held.version !== delta.base)
+        return null;
+    const gone = new Set(delta.removed);
+    const replaced = new Set(delta.layers.map(layer => layer.id));
+    const layers = [...held.layers.filter(layer => !gone.has(layer.id) && !replaced.has(layer.id)), ...delta.layers].sort(byRecency);
+    return { version: delta.version, layers, backends: delta.backends, notices: delta.notices, totalLayers: delta.totalLayers };
+}

package/dist/reports/src/evidence-detail.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @module Evidence of one result
+ *
+ * Reads the evidence (attachments, steps, annotations, attempts, tags, labels, links, extensions) that a layer, a
+ * part or a check carries beyond its outcome: the short summary that rides in every report row, one result's full
+ * detail, and the bundle keys its files live under. It only reads; evidence never decides a status, a slot or a
+ * winner, so nothing here affects who wins.
+ *
+ * @see docs/extending.md
+ * @see docs/report-contract.md (evidence)
+ */
+import type { Annotation, Attachment, Attempt, Check, Step } from '../../schema/src/layer.js';
+import type { EvidenceSummary } from './evidence-types.js';
+/** Anything that may carry evidence: a layer, a part or a check. */
+export type EvidenceHolder = {
+    readonly tags?: readonly string[];
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly links?: readonly {
+        readonly url: string;
+        readonly name?: string | undefined;
+        readonly rel?: string | undefined;
+    }[];
+    readonly attachments?: readonly Attachment[];
+    readonly annotations?: readonly Annotation[];
+    readonly steps?: readonly Step[];
+    readonly attempts?: readonly Attempt[];
+    readonly extensions?: Readonly<Record<string, unknown>>;
+};
+/**
+ * What a result carries beyond its outcome, as counts and short facts. It rides in every row of the
+ * report so a list can show "3 attachments, 12 steps" without opening anything; the evidence itself is
+ * read when someone asks for it. Undefined when there is none.
+ *
+ * Several holders (for example a check and its layer) are summed: `attachments` also counts those on steps and
+ * attempts, `steps` counts only each holder's own top-level steps, tags are de-duplicated, and for a repeated
+ * label the later holder wins. `roles` are the attachments' roles (or, without one, what their media type or file
+ * name implies), sorted and distinct.
+ */
+export declare function summarizeEvidence(...holders: readonly EvidenceHolder[]): EvidenceSummary | undefined;
+/** A role to show when a producer gave none, from the media type: `image`, `video`, `audio`, `snapshot` (text/html), `text` (text, JSON, XML) or `file`. Roles are an open vocabulary; a producer's own role always wins. */
+export declare function roleOfType(contentType: string | undefined): string;
+/** All of one result's evidence, read when someone opens it. */
+export type CheckDetail = {
+    /** The id of the layer the check was read from. */
+    readonly layer: string;
+    /** The kind of the part that holds the check. */
+    readonly kind: string;
+    /** The check as recorded, with all of its evidence. */
+    readonly check: Check;
+    /** What the run as a whole carries: its logs, its links, its labels. */
+    readonly run: EvidenceHolder;
+};
+/** One result's evidence, from a layer: the first check with id `checkId` (in a part of kind `kind`, when given) plus the layer's own evidence. Null when the layer holds no such check. */
+export declare function checkDetailOf(layer: {
+    readonly id: string;
+    readonly parts: readonly {
+        readonly kind: string;
+        readonly checks: readonly Check[];
+    }[];
+} & EvidenceHolder, checkId: string, kind?: string): CheckDetail | null;
+/** What a layer carries as a whole (its tags, labels, links, attachments, annotations and extensions; not its parts' checks). Absent fields stay absent. */
+export declare function runEvidence(layer: EvidenceHolder): EvidenceHolder;
+/** Every distinct bundle key (`bundleKey`) that the attachments of a holder, its steps and its attempts point to, so a layer's files can be copied. Attachments held by `uri` or inline `text` have none. */
+export declare function bundleKeysOf(holder: EvidenceHolder): string[];