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

package/dist/authorize/ask-user.d.ts

@@ -0,0 +1,7 @@
+import type { ReadAuthorizer, ReadAuthorizeTarget, ReadHookContext } from "../contract/extensions.ts";
+/**
+ * Asks `prompt` before each file read. Anything but `true`, or a throw, denies.
+ * Directory listings are allowed without asking. To remember answers, keep
+ * them in ctx.call.host. An abort ends the read even when the prompt ignores it.
+ */
+export declare function askUser<THost>(prompt: (target: ReadAuthorizeTarget, ctx: ReadHookContext<THost>) => Promise<boolean>): ReadAuthorizer<THost>;

package/dist/authorize/ask-user.js

@@ -0,0 +1,25 @@
+import { ALLOW, deny } from "./shared.js";
+/**
+ * Asks `prompt` before each file read. Anything but `true`, or a throw, denies.
+ * Directory listings are allowed without asking. To remember answers, keep
+ * them in ctx.call.host. An abort ends the read even when the prompt ignores it.
+ */
+export function askUser(prompt) {
+    if (typeof prompt !== "function")
+        throw new TypeError("askUser takes a prompt function");
+    return Object.freeze({
+        id: "ask-user",
+        async authorize(target, ctx) {
+            if (target.action !== "read")
+                return ALLOW;
+            let approved = false;
+            try {
+                approved = await prompt(target, ctx);
+            }
+            catch {
+                approved = false;
+            }
+            return approved === true ? ALLOW : deny(ctx, target, "the user did not approve the read");
+        },
+    });
+}

package/dist/authorize/authorizers.d.ts

@@ -0,0 +1,7 @@
+import type { ReadAuthorizer } from "../contract/extensions.ts";
+/**
+ * Runs authorizers left to right. The first deny wins, with that step's note.
+ * Allow notes from every step are kept in order. An empty chain allows. A step
+ * that throws fails the read with EXTENSION_FAILED, naming the step's id.
+ */
+export declare function readAuthorizers<THost = unknown>(...steps: readonly ReadAuthorizer<NoInfer<THost>>[]): ReadAuthorizer<THost>;

package/dist/authorize/authorizers.js

@@ -0,0 +1,34 @@
+import { stepFailure } from "../core/extension-error.js";
+/**
+ * Runs authorizers left to right. The first deny wins, with that step's note.
+ * Allow notes from every step are kept in order. An empty chain allows. A step
+ * that throws fails the read with EXTENSION_FAILED, naming the step's id.
+ */
+export function readAuthorizers(...steps) {
+    for (const step of steps) {
+        if (step === null || typeof step !== "object" || typeof step.authorize !== "function") {
+            throw new TypeError("readAuthorizers takes authorizers");
+        }
+    }
+    const chain = Object.freeze([...steps]);
+    return Object.freeze({
+        id: chain.length === 0 ? "allow" : chain.map((step) => step.id).join("+"),
+        async authorize(target, ctx) {
+            const notes = [];
+            for (const step of chain) {
+                let decision;
+                try {
+                    decision = await step.authorize(target, ctx);
+                    if (!decision.allow)
+                        return decision;
+                }
+                catch (error) {
+                    throw stepFailure(step, error);
+                }
+                if (decision.notes !== undefined)
+                    notes.push(...decision.notes);
+            }
+            return notes.length === 0 ? { allow: true } : { allow: true, notes };
+        },
+    });
+}

package/dist/authorize/deny-paths.d.ts

@@ -0,0 +1,7 @@
+import type { ToolAuthorizer } from "../contract/base.ts";
+/**
+ * Denies any action, in any tool, on a resolvedPath that matches one of the
+ * globs ("**", "*", "?"). For a read the resolvedPath is the realpath, so a
+ * symlink to a denied file is denied.
+ */
+export declare function denyPaths(patterns: readonly string[]): ToolAuthorizer<unknown>;

package/dist/authorize/deny-paths.js

@@ -0,0 +1,25 @@
+import { compileGlob } from "./glob.js";
+import { ALLOW, deny } from "./shared.js";
+/**
+ * Denies any action, in any tool, on a resolvedPath that matches one of the
+ * globs ("**", "*", "?"). For a read the resolvedPath is the realpath, so a
+ * symlink to a denied file is denied.
+ */
+export function denyPaths(patterns) {
+    if (!Array.isArray(patterns) ||
+        !patterns.every((pattern) => typeof pattern === "string" && pattern !== "")) {
+        throw new TypeError("denyPaths takes an array of non-empty glob strings");
+    }
+    const compiled = patterns.map((pattern) => ({ pattern, test: compileGlob(pattern) }));
+    return Object.freeze({
+        id: "deny-paths",
+        authorize(target, ctx) {
+            const hit = compiled.find((entry) => entry.test(target.resolvedPath));
+            if (hit === undefined)
+                return ALLOW;
+            return deny(ctx, target, "the path matches a denied pattern", {
+                data: { pattern: hit.pattern },
+            });
+        },
+    });
+}

package/dist/authorize/glob.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compiles a glob into a matcher for "/"-separated paths. A "**" segment
+ * matches zero or more whole segments. "*" matches any run of characters within
+ * a segment, and "?" one character. Dot names get no special case. Every other
+ * character matches itself. Matching time is linear in pattern and path length.
+ */
+export declare function compileGlob(pattern: string): (path: string) => boolean;

package/dist/authorize/glob.js

@@ -0,0 +1,46 @@
+const GLOBSTAR = Symbol("globstar");
+/**
+ * Compiles a glob into a matcher for "/"-separated paths. A "**" segment
+ * matches zero or more whole segments. "*" matches any run of characters within
+ * a segment, and "?" one character. Dot names get no special case. Every other
+ * character matches itself. Matching time is linear in pattern and path length.
+ */
+export function compileGlob(pattern) {
+    const segments = pattern
+        .split("/")
+        .map((segment) => (segment === "**" ? GLOBSTAR : segmentPattern(segment)));
+    return (path) => matches(segments, path.split("/"));
+}
+function segmentPattern(segment) {
+    let source = "";
+    for (const char of segment) {
+        if (char === "*")
+            source += "[^/]*";
+        else if (char === "?")
+            source += "[^/]";
+        else
+            source += char.replace(/[\\^$.|+()[\]{}]/g, "\\$&");
+    }
+    return new RegExp(`^${source}$`, "u");
+}
+function matches(segments, parts) {
+    let segmentsMatchFirstParts = parts.map(() => false).concat(false);
+    segmentsMatchFirstParts[0] = true;
+    for (const segment of segments) {
+        const next = segmentsMatchFirstParts.map(() => false);
+        if (segment === GLOBSTAR) {
+            let anyEarlierMatched = false;
+            for (let j = 0; j <= parts.length; j += 1) {
+                anyEarlierMatched ||= segmentsMatchFirstParts[j] === true;
+                next[j] = anyEarlierMatched;
+            }
+        }
+        else {
+            for (let j = 1; j <= parts.length; j += 1) {
+                next[j] = segmentsMatchFirstParts[j - 1] === true && segment.test(parts[j - 1] ?? "");
+            }
+        }
+        segmentsMatchFirstParts = next;
+    }
+    return segmentsMatchFirstParts[parts.length] === true;
+}

package/dist/authorize/index.d.ts

@@ -0,0 +1,5 @@
+export { askUser } from "./ask-user.ts";
+export { readAuthorizers } from "./authorizers.ts";
+export { denyPaths } from "./deny-paths.ts";
+export { compileGlob } from "./glob.ts";
+export { sizeCeiling } from "./size-ceiling.ts";

package/dist/authorize/index.js

@@ -0,0 +1,5 @@
+export { askUser } from "./ask-user.js";
+export { readAuthorizers } from "./authorizers.js";
+export { denyPaths } from "./deny-paths.js";
+export { compileGlob } from "./glob.js";
+export { sizeCeiling } from "./size-ceiling.js";

package/dist/authorize/shared.d.ts

@@ -0,0 +1,9 @@
+import type { AccessTarget, ToolHookContext } from "../contract/base.ts";
+import type { ReadAuthorizeDecision } from "../contract/extensions.ts";
+import type { JsonObject } from "../contract/json.ts";
+import type { ReadInput } from "../contract/input.ts";
+export declare const ALLOW: ReadAuthorizeDecision;
+export declare function deny(ctx: ToolHookContext<unknown>, target: AccessTarget, detail: string, extra?: {
+    readonly data?: JsonObject;
+    readonly retry?: ReadInput;
+}): ReadAuthorizeDecision;

package/dist/authorize/shared.js

@@ -0,0 +1,12 @@
+export const ALLOW = Object.freeze({ allow: true });
+export function deny(ctx, target, detail, extra = {}) {
+    return {
+        allow: false,
+        note: {
+            code: "denied",
+            severity: "warning",
+            message: ctx.messages.denied({ path: target.requestedPath, detail }),
+            ...extra,
+        },
+    };
+}

package/dist/authorize/size-ceiling.d.ts

@@ -0,0 +1,10 @@
+import type { ReadAuthorizer } from "../contract/extensions.ts";
+/**
+ * Denies reading a file larger than `maxBytes`. With `unrangedOnly`, denies
+ * only whole-file reads, and the note offers a ranged retry. Unknown sizes and
+ * directory listings are allowed.
+ */
+export declare function sizeCeiling(options: {
+    maxBytes: number;
+    unrangedOnly?: boolean;
+}): ReadAuthorizer<unknown>;

package/dist/authorize/size-ceiling.js

@@ -0,0 +1,34 @@
+import { ALLOW, deny } from "./shared.js";
+/**
+ * Denies reading a file larger than `maxBytes`. With `unrangedOnly`, denies
+ * only whole-file reads, and the note offers a ranged retry. Unknown sizes and
+ * directory listings are allowed.
+ */
+export function sizeCeiling(options) {
+    const { maxBytes, unrangedOnly = false } = options ?? {};
+    if (typeof maxBytes !== "number" || !Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+        throw new TypeError("sizeCeiling maxBytes must be a non-negative safe integer");
+    }
+    if (typeof unrangedOnly !== "boolean") {
+        throw new TypeError("sizeCeiling unrangedOnly must be a boolean");
+    }
+    return Object.freeze({
+        id: "size-ceiling",
+        authorize(target, ctx) {
+            if (target.action !== "read" || target.size === null || target.size <= maxBytes) {
+                return ALLOW;
+            }
+            const data = { size: target.size, maxBytes };
+            if (!unrangedOnly) {
+                return deny(ctx, target, `${target.size} bytes is over the ${maxBytes}-byte ceiling`, {
+                    data,
+                });
+            }
+            if (ctx.request.ranged)
+                return ALLOW;
+            const { path, offset, limit } = ctx.request;
+            const retry = { path, offset, limit };
+            return deny(ctx, target, `${target.size} bytes is over the ${maxBytes}-byte ceiling for a whole-file read; a ranged read such as ${ctx.messages.retry(retry)} is allowed`, { data, retry });
+        },
+    });
+}

package/dist/budget/chars-per-token.d.ts

@@ -0,0 +1,9 @@
+import type { ViewBudget } from "../contract/extensions.ts";
+export interface CharsPerTokenOptions {
+    /** Characters per token. A positive number, for example 4. */
+    ratio: number;
+    /** Tokens in one view. A positive number. */
+    max: number;
+}
+/** Estimates tokens without a tokenizer: ceil(text.length / ratio) + 1 per line. */
+export declare function charsPerToken(options: CharsPerTokenOptions): ViewBudget;

package/dist/budget/chars-per-token.js

@@ -0,0 +1,15 @@
+/** Estimates tokens without a tokenizer: ceil(text.length / ratio) + 1 per line. */
+export function charsPerToken(options) {
+    const { ratio, max } = options ?? {};
+    if (typeof ratio !== "number" || !Number.isFinite(ratio) || ratio <= 0) {
+        throw new TypeError("charsPerToken ratio must be a positive number");
+    }
+    if (typeof max !== "number" || !Number.isFinite(max) || max <= 0) {
+        throw new TypeError("charsPerToken max must be a positive number");
+    }
+    return Object.freeze({
+        id: "chars-per-token",
+        max,
+        measure: (text) => Math.ceil(text.length / ratio) + 1,
+    });
+}

package/dist/budget/index.d.ts

@@ -0,0 +1,2 @@
+export { charsPerToken } from "./chars-per-token.ts";
+export type { CharsPerTokenOptions } from "./chars-per-token.ts";

package/dist/budget/index.js

@@ -0,0 +1 @@
+export { charsPerToken } from "./chars-per-token.js";

package/dist/classifiers/binary.d.ts

@@ -0,0 +1,5 @@
+import type { Classifier, NoteOverride } from "../contract/classify.ts";
+/** Refuses zip archives and samples that contain a NUL byte. */
+export declare function binaryClassifier(options?: {
+    note?: NoteOverride;
+}): Classifier;

package/dist/classifiers/binary.js

@@ -0,0 +1,13 @@
+import { classifier, isZip, unsupported } from "./shared.js";
+/** Refuses zip archives and samples that contain a NUL byte. */
+export function binaryClassifier(options = {}) {
+    return classifier("binary", (sample) => {
+        const suggestedTool = "a format-specific byte tool";
+        if (isZip(sample.bytes)) {
+            return unsupported("BINARY", "application/zip", ["zip-magic"], sample, options.note, suggestedTool);
+        }
+        if (!sample.bytes.includes(0))
+            return null;
+        return unsupported("BINARY", null, ["nul-byte"], sample, options.note, suggestedTool);
+    });
+}

package/dist/classifiers/extension.d.ts

@@ -0,0 +1,17 @@
+import type { Classifier, NoteOverride } from "../contract/classify.ts";
+export interface ExtensionClassifierOptions {
+    /** Keyed by extension, with or without the leading dot. Case-insensitive. */
+    readonly unsupported?: Readonly<Record<string, {
+        code: string;
+        mimeType?: string;
+        note?: NoteOverride;
+    }>>;
+    /** Extensions forced to text. */
+    readonly text?: readonly string[];
+}
+/**
+ * Classifies by file extension alone, as Deep Agents and Mastra do. Place it
+ * before defaultClassifiers(). Its confidence is "medium", and an extension it
+ * does not know gets no opinion.
+ */
+export declare function extensionClassifier(options: ExtensionClassifierOptions): Classifier;

package/dist/classifiers/extension.js

@@ -0,0 +1,45 @@
+import { classifier, refusal } from "./shared.js";
+/**
+ * Classifies by file extension alone, as Deep Agents and Mastra do. Place it
+ * before defaultClassifiers(). Its confidence is "medium", and an extension it
+ * does not know gets no opinion.
+ */
+export function extensionClassifier(options) {
+    const unsupported = new Map(Object.entries(options.unsupported ?? {}).map(([key, value]) => [normalize(key), value]));
+    const text = new Set((options.text ?? []).map(normalize));
+    return classifier("extension", (sample) => {
+        const extension = extensionOf(sample.path);
+        if (extension === null)
+            return null;
+        const refused = unsupported.get(extension);
+        if (refused !== undefined) {
+            return refusal({
+                code: refused.code,
+                mimeType: refused.mimeType ?? null,
+                confidence: "medium",
+                reasons: [`extension:${extension}`],
+                sample,
+                override: refused.note,
+                message: `Files with the .${extension} extension are not supported as UTF-8 text.`,
+            });
+        }
+        if (!text.has(extension))
+            return null;
+        return {
+            kind: "text",
+            mimeType: sample.mimeType ?? "text/plain",
+            confidence: "medium",
+            reasons: [`extension:${extension}`],
+        };
+    });
+}
+function normalize(extension) {
+    return extension.replace(/^\./u, "").toLowerCase();
+}
+function extensionOf(path) {
+    const name = path.slice(path.lastIndexOf("/") + 1);
+    const index = name.lastIndexOf(".");
+    if (index <= 0 || index === name.length - 1)
+        return null;
+    return name.slice(index + 1).toLowerCase();
+}

package/dist/classifiers/image.d.ts

@@ -0,0 +1,5 @@
+import type { Classifier, NoteOverride } from "../contract/classify.ts";
+/** Refuses PNG, JPEG, GIF, and WebP files, detected by their magic bytes. */
+export declare function imageClassifier(options?: {
+    note?: NoteOverride;
+}): Classifier;

package/dist/classifiers/image.js

@@ -0,0 +1,22 @@
+import { asciiProjection, classifier, startsWith, startsWithAscii, unsupported } from "./shared.js";
+/** Refuses PNG, JPEG, GIF, and WebP files, detected by their magic bytes. */
+export function imageClassifier(options = {}) {
+    return classifier("image", (sample) => {
+        const mimeType = imageSignature(sample.bytes);
+        if (mimeType === null)
+            return null;
+        return unsupported("IMAGE", mimeType, ["image-magic"], sample, options.note, "an image or vision tool");
+    });
+}
+function imageSignature(bytes) {
+    if (startsWith(bytes, [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))
+        return "image/png";
+    if (startsWith(bytes, [0xff, 0xd8, 0xff]))
+        return "image/jpeg";
+    if (startsWithAscii(bytes, "GIF87a") || startsWithAscii(bytes, "GIF89a"))
+        return "image/gif";
+    if (startsWithAscii(bytes, "RIFF") && asciiProjection(bytes.subarray(8, 12)) === "WEBP") {
+        return "image/webp";
+    }
+    return null;
+}

package/dist/classifiers/index.d.ts

@@ -0,0 +1,16 @@
+import type { Classifier, DefaultClassifierOptions } from "../contract/classify.ts";
+export { binaryClassifier } from "./binary.ts";
+export { extensionClassifier } from "./extension.ts";
+export type { ExtensionClassifierOptions } from "./extension.ts";
+export { imageClassifier } from "./image.ts";
+export { notebookClassifier } from "./notebook.ts";
+export { officeClassifier } from "./office.ts";
+export { pdfClassifier } from "./pdf.ts";
+export { utf8Classifier } from "./utf8.ts";
+/**
+ * The built-in chain in evaluation order: image, pdf, office, binary, utf8.
+ * The first classifier with an opinion wins. utf8Classifier runs last and is
+ * the one that returns text. A notebook is JSON text here. Put
+ * notebookClassifier() before the chain to refuse or convert notebooks.
+ */
+export declare function defaultClassifiers(options?: DefaultClassifierOptions): Classifier[];

package/dist/classifiers/index.js

@@ -0,0 +1,31 @@
+import { binaryClassifier } from "./binary.js";
+import { imageClassifier } from "./image.js";
+import { officeClassifier } from "./office.js";
+import { pdfClassifier } from "./pdf.js";
+import { utf8Classifier } from "./utf8.js";
+export { binaryClassifier } from "./binary.js";
+export { extensionClassifier } from "./extension.js";
+export { imageClassifier } from "./image.js";
+export { notebookClassifier } from "./notebook.js";
+export { officeClassifier } from "./office.js";
+export { pdfClassifier } from "./pdf.js";
+export { utf8Classifier } from "./utf8.js";
+/**
+ * The built-in chain in evaluation order: image, pdf, office, binary, utf8.
+ * The first classifier with an opinion wins. utf8Classifier runs last and is
+ * the one that returns text. A notebook is JSON text here. Put
+ * notebookClassifier() before the chain to refuse or convert notebooks.
+ */
+export function defaultClassifiers(options = {}) {
+    const notes = options.notes ?? {};
+    return [
+        imageClassifier(withNote(notes.IMAGE)),
+        pdfClassifier(withNote(notes.PDF)),
+        officeClassifier(withNote(notes.OFFICE_DOCUMENT)),
+        binaryClassifier(withNote(notes.BINARY)),
+        utf8Classifier(withNote(notes.UNKNOWN_ENCODING)),
+    ];
+}
+function withNote(note) {
+    return note === undefined ? {} : { note };
+}

package/dist/classifiers/notebook.d.ts

@@ -0,0 +1,5 @@
+import type { Classifier, NoteOverride } from "../contract/classify.ts";
+/** Refuses Jupyter notebooks: JSON with nbformat and a cells array, plus an .ipynb name or metadata. */
+export declare function notebookClassifier(options?: {
+    note?: NoteOverride;
+}): Classifier;

package/dist/classifiers/notebook.js

@@ -0,0 +1,14 @@
+import { classifier, unsupported } from "./shared.js";
+/** Refuses Jupyter notebooks: JSON with nbformat and a cells array, plus an .ipynb name or metadata. */
+export function notebookClassifier(options = {}) {
+    return classifier("notebook", (sample) => {
+        const text = new TextDecoder("utf-8").decode(sample.bytes.subarray(0, 8_192));
+        const evidence = /^\s*\{/u.test(text) && /"nbformat"\s*:/u.test(text) && /"cells"\s*:\s*\[/u.test(text);
+        if (!evidence)
+            return null;
+        if (!sample.path.toLowerCase().endsWith(".ipynb") && !/"metadata"\s*:/u.test(text)) {
+            return null;
+        }
+        return unsupported("NOTEBOOK", "application/x-ipynb+json", ["notebook-json-evidence"], sample, options.note, "a notebook handler");
+    });
+}

package/dist/classifiers/office.d.ts

@@ -0,0 +1,5 @@
+import type { Classifier, NoteOverride } from "../contract/classify.ts";
+/** Refuses Office documents: a zip with an Office marker or an Office extension. */
+export declare function officeClassifier(options?: {
+    note?: NoteOverride;
+}): Classifier;

package/dist/classifiers/office.js

@@ -0,0 +1,30 @@
+import { asciiProjection, classifier, isZip, unsupported } from "./shared.js";
+/** Refuses Office documents: a zip with an Office marker or an Office extension. */
+export function officeClassifier(options = {}) {
+    return classifier("office", (sample) => {
+        if (!isZip(sample.bytes))
+            return null;
+        const path = sample.path.toLowerCase();
+        const marker = /\[Content_Types\]\.xml|word\/|xl\/|ppt\//u.test(asciiProjection(sample.bytes));
+        const extension = /\.(docx|xlsx|pptx)$/u.test(path);
+        if (!marker && !extension)
+            return null;
+        const reasons = [
+            ...(marker ? ["office-zip-marker"] : []),
+            ...(extension ? ["office-extension"] : []),
+        ];
+        return unsupported("OFFICE_DOCUMENT", officeMime(path), reasons, sample, options.note, "an office document handler");
+    });
+}
+function officeMime(path) {
+    if (path.endsWith(".docx")) {
+        return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+    }
+    if (path.endsWith(".xlsx")) {
+        return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+    }
+    if (path.endsWith(".pptx")) {
+        return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+    }
+    return "application/vnd.openxmlformats-officedocument";
+}

package/dist/classifiers/pdf.d.ts

@@ -0,0 +1,4 @@
+import type { Classifier, NoteOverride } from "../contract/classify.ts";
+export declare function pdfClassifier(options?: {
+    note?: NoteOverride;
+}): Classifier;

package/dist/classifiers/pdf.js

@@ -0,0 +1,8 @@
+import { classifier, startsWithAscii, unsupported } from "./shared.js";
+export function pdfClassifier(options = {}) {
+    return classifier("pdf", (sample) => {
+        if (!startsWithAscii(sample.bytes, "%PDF-"))
+            return null;
+        return unsupported("PDF", "application/pdf", ["pdf-magic"], sample, options.note, "a PDF extraction tool");
+    });
+}

package/dist/classifiers/shared.d.ts

@@ -0,0 +1,17 @@
+import type { BuiltInUnsupportedCode, Classification, ClassificationSample, Classifier, NoteOverride, UnsupportedClassification } from "../contract/classify.ts";
+import type { Confidence } from "../contract/result.ts";
+export declare function classifier(id: string, classify: (sample: ClassificationSample) => Classification | null): Classifier;
+export declare function unsupported(code: BuiltInUnsupportedCode, mimeType: string | null, reasons: readonly string[], sample: ClassificationSample, override: NoteOverride | undefined, suggestedTool: string): UnsupportedClassification;
+export declare function refusal(options: {
+    code: string;
+    mimeType: string | null;
+    confidence: Confidence;
+    reasons: readonly string[];
+    sample: ClassificationSample;
+    override: NoteOverride | undefined;
+    message: string;
+}): UnsupportedClassification;
+export declare function startsWith(bytes: Uint8Array, prefix: readonly number[]): boolean;
+export declare function startsWithAscii(bytes: Uint8Array, prefix: string): boolean;
+export declare function asciiProjection(bytes: Uint8Array): string;
+export declare function isZip(bytes: Uint8Array): boolean;

package/dist/classifiers/shared.js

@@ -0,0 +1,57 @@
+export function classifier(id, classify) {
+    return Object.freeze({ id, classify });
+}
+export function unsupported(code, mimeType, reasons, sample, override, suggestedTool) {
+    return refusal({
+        code,
+        mimeType,
+        confidence: "high",
+        reasons,
+        sample,
+        override,
+        message: `This content is not supported as UTF-8 text. Use ${suggestedTool}.`,
+    });
+}
+export function refusal(options) {
+    const { code, mimeType, confidence, reasons, sample, override } = options;
+    const base = {
+        code: `unsupported-${code.toLowerCase().replaceAll("_", "-")}`,
+        severity: "warning",
+        message: options.message,
+    };
+    return {
+        kind: "unsupported",
+        code: override?.code ?? code,
+        mimeType,
+        confidence,
+        reasons,
+        note: applyOverride(base, override, { path: sample.path, mimeType, reasons }),
+    };
+}
+function applyOverride(note, override, context) {
+    if (override === undefined)
+        return note;
+    const message = typeof override.message === "function" ? override.message(context) : override.message;
+    return {
+        code: override.code ?? note.code,
+        severity: override.severity ?? note.severity,
+        message: message ?? note.message,
+        ...(override.data === undefined ? {} : { data: override.data }),
+    };
+}
+export function startsWith(bytes, prefix) {
+    return prefix.every((byte, index) => bytes[index] === byte);
+}
+export function startsWithAscii(bytes, prefix) {
+    return startsWith(bytes, [...prefix].map((character) => character.charCodeAt(0)));
+}
+export function asciiProjection(bytes) {
+    let result = "";
+    for (const byte of bytes) {
+        result += byte >= 0x20 && byte <= 0x7e ? String.fromCharCode(byte) : " ";
+    }
+    return result;
+}
+export function isZip(bytes) {
+    return startsWith(bytes, [0x50, 0x4b, 0x03, 0x04]);
+}

package/dist/classifiers/utf8.d.ts

@@ -0,0 +1,8 @@
+import type { Classifier, NoteOverride } from "../contract/classify.ts";
+/**
+ * Accepts UTF-8 text and refuses invalid UTF-8 with UNKNOWN_ENCODING, also when
+ * the invalid bytes come after the sample. The only built-in that returns text.
+ */
+export declare function utf8Classifier(options?: {
+    note?: NoteOverride;
+}): Classifier;