mdrefine 0.2.0-rc.2 → 0.2.0

package/dist/workspace/discovery.d.ts

@@ -0,0 +1,85 @@
+import type { Config, Dialect, Plugin, ProcessOptions } from "../core/types.js";
+import type { Skipped } from "./files.js";
+import type { Vault } from "./vault.js";
+/** The options of `discoverWorkspace`. */
+export interface DiscoverOptions {
+    /** The workspace root: the folder whose documents are processed and whose files are link targets. */
+    root: string;
+    /**
+     * Files, folders, and patterns to select, absolute or relative to the root.
+     * A folder selects its Markdown files, those named `.md` or `.markdown`; a
+     * file is selected whatever its name. An input that names no existing path
+     * and holds pattern characters (`*`, `?`, `[`, `{`) is a pattern, with `/`
+     * between folders on every system: it selects the Markdown files that it
+     * matches, and matching none is an error. Ignored files are not selected,
+     * and an ignored file or folder named here is reported in `skipped`.
+     * Omitted, every document of the workspace is selected; an empty list
+     * selects none.
+     */
+    inputs?: string[];
+    /**
+     * Files and folders to leave out of the selection, absolute or relative to
+     * the root. They are paths, not patterns, and stay link targets.
+     */
+    exclude?: string[];
+    /** The configuration: its `ignore` and `resolve` settings, and the dialect of each document. */
+    config?: Config;
+    /** Plugin objects, whose rules and presets the configuration can name. */
+    plugins?: Plugin[];
+    /**
+     * Documents whose text the caller supplies, such as an editor's unsaved
+     * text, by path relative to the root. They are selected, and the workspace
+     * reads this text instead of a file at that path. One whose path ignore rules
+     * leave out is not selected and is reported in `skipped`, as a named file is.
+     */
+    documents?: Record<string, string>;
+}
+/** The files of a workspace that `discoverWorkspace` found, and how to process them. */
+export interface WorkspaceDiscovery {
+    /** The workspace root's real path. */
+    readonly root: string;
+    /** The documents to process, as forward-slash paths relative to the root, sorted. */
+    readonly selected: readonly string[];
+    /** What discovery could not read or use and left out, as in the CLI's JSON report. */
+    readonly skipped: readonly Skipped[];
+    /**
+     * The text of a selected document. A file is read when it is first needed
+     * and then kept; an error with the code `EACCES`, `EPERM`, or `EBUSY` means
+     * that the system did not let it be read, and one with the code
+     * `ERR_ENCODING_INVALID_ENCODED_DATA` that its bytes are not UTF-8 text.
+     */
+    read(path: string): string;
+    /**
+     * The options to lint or format a selected document with, as the CLI does:
+     * its path, the configuration and plugins, a workspace for its dialect with
+     * its vault's line-break setting, and the dialect to assume for a note.
+     */
+    options(path: string): ProcessOptions;
+}
+/**
+ * The dialect to assume for a document when nothing names one, or undefined for
+ * the library's own default. An Obsidian vault shows a single line break as a
+ * line break and holds wikilinks, both of which any other dialect lets reflow
+ * change, so a document that a vault holds is read as a note.
+ */
+export declare function assumedDialect(vault: Vault | string | undefined): Dialect | undefined;
+/**
+ * Stops when `given` cannot serve as a workspace root, with a message that
+ * names it. Without this check the first thing to fail could be a search
+ * inside it, with a message about a path the user never named.
+ */
+export declare function checkRoot(given: string): Promise<void>;
+/**
+ * Find the files of a workspace and select documents the way the CLI does:
+ * honoring Git's ignore rules and the configuration's `ignore` and `resolve`
+ * settings, skipping links, nested repositories, and what the system does not
+ * let the tool read, and recognizing each document's Obsidian vault. Nothing
+ * is written.
+ */
+export declare function discoverWorkspace(options: DiscoverOptions): Promise<WorkspaceDiscovery>;
+/**
+ * The same, with relative inputs and exclusions resolved from `base`. Without
+ * `ignoreDocuments`, ignore rules do not leave out the supplied documents, as
+ * for text from stdin without a path of its own.
+ */
+export declare function discoverFrom(options: DiscoverOptions, base: string, ignoreDocuments?: boolean): Promise<WorkspaceDiscovery>;

package/dist/workspace/discovery.js

@@ -0,0 +1,155 @@
+import { access, stat } from "node:fs/promises";
+import { constants } from "node:fs";
+import path from "node:path";
+import { resolveConfig } from "../config/resolve.js";
+import { pathError } from "./access.js";
+import { discover, isIgnoredInput, unlistedLookup, vaultFor } from "./files.js";
+import { createWorkspace } from "./index.js";
+import { excludeSelection } from "./selection.js";
+import { vaultOf } from "./vault.js";
+/**
+ * The dialect to assume for a document when nothing names one, or undefined for
+ * the library's own default. An Obsidian vault shows a single line break as a
+ * line break and holds wikilinks, both of which any other dialect lets reflow
+ * change, so a document that a vault holds is read as a note.
+ */
+export function assumedDialect(vault) {
+    return vault ? "obsidian" : undefined;
+}
+/**
+ * Stops when `given` cannot serve as a workspace root, with a message that
+ * names it. Without this check the first thing to fail could be a search
+ * inside it, with a message about a path the user never named.
+ */
+export async function checkRoot(given) {
+    const root = path.resolve(given);
+    try {
+        if (!(await stat(root)).isDirectory())
+            throw new Error(`Workspace root is not a directory: ${root}`);
+        await access(root, constants.R_OK | constants.X_OK);
+    }
+    catch (error) {
+        throw pathError("Workspace root", root, error);
+    }
+}
+/**
+ * Find the files of a workspace and select documents the way the CLI does:
+ * honoring Git's ignore rules and the configuration's `ignore` and `resolve`
+ * settings, skipping links, nested repositories, and what the system does not
+ * let the tool read, and recognizing each document's Obsidian vault. Nothing
+ * is written.
+ */
+export function discoverWorkspace(options) {
+    return discoverFrom(options, path.resolve(options.root));
+}
+/**
+ * The same, with relative inputs and exclusions resolved from `base`. Without
+ * `ignoreDocuments`, ignore rules do not leave out the supplied documents, as
+ * for text from stdin without a path of its own.
+ */
+export async function discoverFrom(options, base, ignoreDocuments = true) {
+    await checkRoot(options.root);
+    // Which files to leave out does not depend on a document's dialect.
+    const resolved = resolveConfig({ config: options.config, plugins: options.plugins });
+    const documents = new Map();
+    for (const [given, text] of Object.entries(options.documents ?? {})) {
+        const name = path.posix.normalize(given.split(path.sep).join("/"));
+        if (name === "." || name === ".." || name.startsWith("../") || path.isAbsolute(given))
+            throw new Error(`Document path is outside the workspace: ${given}`);
+        documents.set(name, text);
+    }
+    // Discovery always visits the whole workspace, whose files are link targets;
+    // the inputs only choose what is selected.
+    const none = options.inputs?.length === 0;
+    const set = await discover(options.root, none ? [] : (options.inputs ?? []), resolved.ignore, resolved.resolve, base, { documents: ignoreDocuments ? [...documents.keys()] : [], selectNone: none });
+    set.selected = none
+        ? []
+        : await excludeSelection(set.root, set.selected, options.exclude ?? [], base);
+    // A supplied document that ignore rules leave out is reported as a named
+    // file is, and not selected.
+    const ignored = new Set(set.skipped.flatMap((item) => item.type === "file" && isIgnoredInput(item) ? [item.path] : []));
+    // A supplied document can lie in a folder that discovery did not visit, so
+    // its vault is found by a search of its own.
+    const supplied = new Map();
+    for (const [name, text] of documents) {
+        set.files[name] = text;
+        if (!ignored.has(name))
+            supplied.set(name, undefined);
+    }
+    for (const name of supplied.keys())
+        supplied.set(name, await vaultFor(set, name));
+    const selected = [...new Set([...set.selected, ...supplied.keys()])].sort();
+    const chosen = new Set(selected);
+    const known = (name) => {
+        if (!chosen.has(name))
+            throw new Error(`Not a selected document: ${name}`);
+    };
+    // One index per active dialect, built when a document of the dialect is first
+    // processed, and a view of it with each vault's line-break setting.
+    const indexes = new Map();
+    const views = new Map();
+    // Links into folders that discovery does not enter are checked on disk.
+    const lookup = unlistedLookup(set);
+    function index(dialect) {
+        let workspace = indexes.get(dialect);
+        if (workspace)
+            return workspace;
+        // The vault that the root is a folder of, if it is one: links may lead out of sight.
+        const enclosing = set.vaults.find((item) => item.rootInVault);
+        workspace = createWorkspace(set.files, {
+            dialect,
+            directories: set.directories,
+            // Links into a directory that could not be read are unchecked, not missing.
+            unreadable: set.skipped.flatMap((item) => item.type === "directory" && item.code !== "IGNORED" ? [item.path] : []),
+            // The vault at or above the root holds the whole workspace and needs no entry.
+            vaults: set.vaults.flatMap((item) => (item.path ? [item.path] : [])),
+            ...(enclosing?.rootInVault ? { rootInVault: enclosing.rootInVault } : {}),
+            lookup,
+        });
+        indexes.set(dialect, workspace);
+        return workspace;
+    }
+    return {
+        root: set.root,
+        selected,
+        skipped: set.skipped,
+        read(name) {
+            known(name);
+            const value = set.files[name];
+            if (typeof value === "string")
+                return value;
+            if (typeof value === "function")
+                return value();
+            throw new Error(`Not a Markdown document: ${name}`);
+        },
+        options(name) {
+            known(name);
+            const vault = supplied.has(name) ? supplied.get(name) : vaultOf(set.vaults, name);
+            const assumed = assumedDialect(vault);
+            const { dialect } = resolveConfig({
+                config: options.config,
+                path: name,
+                plugins: options.plugins,
+                defaultDialect: assumed,
+            });
+            let workspace = index(dialect);
+            // Whether a note may be reflowed is a setting of its own vault.
+            if (vault?.strictLineBreaks !== undefined) {
+                let ofDialect = views.get(dialect);
+                if (!ofDialect)
+                    views.set(dialect, (ofDialect = new Map()));
+                const shared = workspace;
+                workspace = ofDialect.get(vault) ?? { ...shared, strictLineBreaks: vault.strictLineBreaks };
+                ofDialect.set(vault, workspace);
+            }
+            return {
+                path: name,
+                ...(options.config ? { config: options.config } : {}),
+                ...(options.plugins ? { plugins: options.plugins } : {}),
+                workspace,
+                ...(assumed ? { defaultDialect: assumed } : {}),
+            };
+        },
+    };
+}
+//# sourceMappingURL=discovery.js.map

package/dist/workspace/discovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/workspace/discovery.ts"],"names":[],"mappings":"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","sourcesContent":["import { access, stat } from \"node:fs/promises\";\nimport { constants } from \"node:fs\";\nimport path from \"node:path\";\nimport { resolveConfig } from \"../config/resolve.js\";\nimport type { Config, Dialect, Plugin, ProcessOptions, Workspace } from \"../core/types.js\";\nimport { pathError } from \"./access.js\";\nimport { discover, isIgnoredInput, unlistedLookup, vaultFor } from \"./files.js\";\nimport type { Skipped } from \"./files.js\";\nimport { createWorkspace } from \"./index.js\";\nimport { excludeSelection } from \"./selection.js\";\nimport { vaultOf } from \"./vault.js\";\nimport type { Vault } from \"./vault.js\";\n\n/** The options of `discoverWorkspace`. */\nexport interface DiscoverOptions {\n  /** The workspace root: the folder whose documents are processed and whose files are link targets. */\n  root: string;\n  /**\n   * Files, folders, and patterns to select, absolute or relative to the root.\n   * A folder selects its Markdown files, those named `.md` or `.markdown`; a\n   * file is selected whatever its name. An input that names no existing path\n   * and holds pattern characters (`*`, `?`, `[`, `{`) is a pattern, with `/`\n   * between folders on every system: it selects the Markdown files that it\n   * matches, and matching none is an error. Ignored files are not selected,\n   * and an ignored file or folder named here is reported in `skipped`.\n   * Omitted, every document of the workspace is selected; an empty list\n   * selects none.\n   */\n  inputs?: string[];\n  /**\n   * Files and folders to leave out of the selection, absolute or relative to\n   * the root. They are paths, not patterns, and stay link targets.\n   */\n  exclude?: string[];\n  /** The configuration: its `ignore` and `resolve` settings, and the dialect of each document. */\n  config?: Config;\n  /** Plugin objects, whose rules and presets the configuration can name. */\n  plugins?: Plugin[];\n  /**\n   * Documents whose text the caller supplies, such as an editor's unsaved\n   * text, by path relative to the root. They are selected, and the workspace\n   * reads this text instead of a file at that path. One whose path ignore rules\n   * leave out is not selected and is reported in `skipped`, as a named file is.\n   */\n  documents?: Record<string, string>;\n}\n/** The files of a workspace that `discoverWorkspace` found, and how to process them. */\nexport interface WorkspaceDiscovery {\n  /** The workspace root's real path. */\n  readonly root: string;\n  /** The documents to process, as forward-slash paths relative to the root, sorted. */\n  readonly selected: readonly string[];\n  /** What discovery could not read or use and left out, as in the CLI's JSON report. */\n  readonly skipped: readonly Skipped[];\n  /**\n   * The text of a selected document. A file is read when it is first needed\n   * and then kept; an error with the code `EACCES`, `EPERM`, or `EBUSY` means\n   * that the system did not let it be read, and one with the code\n   * `ERR_ENCODING_INVALID_ENCODED_DATA` that its bytes are not UTF-8 text.\n   */\n  read(path: string): string;\n  /**\n   * The options to lint or format a selected document with, as the CLI does:\n   * its path, the configuration and plugins, a workspace for its dialect with\n   * its vault's line-break setting, and the dialect to assume for a note.\n   */\n  options(path: string): ProcessOptions;\n}\n\n/**\n * The dialect to assume for a document when nothing names one, or undefined for\n * the library's own default. An Obsidian vault shows a single line break as a\n * line break and holds wikilinks, both of which any other dialect lets reflow\n * change, so a document that a vault holds is read as a note.\n */\nexport function assumedDialect(vault: Vault | string | undefined): Dialect | undefined {\n  return vault ? \"obsidian\" : undefined;\n}\n/**\n * Stops when `given` cannot serve as a workspace root, with a message that\n * names it. Without this check the first thing to fail could be a search\n * inside it, with a message about a path the user never named.\n */\nexport async function checkRoot(given: string): Promise<void> {\n  const root = path.resolve(given);\n  try {\n    if (!(await stat(root)).isDirectory())\n      throw new Error(`Workspace root is not a directory: ${root}`);\n    await access(root, constants.R_OK | constants.X_OK);\n  } catch (error) {\n    throw pathError(\"Workspace root\", root, error);\n  }\n}\n/**\n * Find the files of a workspace and select documents the way the CLI does:\n * honoring Git's ignore rules and the configuration's `ignore` and `resolve`\n * settings, skipping links, nested repositories, and what the system does not\n * let the tool read, and recognizing each document's Obsidian vault. Nothing\n * is written.\n */\nexport function discoverWorkspace(options: DiscoverOptions): Promise<WorkspaceDiscovery> {\n  return discoverFrom(options, path.resolve(options.root));\n}\n/**\n * The same, with relative inputs and exclusions resolved from `base`. Without\n * `ignoreDocuments`, ignore rules do not leave out the supplied documents, as\n * for text from stdin without a path of its own.\n */\nexport async function discoverFrom(\n  options: DiscoverOptions,\n  base: string,\n  ignoreDocuments = true,\n): Promise<WorkspaceDiscovery> {\n  await checkRoot(options.root);\n  // Which files to leave out does not depend on a document's dialect.\n  const resolved = resolveConfig({ config: options.config, plugins: options.plugins });\n  const documents = new Map<string, string>();\n  for (const [given, text] of Object.entries(options.documents ?? {})) {\n    const name = path.posix.normalize(given.split(path.sep).join(\"/\"));\n    if (name === \".\" || name === \"..\" || name.startsWith(\"../\") || path.isAbsolute(given))\n      throw new Error(`Document path is outside the workspace: ${given}`);\n    documents.set(name, text);\n  }\n  // Discovery always visits the whole workspace, whose files are link targets;\n  // the inputs only choose what is selected.\n  const none = options.inputs?.length === 0;\n  const set = await discover(\n    options.root,\n    none ? [] : (options.inputs ?? []),\n    resolved.ignore,\n    resolved.resolve,\n    base,\n    { documents: ignoreDocuments ? [...documents.keys()] : [], selectNone: none },\n  );\n  set.selected = none\n    ? []\n    : await excludeSelection(set.root, set.selected, options.exclude ?? [], base);\n  // A supplied document that ignore rules leave out is reported as a named\n  // file is, and not selected.\n  const ignored = new Set(\n    set.skipped.flatMap((item) =>\n      item.type === \"file\" && isIgnoredInput(item) ? [item.path] : [],\n    ),\n  );\n  // A supplied document can lie in a folder that discovery did not visit, so\n  // its vault is found by a search of its own.\n  const supplied = new Map<string, Vault | undefined>();\n  for (const [name, text] of documents) {\n    set.files[name] = text;\n    if (!ignored.has(name)) supplied.set(name, undefined);\n  }\n  for (const name of supplied.keys()) supplied.set(name, await vaultFor(set, name));\n  const selected = [...new Set([...set.selected, ...supplied.keys()])].sort();\n  const chosen = new Set(selected);\n  const known = (name: string) => {\n    if (!chosen.has(name)) throw new Error(`Not a selected document: ${name}`);\n  };\n  // One index per active dialect, built when a document of the dialect is first\n  // processed, and a view of it with each vault's line-break setting.\n  const indexes = new Map<Dialect, Workspace>();\n  const views = new Map<Dialect, Map<Vault, Workspace>>();\n  // Links into folders that discovery does not enter are checked on disk.\n  const lookup = unlistedLookup(set);\n  function index(dialect: Dialect): Workspace {\n    let workspace = indexes.get(dialect);\n    if (workspace) return workspace;\n    // The vault that the root is a folder of, if it is one: links may lead out of sight.\n    const enclosing = set.vaults.find((item) => item.rootInVault);\n    workspace = createWorkspace(set.files, {\n      dialect,\n      directories: set.directories,\n      // Links into a directory that could not be read are unchecked, not missing.\n      unreadable: set.skipped.flatMap((item) =>\n        item.type === \"directory\" && item.code !== \"IGNORED\" ? [item.path] : [],\n      ),\n      // The vault at or above the root holds the whole workspace and needs no entry.\n      vaults: set.vaults.flatMap((item) => (item.path ? [item.path] : [])),\n      ...(enclosing?.rootInVault ? { rootInVault: enclosing.rootInVault } : {}),\n      lookup,\n    });\n    indexes.set(dialect, workspace);\n    return workspace;\n  }\n  return {\n    root: set.root,\n    selected,\n    skipped: set.skipped,\n    read(name) {\n      known(name);\n      const value = set.files[name];\n      if (typeof value === \"string\") return value;\n      if (typeof value === \"function\") return value();\n      throw new Error(`Not a Markdown document: ${name}`);\n    },\n    options(name) {\n      known(name);\n      const vault = supplied.has(name) ? supplied.get(name) : vaultOf(set.vaults, name);\n      const assumed = assumedDialect(vault);\n      const { dialect } = resolveConfig({\n        config: options.config,\n        path: name,\n        plugins: options.plugins,\n        defaultDialect: assumed,\n      });\n      let workspace = index(dialect);\n      // Whether a note may be reflowed is a setting of its own vault.\n      if (vault?.strictLineBreaks !== undefined) {\n        let ofDialect = views.get(dialect);\n        if (!ofDialect) views.set(dialect, (ofDialect = new Map()));\n        const shared = workspace;\n        workspace = ofDialect.get(vault) ?? { ...shared, strictLineBreaks: vault.strictLineBreaks };\n        ofDialect.set(vault, workspace);\n      }\n      return {\n        path: name,\n        ...(options.config ? { config: options.config } : {}),\n        ...(options.plugins ? { plugins: options.plugins } : {}),\n        workspace,\n        ...(assumed ? { defaultDialect: assumed } : {}),\n      };\n    },\n  };\n}\n"]}

package/dist/workspace/encoding.d.ts

@@ -0,0 +1,24 @@
+/** Bytes that are not UTF-8 text, with what is wrong in words that do not name their source. */
+export declare class NotUtf8Error extends Error {
+    readonly reason: string;
+    readonly code = "ERR_ENCODING_INVALID_ENCODED_DATA";
+    constructor(reason: string, message: string);
+}
+/** Whether an error says that bytes are not UTF-8 text, as `decodeText` and a fatal `TextDecoder` do. */
+export declare function isNotUtf8(error: unknown): boolean;
+/**
+ * The offset of the first byte that does not start a valid UTF-8 sequence, or
+ * -1 when every one does. A sequence is valid as Unicode's table of
+ * well-formed byte sequences defines it: no overlong forms, no surrogates, and
+ * nothing above U+10FFFF.
+ */
+export declare function invalidUtf8At(bytes: Uint8Array): number;
+/**
+ * The text of `bytes`, which must be UTF-8, with or without a byte order mark.
+ * A mark stays at the start of the text, where formatting keeps it. Text with a
+ * NUL byte is refused too: Markdown has no use for one, and UTF-16 text without
+ * a byte order mark, whose ASCII characters each have one, could otherwise pass
+ * for UTF-8 and be damaged by an edit. Bytes that are not such text throw a
+ * `NotUtf8Error` whose message names `subject`; nothing is ever replaced.
+ */
+export declare function decodeText(bytes: Buffer, subject: string): string;

package/dist/workspace/encoding.js

@@ -0,0 +1,113 @@
+import { isUtf8 } from "node:buffer";
+/**
+ * The code of the error for bytes that are not UTF-8 text. Node.js's
+ * `TextDecoder`, created with `fatal: true`, throws an error with the same code
+ * for bytes that are not valid in its encoding.
+ */
+const notUtf8Code = "ERR_ENCODING_INVALID_ENCODED_DATA";
+/** Bytes that are not UTF-8 text, with what is wrong in words that do not name their source. */
+export class NotUtf8Error extends Error {
+    reason;
+    code = notUtf8Code;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/** Whether an error says that bytes are not UTF-8 text, as `decodeText` and a fatal `TextDecoder` do. */
+export function isNotUtf8(error) {
+    return (typeof error === "object" && error !== null && "code" in error && error.code === notUtf8Code);
+}
+/**
+ * The byte order marks of other encodings. UTF-32LE's starts with UTF-16LE's,
+ * so it is looked for first.
+ */
+const marks = [
+    ["UTF-32LE", [0xff, 0xfe, 0x00, 0x00]],
+    ["UTF-32BE", [0x00, 0x00, 0xfe, 0xff]],
+    ["UTF-16LE", [0xff, 0xfe]],
+    ["UTF-16BE", [0xfe, 0xff]],
+];
+/**
+ * The offset of the first byte that does not start a valid UTF-8 sequence, or
+ * -1 when every one does. A sequence is valid as Unicode's table of
+ * well-formed byte sequences defines it: no overlong forms, no surrogates, and
+ * nothing above U+10FFFF.
+ */
+export function invalidUtf8At(bytes) {
+    for (let at = 0; at < bytes.length;) {
+        const lead = bytes[at];
+        if (lead < 0x80) {
+            at++;
+            continue;
+        }
+        // The length of the sequence, and the range of its second byte.
+        let size;
+        let low = 0x80;
+        let high = 0xbf;
+        if (lead >= 0xc2 && lead <= 0xdf)
+            size = 2;
+        else if (lead >= 0xe0 && lead <= 0xef) {
+            size = 3;
+            if (lead === 0xe0)
+                low = 0xa0;
+            if (lead === 0xed)
+                high = 0x9f;
+        }
+        else if (lead >= 0xf0 && lead <= 0xf4) {
+            size = 4;
+            if (lead === 0xf0)
+                low = 0x90;
+            if (lead === 0xf4)
+                high = 0x8f;
+        }
+        else
+            return at;
+        for (let next = 1; next < size; next++) {
+            const byte = bytes[at + next];
+            if (byte === undefined ||
+                byte < (next === 1 ? low : 0x80) ||
+                byte > (next === 1 ? high : 0xbf))
+                return at;
+        }
+        at += size;
+    }
+    return -1;
+}
+/** The line that a byte offset lies on, counting LF, CR, and CRLF as line ends. */
+function lineAt(bytes, offset) {
+    let line = 1;
+    for (let at = 0; at < offset; at++)
+        if (bytes[at] === 0x0a || (bytes[at] === 0x0d && bytes[at + 1] !== 0x0a))
+            line++;
+    return line;
+}
+/** What keeps `bytes` from being read as UTF-8 text, or undefined when nothing does. */
+function problem(bytes) {
+    for (const [name, mark] of marks)
+        if (mark.every((byte, index) => bytes[index] === byte))
+            return `it starts with a ${name} byte order mark`;
+    const invalid = isUtf8(bytes) ? -1 : invalidUtf8At(bytes);
+    const nul = bytes.indexOf(0);
+    if (nul >= 0 && (invalid < 0 || nul < invalid))
+        return `line ${lineAt(bytes, nul)} contains a NUL byte, as UTF-16 text and binary files do`;
+    if (invalid < 0)
+        return undefined;
+    const byte = bytes[invalid].toString(16).toUpperCase().padStart(2, "0");
+    return `byte 0x${byte} on line ${lineAt(bytes, invalid)} is not valid UTF-8`;
+}
+/**
+ * The text of `bytes`, which must be UTF-8, with or without a byte order mark.
+ * A mark stays at the start of the text, where formatting keeps it. Text with a
+ * NUL byte is refused too: Markdown has no use for one, and UTF-16 text without
+ * a byte order mark, whose ASCII characters each have one, could otherwise pass
+ * for UTF-8 and be damaged by an edit. Bytes that are not such text throw a
+ * `NotUtf8Error` whose message names `subject`; nothing is ever replaced.
+ */
+export function decodeText(bytes, subject) {
+    const reason = problem(bytes);
+    if (reason)
+        throw new NotUtf8Error(reason, `Not UTF-8 text: ${subject} (${reason})`);
+    return bytes.toString("utf8");
+}
+//# sourceMappingURL=encoding.js.map

package/dist/workspace/encoding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../src/workspace/encoding.ts"],"names":[],"mappings":"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","sourcesContent":["import { isUtf8 } from \"node:buffer\";\n\n/**\n * The code of the error for bytes that are not UTF-8 text. Node.js's\n * `TextDecoder`, created with `fatal: true`, throws an error with the same code\n * for bytes that are not valid in its encoding.\n */\nconst notUtf8Code = \"ERR_ENCODING_INVALID_ENCODED_DATA\";\n\n/** Bytes that are not UTF-8 text, with what is wrong in words that do not name their source. */\nexport class NotUtf8Error extends Error {\n  readonly code = notUtf8Code;\n  constructor(\n    readonly reason: string,\n    message: string,\n  ) {\n    super(message);\n  }\n}\n/** Whether an error says that bytes are not UTF-8 text, as `decodeText` and a fatal `TextDecoder` do. */\nexport function isNotUtf8(error: unknown): boolean {\n  return (\n    typeof error === \"object\" && error !== null && \"code\" in error && error.code === notUtf8Code\n  );\n}\n/**\n * The byte order marks of other encodings. UTF-32LE's starts with UTF-16LE's,\n * so it is looked for first.\n */\nconst marks = [\n  [\"UTF-32LE\", [0xff, 0xfe, 0x00, 0x00]],\n  [\"UTF-32BE\", [0x00, 0x00, 0xfe, 0xff]],\n  [\"UTF-16LE\", [0xff, 0xfe]],\n  [\"UTF-16BE\", [0xfe, 0xff]],\n] as const;\n/**\n * The offset of the first byte that does not start a valid UTF-8 sequence, or\n * -1 when every one does. A sequence is valid as Unicode's table of\n * well-formed byte sequences defines it: no overlong forms, no surrogates, and\n * nothing above U+10FFFF.\n */\nexport function invalidUtf8At(bytes: Uint8Array): number {\n  for (let at = 0; at < bytes.length;) {\n    const lead = bytes[at]!;\n    if (lead < 0x80) {\n      at++;\n      continue;\n    }\n    // The length of the sequence, and the range of its second byte.\n    let size: number;\n    let low = 0x80;\n    let high = 0xbf;\n    if (lead >= 0xc2 && lead <= 0xdf) size = 2;\n    else if (lead >= 0xe0 && lead <= 0xef) {\n      size = 3;\n      if (lead === 0xe0) low = 0xa0;\n      if (lead === 0xed) high = 0x9f;\n    } else if (lead >= 0xf0 && lead <= 0xf4) {\n      size = 4;\n      if (lead === 0xf0) low = 0x90;\n      if (lead === 0xf4) high = 0x8f;\n    } else return at;\n    for (let next = 1; next < size; next++) {\n      const byte = bytes[at + next];\n      if (\n        byte === undefined ||\n        byte < (next === 1 ? low : 0x80) ||\n        byte > (next === 1 ? high : 0xbf)\n      )\n        return at;\n    }\n    at += size;\n  }\n  return -1;\n}\n/** The line that a byte offset lies on, counting LF, CR, and CRLF as line ends. */\nfunction lineAt(bytes: Uint8Array, offset: number): number {\n  let line = 1;\n  for (let at = 0; at < offset; at++)\n    if (bytes[at] === 0x0a || (bytes[at] === 0x0d && bytes[at + 1] !== 0x0a)) line++;\n  return line;\n}\n/** What keeps `bytes` from being read as UTF-8 text, or undefined when nothing does. */\nfunction problem(bytes: Buffer): string | undefined {\n  for (const [name, mark] of marks)\n    if (mark.every((byte, index) => bytes[index] === byte))\n      return `it starts with a ${name} byte order mark`;\n  const invalid = isUtf8(bytes) ? -1 : invalidUtf8At(bytes);\n  const nul = bytes.indexOf(0);\n  if (nul >= 0 && (invalid < 0 || nul < invalid))\n    return `line ${lineAt(bytes, nul)} contains a NUL byte, as UTF-16 text and binary files do`;\n  if (invalid < 0) return undefined;\n  const byte = bytes[invalid]!.toString(16).toUpperCase().padStart(2, \"0\");\n  return `byte 0x${byte} on line ${lineAt(bytes, invalid)} is not valid UTF-8`;\n}\n/**\n * The text of `bytes`, which must be UTF-8, with or without a byte order mark.\n * A mark stays at the start of the text, where formatting keeps it. Text with a\n * NUL byte is refused too: Markdown has no use for one, and UTF-16 text without\n * a byte order mark, whose ASCII characters each have one, could otherwise pass\n * for UTF-8 and be damaged by an edit. Bytes that are not such text throw a\n * `NotUtf8Error` whose message names `subject`; nothing is ever replaced.\n */\nexport function decodeText(bytes: Buffer, subject: string): string {\n  const reason = problem(bytes);\n  if (reason) throw new NotUtf8Error(reason, `Not UTF-8 text: ${subject} (${reason})`);\n  return bytes.toString(\"utf8\");\n}\n"]}

package/dist/workspace/files.d.ts

@@ -1,21 +1,47 @@
 import type { ResolveOptions } from "../core/types.js";
-import type { WorkspaceSource } from "./index.js";
+import type { LookupResult, WorkspaceSource } from "./index.js";
 import type { RefusalCode } from "./access.js";
 import type { Vault } from "./vault.js";
 /** A path that discovery could not use and left out of the run. */
 export interface Skipped {
-    /** The directory or settings file, relative to the workspace root. */
+    /** The directory or file, relative to the workspace root. */
     path: string;
+    /** Whether a directory or a file was left out. */
     type: "directory" | "file";
-    /** The system's error code, or `INVALID` for a settings file with unusable content. */
-    code: RefusalCode | "INVALID";
+    /**
+     * The system's error code, `INVALID` for a settings file with unusable
+     * content, or `IGNORED` for an input that was named but is ignored.
+     */
+    code: RefusalCode | "INVALID" | "IGNORED";
     /** What was skipped, why, and what follows from it. */
     message: string;
 }
+/** Names a path of the workspace, given relative to the root, as a message shows it. */
+type PathText = (file: string) => string;
+/**
+ * The message of a skipped entry with each path of the workspace that it names
+ * given by `show`, which receives the path relative to the root. The CLI's text
+ * names them from the current directory.
+ */
+export declare function skippedMessage(item: Skipped, show: PathText): string;
+/**
+ * Whether a skipped entry reports a named file or folder that discovery leaves
+ * out as ignored, a warning that the CLI's `--no-warn-ignored` leaves out. An
+ * ignored workspace root is not one: no path named it, and none of its files is
+ * processed.
+ */
+export declare function isIgnoredInput(item: Skipped): boolean;
 export interface FileSet {
     root: string;
     files: Record<string, WorkspaceSource>;
     directories: string[];
+    /**
+     * The entries below the root that discovery did not enter and that Git does
+     * not ignore: folders and files of the names that it always leaves out, and
+     * symbolic links and junctions. Their files are not in `files`, but a link
+     * can name one.
+     */
+    unlisted: string[];
     /** What discovery could not read or use, sorted by path. */
     skipped: Skipped[];
     selected: string[];
@@ -26,6 +52,14 @@ export interface FileSet {
      */
     vaults: Vault[];
 }
+/**
+ * The workspace's lookup of a path at or below one of the set's `unlisted`
+ * entries, on disk: a link that names such a path is checked there instead of
+ * being called missing. The workspace root still bounds what is read, so a
+ * path whose real location lies outside it, through a symbolic link or a
+ * junction, is reported as such and not read.
+ */
+export declare function unlistedLookup(set: FileSet): (name: string, folded: boolean) => LookupResult | undefined;
 /**
  * The vault that holds the document `name` of the workspace, which need not
  * exist on disk: text read from stdin can be named into a folder that discovery
@@ -33,5 +67,57 @@ export interface FileSet {
  * folder and is added to the set when it is new.
  */
 export declare function vaultFor(set: FileSet, name: string): Promise<Vault | undefined>;
-export declare function discover(rootPath: string, supplied: string[], excluded: string[], resolve?: ResolveOptions): Promise<FileSet>;
-export declare function writeAtomic(file: string, before: string, after: string): Promise<void>;
+/**
+ * The files of the workspace at `rootPath`, and the documents that `supplied`
+ * files, folders, and patterns select, or all of them when `supplied` is
+ * empty. Relative inputs are resolved from `base`.
+ *
+ * A folder or pattern selects the Markdown files in it or matching it, by
+ * name (`isMarkdownName`), that nothing ignores. A file named on its own is
+ * selected whatever its name: naming it is the request. When ignore rules
+ * leave out a named file or folder, `skipped` says so and why.
+ *
+ * `documents` are paths from the root of documents whose text a caller
+ * supplies, which need not exist. They are not selected here, but ignore rules
+ * leave them out as named files, as far as their folders exist. With
+ * `selectNone`, the caller selects nothing from disk, and an ignored root is
+ * not reported.
+ */
+export declare function discover(rootPath: string, supplied: string[], excluded: string[], resolve?: ResolveOptions, base?: string, { documents, selectNone }?: {
+    documents?: string[];
+    selectNone?: boolean;
+}): Promise<FileSet>;
+/**
+ * A file that `writeFormatted` would not write, or did not write completely,
+ * with the reason in words that do not name it.
+ */
+export declare class ReplacementRefused extends Error {
+    readonly reason: string;
+    constructor(reason: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Why `file` cannot be written, or undefined when nothing stands in the way
+ * that can be seen before writing: the file may not be written, or its folder
+ * does not let the trial file be created beside it. A read-only file is refused
+ * on every platform: the flag marks a file that is not to be edited.
+ */
+export declare function replacementProblem(file: string): Promise<string | undefined>;
+/**
+ * What went wrong when `writeFormatted` failed for a file, in words that do
+ * not name it, or undefined for an error that is a fault of the tool.
+ */
+export declare function replacementFailure(error: unknown): string | undefined;
+/**
+ * Write the formatted text `after` into `file`, whose text was read as
+ * `before`, if the file still holds exactly the bytes that were read. The file
+ * itself is written, not replaced by a new one, so that it keeps its
+ * permissions, attributes, owner, creation time, and hard links, which Node.js
+ * cannot all carry over to a new file. A trial write beside the file first shows that
+ * the new content fits on the disk. The file is then checked through the open
+ * file, just before writing. If writing fails part way, the bytes that were read
+ * are written back, and the reason says whether that worked. A file that already
+ * holds `after`, as the second name of a hard link written earlier in the batch
+ * does, is left as it is.
+ */
+export declare function writeFormatted(file: string, before: string, after: string): Promise<void>;
+export {};