@better-fs-tools/read 0.0.0-tegami-trusted-publish-setup → 0.2.0

package/dist/core/text-outcome.d.ts

@@ -0,0 +1,19 @@
+import type { FileSystem } from "@better-fs-tools/fs";
+import type { ReadDependencies } from "../contract/deps.ts";
+import type { ReadRequest } from "../contract/input.ts";
+import type { ClassificationInfo, ConversionInfo, FileInfo, ReadNote, ReadOk } from "../contract/result.ts";
+import type { ScanOutcome } from "./scan.ts";
+export interface TextOutcomeInput<THost> {
+    readonly deps: ReadDependencies<THost>;
+    readonly fs: FileSystem | null;
+    readonly request: ReadRequest;
+    readonly file: FileInfo;
+    readonly classification: ClassificationInfo;
+    readonly conversion: ConversionInfo | null;
+    readonly scan: Extract<ScanOutcome, {
+        kind: "scanned";
+    }>;
+    readonly contentId: string | null;
+    readonly notes: readonly ReadNote[];
+}
+export declare function textOutcome<THost>(input: TextOutcomeInput<THost>): ReadOk;

package/dist/core/text-outcome.js

@@ -0,0 +1,72 @@
+import { buildViewNotes, emptyNote } from "./notes.js";
+import { buildObservation } from "./observation.js";
+export function textOutcome(input) {
+    const { deps, fs, request, file, classification, conversion, scan } = input;
+    const { scanner, scanCapped, reachedEof, scannedBytes } = scan;
+    const reasons = [];
+    if (scanner.selectionStop === "lines")
+        reasons.push("lines");
+    if (scanner.selectionStop === "bytes")
+        reasons.push("bytes");
+    if (scanner.selectionStop === "budget")
+        reasons.push("budget");
+    if (scanCapped)
+        reasons.push("scan-limit");
+    if (scanner.clampedLines.length > 0)
+        reasons.push("line-length");
+    const continuationAvailable = scanner.firstUnshown !== null;
+    const wholeFileVisible = request.offset === 1 &&
+        !continuationAvailable &&
+        !scanCapped &&
+        scanner.clampedLines.length === 0;
+    return {
+        tool: "read",
+        status: "ok",
+        request,
+        file,
+        classification,
+        conversion,
+        view: {
+            lines: scanner.lines,
+            startLine: request.offset,
+            endLine: scanner.lines.length === 0 ? request.offset - 1 : request.offset + scanner.lines.length - 1,
+            bytes: scanner.viewBytes,
+            partial: request.offset !== 1 || continuationAvailable || reasons.length > 0,
+        },
+        truncation: { truncated: reasons.length > 0, reasons, primary: reasons[0] ?? null },
+        continuation: {
+            available: continuationAvailable,
+            next: scanner.firstUnshown === null
+                ? null
+                : { path: request.path, offset: scanner.firstUnshown, limit: request.limit },
+        },
+        totals: {
+            lines: scanCapped ? null : scanner.totalLines,
+            exact: !scanCapped,
+            // Converted text has no size of its own: the count is the text scanned.
+            bytes: reachedEof || conversion !== null ? scannedBytes : (file.size ?? scannedBytes),
+        },
+        observation: fs === null
+            ? null
+            : buildObservation(deps.digest, {
+                file,
+                contentId: input.contentId,
+                view: scanner.viewText,
+                observedAt: deps.clock().toISOString(),
+                wholeFileVisible,
+            }),
+        notes: [
+            ...buildViewNotes({
+                scanner,
+                request,
+                limits: deps.limits,
+                messages: deps.messages,
+                scanCapped,
+            }),
+            ...input.notes,
+            ...(conversion === null && reachedEof && scannedBytes === 0
+                ? [emptyNote(deps.messages, file.displayPath)]
+                : []),
+        ],
+    };
+}

package/dist/core/verify.d.ts

@@ -0,0 +1,7 @@
+import type { OpenFile } from "@better-fs-tools/fs";
+import type { ReadRequest } from "../contract/input.ts";
+import type { ReadMessageCatalog } from "../contract/messages.ts";
+import type { FileInfo } from "../contract/result.ts";
+import type { CallScope } from "./call-scope.ts";
+export declare function checkSize(messages: Readonly<ReadMessageCatalog>, request: ReadRequest, file: FileInfo, consumed: number): void;
+export declare function verifyHandle<THost>(handle: OpenFile, messages: Readonly<ReadMessageCatalog>, request: ReadRequest, file: FileInfo, scope: CallScope<THost>): Promise<void>;

package/dist/core/verify.js

@@ -0,0 +1,15 @@
+import { ReadStop, changedDuringRead, fromFileSystemError } from "./outcomes.js";
+export function checkSize(messages, request, file, consumed) {
+    if (file.size !== null && consumed !== file.size) {
+        throw new ReadStop(changedDuringRead(messages, request, file));
+    }
+}
+export async function verifyHandle(handle, messages, request, file, scope) {
+    const verified = await handle.verify();
+    if (!verified.ok) {
+        throw new ReadStop(fromFileSystemError(messages, request, verified.error, scope.phase, file));
+    }
+    if (verified.changed)
+        throw new ReadStop(changedDuringRead(messages, request, file));
+    scope.checkAbort();
+}

package/dist/digest/sha256.d.ts

@@ -0,0 +1,7 @@
+import type { Digest } from "../contract/digest.ts";
+/**
+ * SHA-256 in plain JavaScript, with no Node module, so it works in a Cloudflare
+ * Worker. It gives the same hashes as `nodeDigest()` from
+ * `@better-fs-tools/node`, so both can share one state store.
+ */
+export declare function sha256Digest(): Digest;

package/dist/digest/sha256.js

@@ -0,0 +1,131 @@
+/* FIPS 180-4, section 4.2.2: the first 32 bits of the fractional parts of the cube roots of the first 64 primes. */
+const K = new Uint32Array([
+    0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
+    0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
+    0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
+    0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
+    0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
+    0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
+    0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
+    0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
+]);
+/* Section 5.3.3: the first 32 bits of the fractional parts of the square roots of the first 8 primes. */
+const INITIAL = [
+    0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
+];
+const ENCODER = new TextEncoder();
+/**
+ * SHA-256 in plain JavaScript, with no Node module, so it works in a Cloudflare
+ * Worker. It gives the same hashes as `nodeDigest()` from
+ * `@better-fs-tools/node`, so both can share one state store.
+ */
+export function sha256Digest() {
+    return Object.freeze({
+        id: "sha256",
+        create: () => new Sha256Stream(),
+        hash(value) {
+            const stream = new Sha256Stream();
+            stream.update(ENCODER.encode(value));
+            return stream.digest();
+        },
+    });
+}
+class Sha256Stream {
+    state = Uint32Array.from(INITIAL);
+    block = new Uint8Array(64);
+    words = new Uint32Array(64);
+    filled = 0;
+    // A double holds every length below 2^53 exactly.
+    totalBytes = 0;
+    finished = false;
+    update(bytes) {
+        if (this.finished)
+            throw new TypeError("sha256 stream is already finished");
+        this.totalBytes += bytes.byteLength;
+        let offset = 0;
+        if (this.filled > 0) {
+            const take = Math.min(64 - this.filled, bytes.byteLength);
+            this.block.set(bytes.subarray(0, take), this.filled);
+            this.filled += take;
+            offset = take;
+            if (this.filled < 64)
+                return;
+            this.compress(this.block, 0);
+            this.filled = 0;
+        }
+        for (; offset + 64 <= bytes.byteLength; offset += 64)
+            this.compress(bytes, offset);
+        if (offset < bytes.byteLength) {
+            this.block.set(bytes.subarray(offset), 0);
+            this.filled = bytes.byteLength - offset;
+        }
+    }
+    digest() {
+        if (this.finished)
+            throw new TypeError("sha256 stream is already finished");
+        this.finished = true;
+        const bits = this.totalBytes * 8;
+        this.block[this.filled] = 0x80;
+        this.block.fill(0, this.filled + 1);
+        if (this.filled >= 56) {
+            this.compress(this.block, 0);
+            this.block.fill(0);
+        }
+        setUint64BigEndian(new DataView(this.block.buffer), 56, bits);
+        this.compress(this.block, 0);
+        let hex = "sha256:";
+        for (const word of this.state)
+            hex += word.toString(16).padStart(8, "0");
+        return hex;
+    }
+    compress(bytes, offset) {
+        const w = this.words;
+        for (let i = 0; i < 16; i++) {
+            const j = offset + i * 4;
+            w[i] = (bytes[j] << 24) | (bytes[j + 1] << 16) | (bytes[j + 2] << 8) | bytes[j + 3];
+        }
+        for (let i = 16; i < 64; i++) {
+            const a = w[i - 15];
+            const b = w[i - 2];
+            const s0 = rotr(a, 7) ^ rotr(a, 18) ^ (a >>> 3);
+            const s1 = rotr(b, 17) ^ rotr(b, 19) ^ (b >>> 10);
+            w[i] = (w[i - 16] + s0 + w[i - 7] + s1) | 0;
+        }
+        const s = this.state;
+        let a = s[0];
+        let b = s[1];
+        let c = s[2];
+        let d = s[3];
+        let e = s[4];
+        let f = s[5];
+        let g = s[6];
+        let h = s[7];
+        for (let i = 0; i < 64; i++) {
+            const t1 = (h + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + ((e & f) ^ (~e & g)) + K[i] + w[i]) | 0;
+            const t2 = ((rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + ((a & b) ^ (a & c) ^ (b & c))) | 0;
+            h = g;
+            g = f;
+            f = e;
+            e = (d + t1) | 0;
+            d = c;
+            c = b;
+            b = a;
+            a = (t1 + t2) | 0;
+        }
+        s[0] = s[0] + a;
+        s[1] = s[1] + b;
+        s[2] = s[2] + c;
+        s[3] = s[3] + d;
+        s[4] = s[4] + e;
+        s[5] = s[5] + f;
+        s[6] = s[6] + g;
+        s[7] = s[7] + h;
+    }
+}
+function setUint64BigEndian(view, offset, value) {
+    view.setUint32(offset, Math.floor(value / 0x1_0000_0000));
+    view.setUint32(offset + 4, value >>> 0);
+}
+function rotr(value, bits) {
+    return (value >>> bits) | (value << (32 - bits));
+}

package/dist/formats/deep-agents.d.ts

@@ -0,0 +1,7 @@
+import type { ReadFormatter } from "../contract/format.ts";
+/**
+ * Deep Agents style: the source with no gutter between two range lines,
+ * `@@ lines 1-100 of 250 | next offset 101 @@`. The offset is canonical
+ * (one-based). The total is left out when the scan stopped before EOF.
+ */
+export declare function deepAgentsFormat(): ReadFormatter<unknown>;

package/dist/formats/deep-agents.js

@@ -0,0 +1,23 @@
+import { plainFormatter } from "../formatters/plain.js";
+import { isDirectory, preset } from "./shared.js";
+/**
+ * Deep Agents style: the source with no gutter between two range lines,
+ * `@@ lines 1-100 of 250 | next offset 101 @@`. The offset is canonical
+ * (one-based). The total is left out when the scan stopped before EOF.
+ */
+export function deepAgentsFormat() {
+    return preset("deep-agents", plainFormatter({ header: range, footer: range }));
+}
+function range(outcome) {
+    if (outcome.status !== "ok")
+        return null;
+    const noun = isDirectory(outcome) ? "entries" : "lines";
+    const { lines } = outcome.view;
+    const first = lines[0];
+    const last = lines.at(-1);
+    const shown = first && last ? `${noun} ${first.number}-${last.number}` : `no ${noun}`;
+    const total = outcome.totals.lines === null ? "" : ` of ${outcome.totals.lines}`;
+    const offset = outcome.continuation.next?.offset;
+    const next = offset === undefined ? "" : ` | next offset ${offset}`;
+    return `@@ ${shown}${total}${next} @@`;
+}

package/dist/formats/hashline.d.ts

@@ -0,0 +1,6 @@
+import type { ReadFormatter } from "../contract/format.ts";
+/**
+ * Hashline style: a file hash line, then `12:a3|text` lines, and an
+ * end-of-file line. Directory entries get plain `1|` numbers.
+ */
+export declare function hashlineFormat(): ReadFormatter<unknown>;

package/dist/formats/hashline.js

@@ -0,0 +1,16 @@
+import { eofFooter } from "../formatters/eof.js";
+import { fileHashHeader } from "../formatters/file-hash.js";
+import { hashlineGutter } from "../formatters/hashline.js";
+import { lineNumberFormatter } from "../formatters/line-number.js";
+import { preset } from "./shared.js";
+/**
+ * Hashline style: a file hash line, then `12:a3|text` lines, and an
+ * end-of-file line. Directory entries get plain `1|` numbers.
+ */
+export function hashlineFormat() {
+    return preset("hashline", lineNumberFormatter({
+        gutter: hashlineGutter(),
+        header: fileHashHeader(),
+        footer: eofFooter(),
+    }), lineNumberFormatter());
+}

package/dist/formats/hermes.d.ts

@@ -0,0 +1,9 @@
+import type { ReadFormatter } from "../contract/format.ts";
+/**
+ * Hermes style: one JSON object. Text gives `content` with `12|text` lines,
+ * `total_lines`, `file_size`, `truncated` (any cut, a clamped line too),
+ * `next_offset` (when more lines follow), and the notes joined as `hint`.
+ * Failures and refusals give `error`, and a miss adds `similar_files`. Media
+ * gives the JSON, then the media parts. "view" mode leaves out the hint.
+ */
+export declare function hermesFormat(): ReadFormatter<unknown>;

package/dist/formats/hermes.js

@@ -0,0 +1,62 @@
+import { jsonFormatter } from "../formatters/json.js";
+import { isDirectory } from "./shared.js";
+/**
+ * Hermes style: one JSON object. Text gives `content` with `12|text` lines,
+ * `total_lines`, `file_size`, `truncated` (any cut, a clamped line too),
+ * `next_offset` (when more lines follow), and the notes joined as `hint`.
+ * Failures and refusals give `error`, and a miss adds `similar_files`. Media
+ * gives the JSON, then the media parts. "view" mode leaves out the hint.
+ */
+export function hermesFormat() {
+    const json = jsonFormatter({ pick: hermesFields });
+    return Object.freeze({
+        id: "hermes",
+        format: (outcome, ctx) => json.format(ctx.mode === "view" ? withoutNotes(outcome) : outcome, ctx),
+    });
+}
+function withoutNotes(outcome) {
+    return { ...outcome, notes: [] };
+}
+function hermesFields(outcome) {
+    const messages = outcome.notes.map((note) => note.message).join(" ");
+    const hint = messages === "" ? {} : { hint: messages };
+    const size = outcome.file?.size ?? null;
+    const fileSize = size === null ? {} : { file_size: size };
+    switch (outcome.status) {
+        case "ok": {
+            const directory = isDirectory(outcome);
+            const content = outcome.view.lines
+                .map((line) => directory
+                ? line.text
+                : `${line.number}|${line.text}${line.clamped ? "... [truncated]" : ""}`)
+                .join("\n");
+            const total = outcome.totals.lines;
+            const offset = outcome.continuation.next?.offset;
+            return {
+                content,
+                ...(total === null ? {} : { [directory ? "total_entries" : "total_lines"]: total }),
+                ...fileSize,
+                truncated: outcome.truncation.truncated,
+                ...(offset === undefined ? {} : { next_offset: offset }),
+                ...hint,
+            };
+        }
+        case "media": {
+            const text = outcome.parts.flatMap((part) => (part.type === "text" ? [part.text] : []));
+            return {
+                ...(text.length === 0 ? {} : { content: text.join("\n") }),
+                mime_type: outcome.conversion.mimeType,
+                ...fileSize,
+                ...hint,
+            };
+        }
+        case "unsupported":
+            return { error: messages || outcome.code, ...fileSize };
+        case "error":
+            return { error: messages || outcome.error.code, ...similarFiles(outcome.notes) };
+    }
+}
+function similarFiles(notes) {
+    const suggestions = notes.find((note) => note.code === "not-found")?.data?.["suggestions"];
+    return Array.isArray(suggestions) && suggestions.length > 0 ? { similar_files: suggestions } : {};
+}

package/dist/formats/index.d.ts

@@ -0,0 +1,4 @@
+export { deepAgentsFormat } from "./deep-agents.ts";
+export { hashlineFormat } from "./hashline.ts";
+export { hermesFormat } from "./hermes.ts";
+export { opencodeFormat } from "./opencode.ts";

package/dist/formats/index.js

@@ -0,0 +1,4 @@
+export { deepAgentsFormat } from "./deep-agents.js";
+export { hashlineFormat } from "./hashline.js";
+export { hermesFormat } from "./hermes.js";
+export { opencodeFormat } from "./opencode.js";

package/dist/formats/opencode.d.ts

@@ -0,0 +1,7 @@
+import type { ReadFormatter } from "../contract/format.ts";
+/**
+ * OpenCode style: path and type tags, then `1: text` lines in `<content>`,
+ * and an end-of-file line. Directory entries go in `<entries>` with no
+ * numbers. Notes follow the closing tag.
+ */
+export declare function opencodeFormat(): ReadFormatter<unknown>;

package/dist/formats/opencode.js

@@ -0,0 +1,35 @@
+import { eofFooter } from "../formatters/eof.js";
+import { lineNumberFormatter } from "../formatters/line-number.js";
+import { plainFormatter } from "../formatters/plain.js";
+import { isDirectory, preset } from "./shared.js";
+const eof = eofFooter();
+/**
+ * OpenCode style: path and type tags, then `1: text` lines in `<content>`,
+ * and an end-of-file line. Directory entries go in `<entries>` with no
+ * numbers. Notes follow the closing tag.
+ */
+export function opencodeFormat() {
+    const options = { header, footer };
+    return preset("opencode", lineNumberFormatter({ ...options, gutter: (line) => `${line.number}: ` }), plainFormatter(options));
+}
+function header(outcome) {
+    if (outcome.status === "media") {
+        return `<path>${outcome.file.displayPath}</path>\n<type>media</type>`;
+    }
+    if (outcome.status !== "ok")
+        return null;
+    const directory = isDirectory(outcome);
+    return [
+        `<path>${outcome.file.displayPath}</path>`,
+        `<type>${directory ? "directory" : "file"}</type>`,
+        directory ? "<entries>" : "<content>",
+    ].join("\n");
+}
+function footer(outcome, ctx) {
+    if (outcome.status !== "ok")
+        return null;
+    if (isDirectory(outcome))
+        return "</entries>";
+    const end = eof(outcome, ctx);
+    return end === null ? "</content>" : `\n${end}\n</content>`;
+}

package/dist/formats/shared.d.ts

@@ -0,0 +1,4 @@
+import type { ReadFormatter } from "../contract/format.ts";
+import type { ReadReport } from "../contract/result.ts";
+export declare function isDirectory(outcome: ReadReport): boolean;
+export declare function preset(id: string, file: ReadFormatter<unknown>, directory?: ReadFormatter<unknown>): ReadFormatter<unknown>;

package/dist/formats/shared.js

@@ -0,0 +1,9 @@
+export function isDirectory(outcome) {
+    return outcome.status === "ok" && outcome.classification.kind === "directory";
+}
+export function preset(id, file, directory = file) {
+    return Object.freeze({
+        id,
+        format: (outcome, ctx) => (isDirectory(outcome) ? directory : file).format(outcome, ctx),
+    });
+}

package/dist/formatters/eof.d.ts

@@ -0,0 +1,7 @@
+import type { LineNumberFormatterOptions } from "./line-number.ts";
+/**
+ * An end-of-file footer, shown only when the view ends at the file's last line
+ * and the total is exact. An empty file counts. Directory listings and views a
+ * hook emptied do not.
+ */
+export declare function eofFooter(text?: (totalLines: number) => string): NonNullable<LineNumberFormatterOptions["footer"]>;

package/dist/formatters/eof.js

@@ -0,0 +1,20 @@
+/**
+ * An end-of-file footer, shown only when the view ends at the file's last line
+ * and the total is exact. An empty file counts. Directory listings and views a
+ * hook emptied do not.
+ */
+export function eofFooter(text = (n) => `(End of file - total ${n} lines)`) {
+    return (outcome) => {
+        const total = eofTotal(outcome);
+        return total === null ? null : text(total);
+    };
+}
+function eofTotal(outcome) {
+    if (outcome.status !== "ok" || outcome.classification.kind === "directory")
+        return null;
+    const total = outcome.totals.lines;
+    if (!outcome.totals.exact || total === null || outcome.continuation.available)
+        return null;
+    const last = outcome.view.lines.at(-1)?.number ?? 0;
+    return last === total ? total : null;
+}

package/dist/formatters/file-hash.d.ts

@@ -0,0 +1,7 @@
+import type { LineNumberFormatterOptions } from "./line-number.ts";
+/**
+ * A "file-hash: <contentId>" header, where contentId is the hash of the source
+ * bytes. Shows nothing when the hash is unknown: no digest, a scan that stopped
+ * before EOF, or an outcome with no observation.
+ */
+export declare function fileHashHeader(): NonNullable<LineNumberFormatterOptions["header"]>;

package/dist/formatters/file-hash.js

@@ -0,0 +1,13 @@
+/**
+ * A "file-hash: <contentId>" header, where contentId is the hash of the source
+ * bytes. Shows nothing when the hash is unknown: no digest, a scan that stopped
+ * before EOF, or an outcome with no observation.
+ */
+export function fileHashHeader() {
+    return (outcome) => {
+        if (outcome.status !== "ok" && outcome.status !== "media")
+            return null;
+        const contentId = outcome.observation?.contentId ?? null;
+        return contentId === null ? null : `file-hash: ${contentId}`;
+    };
+}

package/dist/formatters/hashline.d.ts

@@ -0,0 +1,11 @@
+import type { LineNumberFormatterOptions } from "./line-number.ts";
+export interface HashlineGutterOptions {
+    /** Characters of the line hash to show. Default 2. */
+    width?: number;
+}
+/**
+ * A "12:a3|" gutter: the line number and the start of the line's hash, so the
+ * id is stable across reads and changes when the line changes. With no digest
+ * the gutter is the number alone: "12|".
+ */
+export declare function hashlineGutter(options?: HashlineGutterOptions): NonNullable<LineNumberFormatterOptions["gutter"]>;

package/dist/formatters/hashline.js

@@ -0,0 +1,18 @@
+/**
+ * A "12:a3|" gutter: the line number and the start of the line's hash, so the
+ * id is stable across reads and changes when the line changes. With no digest
+ * the gutter is the number alone: "12|".
+ */
+export function hashlineGutter(options = {}) {
+    const width = options.width ?? 2;
+    if (!Number.isSafeInteger(width) || width < 1) {
+        throw new TypeError("hashlineGutter width must be a positive integer");
+    }
+    return (line, ctx) => {
+        if (ctx.digest === null)
+            return `${line.number}|`;
+        const value = ctx.digest.hash(line.text);
+        const afterAlgorithmPrefix = value.lastIndexOf(":") + 1;
+        return `${line.number}:${value.slice(afterAlgorithmPrefix, afterAlgorithmPrefix + width)}|`;
+    };
+}

package/dist/formatters/index.d.ts

@@ -0,0 +1,10 @@
+export { eofFooter } from "./eof.ts";
+export { fileHashHeader } from "./file-hash.ts";
+export { hashlineGutter } from "./hashline.ts";
+export type { HashlineGutterOptions } from "./hashline.ts";
+export { jsonFormatter } from "./json.ts";
+export type { JsonFormatterOptions } from "./json.ts";
+export { defaultNoteLine } from "./layout.ts";
+export { lineNumberFormatter } from "./line-number.ts";
+export type { LineNumberFormatterOptions } from "./line-number.ts";
+export { plainFormatter } from "./plain.ts";

package/dist/formatters/index.js

@@ -0,0 +1,7 @@
+export { eofFooter } from "./eof.js";
+export { fileHashHeader } from "./file-hash.js";
+export { hashlineGutter } from "./hashline.js";
+export { jsonFormatter } from "./json.js";
+export { defaultNoteLine } from "./layout.js";
+export { lineNumberFormatter } from "./line-number.js";
+export { plainFormatter } from "./plain.js";

package/dist/formatters/json.d.ts

@@ -0,0 +1,17 @@
+import type { ReadFormatter } from "../contract/format.ts";
+import type { JsonObject } from "../contract/json.ts";
+import type { ReadReport } from "../contract/result.ts";
+export interface JsonFormatterOptions {
+    /** Default: the whole outcome. */
+    pick?: (outcome: ReadReport) => JsonObject;
+    /** "inside" (default) puts notes in the JSON; "after" adds note lines after it. */
+    notes?: "inside" | "after";
+    space?: number;
+}
+/**
+ * JSON text of pick(outcome), for hosts that render the result themselves.
+ * With notes "after", and in "view" mode, the top-level `notes` key is left out.
+ * Media bytes are left out of the JSON: each byte array becomes its length.
+ * A media outcome returns the JSON text part, then its media parts.
+ */
+export declare function jsonFormatter(options?: JsonFormatterOptions): ReadFormatter<unknown>;

package/dist/formatters/json.js

@@ -0,0 +1,36 @@
+import { join, noteLines } from "./layout.js";
+/**
+ * JSON text of pick(outcome), for hosts that render the result themselves.
+ * With notes "after", and in "view" mode, the top-level `notes` key is left out.
+ * Media bytes are left out of the JSON: each byte array becomes its length.
+ * A media outcome returns the JSON text part, then its media parts.
+ */
+export function jsonFormatter(options = {}) {
+    const pick = options.pick ?? ((outcome) => outcome);
+    const placement = options.notes ?? "inside";
+    const space = options.space ?? 0;
+    const stringify = (value) => JSON.stringify(value, withoutBytes, space);
+    return Object.freeze({
+        id: "json",
+        format(outcome, ctx) {
+            const picked = pick(outcome);
+            let text;
+            if (placement === "inside" && ctx.mode === "model") {
+                text = stringify(picked);
+            }
+            else {
+                const json = stringify(withoutNotes(picked));
+                text = ctx.mode === "view" ? json : join(json, noteLines(outcome.notes, {}));
+            }
+            if (outcome.status !== "media")
+                return text;
+            return [{ type: "text", text }, ...outcome.parts.filter((part) => part.type === "media")];
+        },
+    });
+}
+function withoutBytes(_key, value) {
+    return value instanceof Uint8Array ? { bytes: value.byteLength } : value;
+}
+function withoutNotes(value) {
+    return Object.fromEntries(Object.entries(value).filter(([key]) => key !== "notes"));
+}

package/dist/formatters/layout.d.ts

@@ -0,0 +1,15 @@
+import type { ReadFormatContext } from "../contract/format.ts";
+import type { ContentPart, ReadNote, ReadReport } from "../contract/result.ts";
+export interface LayoutOptions {
+    header?: (outcome: ReadReport, ctx: ReadFormatContext<unknown>) => string | null;
+    footer?: (outcome: ReadReport, ctx: ReadFormatContext<unknown>) => string | null;
+    /** Filter or rewrite a note for display. null hides it. */
+    notes?: (note: ReadNote) => ReadNote | null;
+    /** Default: `[read:${note.code}] ${note.message}`. */
+    noteLine?: (note: ReadNote) => string;
+}
+export declare function defaultNoteLine(note: ReadNote): string;
+export declare function layout(outcome: ReadReport, ctx: ReadFormatContext<unknown>, body: string, options: LayoutOptions): string;
+export declare function noteLines(notes: readonly ReadNote[], options: LayoutOptions): string[];
+export declare function join(main: string, lines: readonly string[]): string;
+export declare function withParts(outcome: ReadReport, text: string): string | readonly ContentPart[];