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

package/dist/core/messages.d.ts

@@ -0,0 +1,8 @@
+import type { ReadMessageCatalog } from "../contract/messages.ts";
+/** The default wording of every read message. */
+export declare const defaultReadMessages: Readonly<ReadMessageCatalog>;
+/**
+ * Merges overrides over `defaultReadMessages`. Throws TypeError on an unknown key
+ * or a value that is not a function.
+ */
+export declare function resolveReadMessages(overrides?: Partial<ReadMessageCatalog>): Readonly<ReadMessageCatalog>;

package/dist/core/messages.js

@@ -0,0 +1,78 @@
+const catalog = {
+    retry: (next) => JSON.stringify(next),
+    continuation: ({ retry, reason }) => `Output stopped at the ${reasonLabel(reason)}. Continue with ${retry}.`,
+    firstLineTooLong: ({ line, maxViewBytes, retry }) => `Line ${line} cannot be shown within the ${maxViewBytes}-byte view limit. To skip it, continue with ${retry}.`,
+    offsetPastEof: ({ request, totalLines, retry }) => `Line ${request.offset} is past EOF; the file has ${totalLines} logical line${totalLines === 1 ? "" : "s"}. To read the last line, retry with ${retry}.`,
+    offsetUnreached: ({ request, reachedLine, retry }) => `Scanning stopped before line ${request.offset} was reached. Retry from line ${reachedLine} with ${retry}.`,
+    lineClamped: ({ lines, total, maxChars }) => `Source line${total === 1 ? "" : "s"} ${lines.join(", ")}${total > lines.length ? ", …" : ""} exceeded ${maxChars} characters and ${total === 1 ? "was" : "were"} clamped.`,
+    limitClamped: ({ requested, max }) => `The requested line count of ${requested} is over the maximum, so at most ${max} lines are shown.`,
+    scanLimit: ({ maxScanBytes }) => `Scanning stopped at ${maxScanBytes} bytes, so the total line count is unknown.`,
+    empty: ({ path }) => `${path} is empty (0 bytes); no retry is needed.`,
+    notFound: ({ request, suggestions }) => suggestions.length === 0
+        ? `${request.path} was not found.`
+        : `${request.path} was not found. Nearby names: ${quoted(suggestions)}.`,
+    pathRepaired: ({ from, to }) => `The requested filename ${JSON.stringify(from)} was repaired to the unique Unicode-equivalent path ${JSON.stringify(to)}.`,
+    notAFile: ({ request, kind }) => `${request.path} is a ${kindLabel(kind)}.`,
+    dangerousPath: ({ request, detail }) => `${request.path} is refused by policy${detail === null ? "" : ` (${detail})`}. Choose another path.`,
+    outsideAllowedRoots: ({ request }) => `${request.path} is outside every configured allowed root.`,
+    permissionDenied: ({ request }) => `Permission was denied for ${request.path}.`,
+    denied: ({ path, detail }) => `${path} was refused by policy${detail === null ? "" : ` (${detail})`}.`,
+    tooLarge: ({ request, stage, limit }) => {
+        if (stage === "backend") {
+            return `${request.path} is larger than the ${limit}-byte limit of this filesystem backend, so it was not read.`;
+        }
+        return stage === "convert"
+            ? `${request.path} is larger than the ${limit}-byte conversion limit, so it was not converted.`
+            : `The media converted from ${request.path} is larger than the ${limit}-byte media limit, so it was not returned.`;
+    },
+    changedDuringRead: ({ request, retry }) => `${request.path} changed while it was being read. Read it again with ${retry} before relying on this result.`,
+    aborted: ({ phase }) => `The read was aborted during the ${phase} phase, so nothing was read.`,
+    invalidInput: ({ detail }) => `The read input was rejected: ${detail}`,
+    extensionFailed: ({ request, extension, phase }) => `The ${extension} extension failed during the ${phase} phase while reading ${request.path}; this is a host problem rather than a property of the file.`,
+    ioError: ({ request }) => `The backend failed while reading ${request === null ? "the requested path" : request.path}.`,
+    unsupportedBackend: ({ request, detail }) => `This host cannot read ${request.path}${detail === null ? "" : ` (${detail})`}. Do not retry.`,
+    viewModified: ({ hook }) => `The ${hook} hook changed this view, so it is not the exact file text.`,
+};
+/** The default wording of every read message. */
+export const defaultReadMessages = Object.freeze(catalog);
+function quoted(values) {
+    return values.map((value) => JSON.stringify(value)).join(", ");
+}
+function reasonLabel(reason) {
+    if (reason === "lines")
+        return "line limit";
+    if (reason === "bytes")
+        return "view-byte limit";
+    if (reason === "budget")
+        return "view budget";
+    if (reason === "scan-limit")
+        return "scan limit";
+    return "line-length limit";
+}
+function kindLabel(kind) {
+    if (kind === "fifo")
+        return "FIFO";
+    if (kind === "other")
+        return "non-regular file";
+    return kind;
+}
+/**
+ * Merges overrides over `defaultReadMessages`. Throws TypeError on an unknown key
+ * or a value that is not a function.
+ */
+export function resolveReadMessages(overrides = {}) {
+    if (overrides === null || typeof overrides !== "object" || Array.isArray(overrides)) {
+        throw new TypeError("messages must be an object");
+    }
+    const resolved = { ...defaultReadMessages };
+    for (const [key, value] of Object.entries(overrides)) {
+        if (!Object.hasOwn(defaultReadMessages, key))
+            throw new TypeError(`Unknown message: ${key}`);
+        if (value === undefined)
+            continue;
+        if (typeof value !== "function")
+            throw new TypeError(`messages.${key} must be a function`);
+        resolved[key] = value;
+    }
+    return Object.freeze(resolved);
+}

package/dist/core/notes.d.ts

@@ -0,0 +1,14 @@
+import type { ReadRequest } from "../contract/input.ts";
+import type { ReadLimits } from "../contract/limits.ts";
+import type { ReadMessageCatalog } from "../contract/messages.ts";
+import type { ReadNote } from "../contract/result.ts";
+import type { LineScanner } from "./scanner.ts";
+export interface ViewNoteContext {
+    readonly scanner: LineScanner;
+    readonly request: ReadRequest;
+    readonly limits: Readonly<ReadLimits>;
+    readonly messages: Readonly<ReadMessageCatalog>;
+    readonly scanCapped: boolean;
+}
+export declare function buildViewNotes(context: ViewNoteContext): ReadNote[];
+export declare function emptyNote(messages: Readonly<ReadMessageCatalog>, path: string): ReadNote;

package/dist/core/notes.js

@@ -0,0 +1,94 @@
+const MAX_LISTED_CLAMPED_LINES = 20;
+export function buildViewNotes(context) {
+    const { scanner, request, limits, messages, scanCapped } = context;
+    const notes = [];
+    const offsetUnreached = scanCapped &&
+        scanner.lines.length === 0 &&
+        scanner.firstUnshown === null &&
+        request.offset > scanner.totalLines + 1;
+    if (offsetUnreached) {
+        const reachedLine = scanner.totalLines + 1;
+        const retry = retryFrom(request, reachedLine);
+        notes.push({
+            code: "offset-unreached",
+            severity: "warning",
+            message: messages.offsetUnreached({ request, reachedLine, retry: messages.retry(retry) }),
+            retry,
+            data: { reachedLine },
+        });
+    }
+    else if (scanner.selectionStop === "bytes" &&
+        scanner.lines.length === 0 &&
+        scanner.firstUnshown !== null) {
+        const line = scanner.firstUnshown;
+        const retry = retryFrom(request, line + 1);
+        notes.push({
+            code: "first-line-exceeds-byte-limit",
+            severity: "warning",
+            message: messages.firstLineTooLong({
+                line,
+                maxViewBytes: limits.maxViewBytes,
+                retry: messages.retry(retry),
+            }),
+            retry,
+            data: { line },
+        });
+    }
+    else if (scanner.firstUnshown !== null) {
+        const retry = retryFrom(request, scanner.firstUnshown);
+        const reason = scanner.selectionStop ?? "scan-limit";
+        notes.push({
+            code: "continue",
+            severity: "info",
+            message: messages.continuation({ request, retry: messages.retry(retry), reason }),
+            retry,
+            data: { reason },
+        });
+    }
+    const clamped = scanner.clampedLines;
+    if (clamped.length > 0) {
+        const listed = clamped.slice(0, MAX_LISTED_CLAMPED_LINES);
+        notes.push({
+            code: "line-clamped",
+            severity: "warning",
+            message: messages.lineClamped({
+                lines: listed,
+                total: clamped.length,
+                maxChars: limits.maxCharsPerLine,
+            }),
+            data: { lines: [...listed], total: clamped.length, maxChars: limits.maxCharsPerLine },
+        });
+    }
+    if (scanCapped) {
+        notes.push({
+            code: "scan-limit",
+            severity: "warning",
+            message: messages.scanLimit({ maxScanBytes: limits.maxScanBytes }),
+            data: { maxScanBytes: limits.maxScanBytes },
+        });
+    }
+    if (!scanCapped &&
+        scanner.lines.length === 0 &&
+        request.offset > scanner.totalLines &&
+        scanner.totalLines > 0) {
+        const retry = retryFrom(request, Math.max(1, scanner.totalLines));
+        notes.push({
+            code: "offset-past-eof",
+            severity: "info",
+            message: messages.offsetPastEof({
+                request,
+                totalLines: scanner.totalLines,
+                retry: messages.retry(retry),
+            }),
+            retry,
+            data: { totalLines: scanner.totalLines },
+        });
+    }
+    return notes;
+}
+export function emptyNote(messages, path) {
+    return { code: "empty", severity: "info", message: messages.empty({ path }) };
+}
+function retryFrom(request, offset) {
+    return { path: request.path, offset, limit: request.limit };
+}

package/dist/core/observation.d.ts

@@ -0,0 +1,11 @@
+import type { Digest } from "../contract/digest.ts";
+import type { ContentPart, FileInfo, ReadObservation } from "../contract/result.ts";
+export interface ObservationInput {
+    readonly file: FileInfo;
+    readonly contentId: string | null;
+    readonly view: string | readonly ContentPart[];
+    readonly observedAt: string;
+    readonly wholeFileVisible: boolean;
+}
+export declare function buildObservation(digest: Digest | null, input: ObservationInput): ReadObservation | null;
+export declare function withEditedView(digest: Digest, observation: ReadObservation, view: string | readonly ContentPart[]): ReadObservation;

package/dist/core/observation.js

@@ -0,0 +1,51 @@
+const ENCODER = new TextEncoder();
+export function buildObservation(digest, input) {
+    if (digest === null)
+        return null;
+    const statId = digest.hash(JSON.stringify({
+        resolvedPath: input.file.resolvedPath,
+        identity: input.file.identity,
+        size: input.file.size,
+        mtimeMs: input.file.mtimeMs,
+    }));
+    const viewId = viewIdOf(digest, input.view);
+    return {
+        id: observationId(digest, statId, input.contentId, viewId),
+        statId,
+        contentId: input.contentId,
+        viewId,
+        observedAt: input.observedAt,
+        wholeFileVisible: input.wholeFileVisible,
+    };
+}
+export function withEditedView(digest, observation, view) {
+    const viewId = viewIdOf(digest, view);
+    return {
+        ...observation,
+        id: observationId(digest, observation.statId, observation.contentId, viewId),
+        viewId,
+        wholeFileVisible: false,
+    };
+}
+function viewIdOf(digest, view) {
+    return typeof view === "string" ? digest.hash(view) : partsId(digest, view);
+}
+function observationId(digest, statId, contentId, viewId) {
+    return digest.hash(JSON.stringify([statId, contentId, viewId]));
+}
+function partsId(digest, parts) {
+    const stream = digest.create();
+    // Type and length prefixes stop different part lists from hashing the same.
+    for (const part of parts) {
+        if (part.type === "text") {
+            const bytes = ENCODER.encode(part.text);
+            stream.update(ENCODER.encode(`text:${bytes.byteLength}:`));
+            stream.update(bytes);
+        }
+        else {
+            stream.update(ENCODER.encode(`media:${part.mediaType}:${part.data.byteLength}:`));
+            stream.update(part.data);
+        }
+    }
+    return stream.digest();
+}

package/dist/core/open.d.ts

@@ -0,0 +1,16 @@
+import type { FileSystem, NotAFileError, OpenFile, OpenFileInfo } from "@better-fs-tools/fs";
+import type { ReadDependencies } from "../contract/deps.ts";
+import type { DirectoryConverter } from "../contract/extensions.ts";
+import type { ReadRequest } from "../contract/input.ts";
+import type { FileInfo } from "../contract/result.ts";
+import type { CallScope } from "./call-scope.ts";
+export type Opened<THost> = {
+    readonly kind: "file";
+    readonly handle: OpenFile;
+} | {
+    readonly kind: "directory";
+    readonly error: NotAFileError;
+    readonly converter: DirectoryConverter<THost>;
+};
+export declare function openFile<THost>(deps: ReadDependencies<THost>, fs: FileSystem, request: ReadRequest, path: string, scope: CallScope<THost>): Promise<Opened<THost>>;
+export declare function fileInfo(fs: FileSystem, request: ReadRequest, info: OpenFileInfo, resolvedFrom: string | null): FileInfo;

package/dist/core/open.js

@@ -0,0 +1,33 @@
+import { directoryConverter } from "./directory.js";
+import { ReadStop, fromFileSystemError } from "./outcomes.js";
+import { missOutcome } from "./suggest.js";
+export async function openFile(deps, fs, request, path, scope) {
+    const signal = scope.signal;
+    const opened = await fs.open(path, signal === undefined ? {} : { signal });
+    if (opened.ok)
+        return { kind: "file", handle: opened.file };
+    const { error } = opened;
+    if (error.reason === "not-found") {
+        throw new ReadStop(await missOutcome(deps, request, fs, scope, path, error));
+    }
+    if (error.reason === "not-a-file" && error.kind === "directory") {
+        const converter = directoryConverter(scope, fs);
+        if (converter !== null)
+            return { kind: "directory", error, converter };
+    }
+    throw new ReadStop(fromFileSystemError(deps.messages, request, error, scope.phase));
+}
+export function fileInfo(fs, request, info, resolvedFrom) {
+    return {
+        requestedPath: request.path,
+        resolvedPath: info.resolvedPath,
+        displayPath: info.displayPath,
+        backend: fs.id,
+        size: info.size,
+        mtimeMs: info.mtimeMs,
+        identity: fs.capabilities.identity ? info.identity : null,
+        mimeType: info.mimeType,
+        resolvedFrom,
+        version: info.version ?? null,
+    };
+}

package/dist/core/outcomes.d.ts

@@ -0,0 +1,27 @@
+import type { FileSystemError } from "@better-fs-tools/fs";
+import type { UnsupportedClassification } from "../contract/classify.ts";
+import type { ReadRequest } from "../contract/input.ts";
+import type { JsonValue } from "../contract/json.ts";
+import type { ReadMessageCatalog, ReadPhase } from "../contract/messages.ts";
+import type { FileInfo, ReadErrorCode, ReadFailure, ReadNote, ReadReport, ReadUnsupported } from "../contract/result.ts";
+type Messages = Readonly<ReadMessageCatalog>;
+export declare class ReadStop extends Error {
+    readonly outcome: ReadReport;
+    constructor(outcome: ReadReport);
+}
+export declare function failure(code: ReadErrorCode, phase: ReadPhase, request: ReadRequest | null, file: FileInfo | null, note: ReadNote): ReadFailure;
+export declare function invalidInput(messages: Messages, input: unknown, error: unknown): ReadFailure;
+export declare function aborted(messages: Messages, request: ReadRequest, phase: ReadPhase): ReadFailure;
+export declare function extensionFailed(messages: Messages, request: ReadRequest, extension: string, phase: ReadPhase, id?: string | null): ReadFailure;
+export declare function hostErrorNote(code: ReadErrorCode, note: ReadNote): ReadNote;
+export declare function denied(messages: Messages, request: ReadRequest, note: ReadNote | null): ReadFailure;
+export declare function ioError(messages: Messages, request: ReadRequest, phase: ReadPhase, error: unknown): ReadFailure;
+export declare function changedDuringRead(messages: Messages, request: ReadRequest, file: FileInfo): ReadFailure;
+export declare function unsupportedBackend(messages: Messages, request: ReadRequest, phase: ReadPhase, file: FileInfo, detail: string | null): ReadFailure;
+export declare function unsupportedOutcome(request: ReadRequest, file: FileInfo, classifier: string, classification: UnsupportedClassification): ReadUnsupported;
+export declare function fromFileSystemError(messages: Messages, request: ReadRequest, error: FileSystemError, phase: ReadPhase, file?: FileInfo | null): ReadFailure;
+export declare function errorData(error: FileSystemError): Record<string, JsonValue>;
+export declare function notFound(messages: Messages, request: ReadRequest, suggestions: readonly string[], data: Record<string, JsonValue>): ReadFailure;
+export declare function isNote(value: unknown): value is ReadNote;
+export declare function messageOf(error: unknown): string;
+export {};

package/dist/core/outcomes.js

@@ -0,0 +1,172 @@
+import { classificationInfo } from "./classify.js";
+import { isRecord } from "./input.js";
+export class ReadStop extends Error {
+    outcome;
+    constructor(outcome) {
+        super(`read stopped with ${outcome.status}`);
+        this.outcome = outcome;
+    }
+}
+export function failure(code, phase, request, file, note) {
+    const error = {
+        code,
+        phase,
+        message: note.message,
+        ...(note.data === undefined ? {} : { data: note.data }),
+    };
+    return { tool: "read", status: "error", error, request, file, notes: [note] };
+}
+export function invalidInput(messages, input, error) {
+    const path = isRecord(input) && typeof input.path === "string" ? input.path : "";
+    return failure("INVALID_INPUT", "input", null, null, {
+        code: "invalid-input",
+        severity: "warning",
+        message: messages.invalidInput({ detail: messageOf(error) }),
+        ...(path === "" ? {} : { data: { path } }),
+    });
+}
+export function aborted(messages, request, phase) {
+    return failure("ABORTED", phase, request, null, {
+        code: "aborted",
+        severity: "warning",
+        message: messages.aborted({ phase }),
+        data: { phase },
+    });
+}
+export function extensionFailed(messages, request, extension, phase, id = null) {
+    return failure("EXTENSION_FAILED", phase, request, null, {
+        code: "extension-failed",
+        severity: "warning",
+        message: messages.extensionFailed({ request, extension, phase }),
+        data: id === null ? { extension, phase } : { extension, phase, id },
+    });
+}
+export function hostErrorNote(code, note) {
+    const kebab = code.toLowerCase().replaceAll("_", "-");
+    const data = note.code === kebab ? note.data : { ...note.data, source: note.code };
+    return {
+        code: kebab,
+        severity: "warning",
+        message: note.message,
+        ...(data === undefined ? {} : { data }),
+        ...(note.retry === undefined ? {} : { retry: note.retry }),
+    };
+}
+export function denied(messages, request, note) {
+    return failure("DENIED", "authorize", request, 
+    // No file info: a denial must not disclose the open target.
+    null, note === null
+        ? {
+            code: "denied",
+            severity: "warning",
+            message: messages.denied({ path: request.path, detail: null }),
+        }
+        : hostErrorNote("DENIED", note));
+}
+export function ioError(messages, request, phase, error) {
+    return failure("IO_ERROR", phase, request, null, {
+        code: "io-error",
+        severity: "warning",
+        message: messages.ioError({ request }),
+        data: { detail: messageOf(error) },
+    });
+}
+export function changedDuringRead(messages, request, file) {
+    const retry = { path: request.path, offset: request.offset, limit: request.limit };
+    return failure("CHANGED_DURING_READ", "verification", request, file, {
+        code: "changed-during-read",
+        severity: "warning",
+        message: messages.changedDuringRead({ request, retry: messages.retry(retry) }),
+        retry,
+    });
+}
+export function unsupportedBackend(messages, request, phase, file, detail) {
+    return failure("UNSUPPORTED_BACKEND", phase, request, file, {
+        code: "unsupported-backend",
+        severity: "warning",
+        message: messages.unsupportedBackend({ request, detail }),
+    });
+}
+export function unsupportedOutcome(request, file, classifier, classification) {
+    return {
+        tool: "read",
+        status: "unsupported",
+        code: classification.code,
+        request,
+        file,
+        classification: classificationInfo({ classifier, classification }),
+        notes: [classification.note],
+    };
+}
+const CODE_BY_REASON = {
+    "not-found": "NOT_FOUND",
+    "not-a-file": "NOT_A_FILE",
+    "dangerous-path": "DANGEROUS_PATH",
+    "outside-allowed-roots": "OUTSIDE_ALLOWED_ROOTS",
+    "permission-denied": "PERMISSION_DENIED",
+    denied: "DENIED",
+    "too-large": "TOO_LARGE",
+    unsupported: "UNSUPPORTED_BACKEND",
+    aborted: "ABORTED",
+    io: "IO_ERROR",
+};
+export function fromFileSystemError(messages, request, error, phase, file = null) {
+    const code = CODE_BY_REASON[error.reason];
+    if (code === "ABORTED")
+        return aborted(messages, request, phase);
+    const detail = error.detail ?? null;
+    const data = errorData(error);
+    return failure(code, phase, request, file, {
+        code: code.toLowerCase().replaceAll("_", "-"),
+        severity: "warning",
+        message: messageForError(messages, request, error, detail),
+        ...(Object.keys(data).length === 0 ? {} : { data }),
+    });
+}
+export function errorData(error) {
+    return {
+        ...(error.reason === "not-a-file" ? { kind: error.kind } : {}),
+        ...(error.reason === "too-large" ? { limit: error.limit, size: error.size } : {}),
+        ...(error.detail === undefined ? {} : { detail: error.detail }),
+        ...(error.cause === undefined ? {} : { cause: { ...error.cause } }),
+    };
+}
+export function notFound(messages, request, suggestions, data) {
+    return failure("NOT_FOUND", "resolve", request, null, {
+        code: "not-found",
+        severity: "warning",
+        message: messages.notFound({ request, suggestions }),
+        ...(Object.keys(data).length === 0 ? {} : { data }),
+    });
+}
+function messageForError(messages, request, error, detail) {
+    switch (error.reason) {
+        case "not-found":
+            return messages.notFound({ request, suggestions: [] });
+        case "not-a-file":
+            return messages.notAFile({ request, kind: error.kind });
+        case "dangerous-path":
+            return messages.dangerousPath({ request, detail });
+        case "outside-allowed-roots":
+            return messages.outsideAllowedRoots({ request, detail });
+        case "permission-denied":
+            return messages.permissionDenied({ request, detail });
+        case "denied":
+            return messages.denied({ path: request.path, detail });
+        case "too-large":
+            return messages.tooLarge({ request, stage: "backend", limit: error.limit });
+        case "unsupported":
+            return messages.unsupportedBackend({ request, detail });
+        default:
+            return messages.ioError({ request });
+    }
+}
+export function isNote(value) {
+    return (isRecord(value) &&
+        typeof value.code === "string" &&
+        typeof value.message === "string" &&
+        (value.severity === "info" || value.severity === "warning"));
+}
+export function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/core/pipeline.d.ts

@@ -0,0 +1,4 @@
+import type { ReadContext } from "../contract/context.ts";
+import type { ReadDependencies } from "../contract/deps.ts";
+import type { ReadResult } from "../contract/result.ts";
+export declare function runRead<THost>(deps: ReadDependencies<THost>, input: unknown, call: ReadContext<THost>): Promise<ReadResult>;