@loomcli/core 0.5.0 → 0.6.0

package/dist/controls.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The text with every control character, line separator, and bidirectional control replaced by its
+ * four-digit lowercase `\uXXXX` escape, so the text stays on one line, no control character
+ * reaches a terminal, and no bidirectional control reorders the rest of the line. Raw text a
+ * diagnostic quotes, such as a file path, a typed token, or a reason a plugin threw, is escaped
+ * with this before it is written.
+ */
+export declare function escapeControlCharacters(text: string): string;

package/dist/controls.js

@@ -0,0 +1,23 @@
+/** The radix and digit count a `\uXXXX` escape always uses. */
+const hexRadix = 16;
+const hexDigitCount = 4;
+/** Each replaced character is exactly one UTF-16 code unit, so its code always sits at index 0. */
+const soleCodeUnit = 0;
+/**
+ * Every character a quoted diagnostic escapes: the control characters U+0000 through U+001F and
+ * U+007F through U+009F, the separators U+2028 and U+2029, the bidirectional embedding, override,
+ * and isolate controls U+202A through U+202E and U+2066 through U+2069, and the marks U+200E,
+ * U+200F, and U+061C. Other format characters, such as a zero-width joiner inside an emoji or a
+ * soft hyphen, are ordinary text and stay.
+ */
+const escaped = /[\p{Cc}\p{Zl}\p{Zp}\u{202a}-\u{202e}\u{2066}-\u{2069}\u{200e}\u{200f}\u{61c}]/gu;
+/**
+ * The text with every control character, line separator, and bidirectional control replaced by its
+ * four-digit lowercase `\uXXXX` escape, so the text stays on one line, no control character
+ * reaches a terminal, and no bidirectional control reorders the rest of the line. Raw text a
+ * diagnostic quotes, such as a file path, a typed token, or a reason a plugin threw, is escaped
+ * with this before it is written.
+ */
+export function escapeControlCharacters(text) {
+    return text.replaceAll(escaped, (character) => `\\u${character.charCodeAt(soleCodeUnit).toString(hexRadix).padStart(hexDigitCount, '0')}`);
+}

package/dist/defect.d.ts

@@ -0,0 +1,18 @@
+/**
+ * What a development build reads a defect's source through: the working directory, the roots a
+ * frame may lie under, and a reader. The roots are `cwd` and the path it resolves to through
+ * symbolic links, because a runtime names a module by its resolved path.
+ */
+interface SourceAccess {
+    readonly cwd: string;
+    readonly roots: readonly string[];
+    readonly readSource: ((path: string, cwd: string) => string | undefined) | undefined;
+}
+/**
+ * A defect's findings in a development build: the author's source around the failing frame, read
+ * only here, and the cause chain. A thrown value that is not an Error prints as a value, and a
+ * defect with no cause shows none.
+ */
+declare function defectEvidence(cause: unknown, access: SourceAccess): string[];
+export type { SourceAccess };
+export { defectEvidence };

package/dist/defect.js

@@ -0,0 +1,272 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { escapeControlCharacters } from './controls.js';
+import { valueCode } from './diagnostic-text.js';
+import { DeclarationError } from './errors.js';
+/** How many causes a chain prints before it stops, so a chain a getter grows cannot run forever. */
+const causeLimit = 8;
+/** How many lines a source excerpt shows on each side of the failing line. */
+const context = 2;
+/** A frame's location, `file:line:column`, where the file may hold spaces and parentheses. */
+const frameLocation = /^(?<file>.+):(?<line>\d+):(?<column>\d+)$/u;
+/** Every line terminator a JavaScript engine counts, in a message, a stack, or a source file. */
+const lineBreak = /\r\n|[\n\r\u2028\u2029]/u;
+/** A value read through a property, or `undefined` when reading it throws. */
+function readField(value, key) {
+    try {
+        return Reflect.get(value, key);
+    }
+    catch {
+        return undefined;
+    }
+}
+/** A field that must be a string, read defensively. */
+function readText(value, key) {
+    const field = readField(value, key);
+    return typeof field === 'string' ? field : undefined;
+}
+/** Whether a value is an Error, read defensively, because a proxy's prototype trap can throw. */
+function isError(value) {
+    try {
+        return value instanceof Error;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * What one cause says about itself on its heading line. A `DeclarationError` says its sentence,
+ * because its message holds its whole diagnostic.
+ */
+function causeReason(cause) {
+    try {
+        return cause instanceof DeclarationError ? cause.sentence : readText(cause, 'message');
+    }
+    catch {
+        return readText(cause, 'message');
+    }
+}
+/**
+ * The part of a stack after its header. A runtime opens a stack with the error's name and message,
+ * and a message can hold a line that reads as a frame, so the header is cut off whole: by its text
+ * when the stack opens with it, and otherwise by as many lines as the message holds.
+ */
+function stackBody(cause) {
+    const stack = readText(cause, 'stack') ?? '';
+    const name = readText(cause, 'name') ?? 'Error';
+    const message = readText(cause, 'message') ?? '';
+    const header = message === '' ? name : `${name}: ${message}`;
+    if (stack.startsWith(header)) {
+        return stack.slice(header.length).split(lineBreak);
+    }
+    return stack.split(lineBreak).slice(message.split(lineBreak).length);
+}
+/** The frame lines of one cause's stack: each line after the header that opens with `at`, trimmed. */
+function frameLines(cause) {
+    return stackBody(cause)
+        .map((line) => line.trim())
+        .filter((line) => line.startsWith('at '));
+}
+/** The file a frame names as a path, converting a `file:` URL, or `undefined` for one that fails. */
+function framePath(file) {
+    if (!file.startsWith('file:')) {
+        return file;
+    }
+    try {
+        return fileURLToPath(file);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * The location one frame line names: the text between the first ` (` and the closing parenthesis
+ * when the line has both, and otherwise everything after `at` and an optional `async`.
+ */
+function frameText(line) {
+    const rest = line.replace(/^at (?:async )?/u, '');
+    const open = rest.indexOf(' (');
+    return open !== -1 && rest.endsWith(')') ? rest.slice(open + 2, -1) : rest;
+}
+/** One frame line's location, or `undefined` for a line that names none. */
+function parseFrame(line) {
+    const groups = frameLocation.exec(frameText(line))?.groups;
+    const file = groups?.file === undefined ? undefined : framePath(groups.file);
+    if (file === undefined || groups?.line === undefined || groups.column === undefined) {
+        return undefined;
+    }
+    return { column: Number(groups.column), file, line: Number(groups.line) };
+}
+/** A frame's file relative to one root, or `undefined` when the file does not lie under it. */
+function within(file, root) {
+    const inside = relative(resolve(root), resolve(file));
+    return inside === '' || inside === '..' || inside.startsWith(`..${sep}`) || isAbsolute(inside)
+        ? undefined
+        : inside;
+}
+/**
+ * A frame's file relative to the first root it lies under, when it may be read: an absolute path
+ * whose normalized form lies under a root and outside any `node_modules` directory. A thrown
+ * value's stack can be forged, so this is checked before any read, and the reader checks it again
+ * past symbolic links. It answers `undefined` for a file that does not qualify.
+ */
+function qualified(file, roots) {
+    if (!isAbsolute(file) || resolve(file).split(sep).includes('node_modules')) {
+        return undefined;
+    }
+    for (const root of roots) {
+        const inside = within(file, root);
+        if (inside !== undefined) {
+            return inside;
+        }
+    }
+    return undefined;
+}
+/** A frame's location as the diagnostic prints it: relative to the working directory when under it. */
+function locationText(frame, roots) {
+    const file = qualified(frame.file, roots) ?? frame.file;
+    return escapeControlCharacters(`${file}:${String(frame.line)}:${String(frame.column)}`);
+}
+/** The source one reader answers for a file, or `undefined` when it answers none or throws. */
+function readFile(access, file) {
+    try {
+        const text = access.readSource?.(resolve(file), access.cwd);
+        return typeof text === 'string' ? text : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * One numbered source line, marked when it is the failing line, with a caret under the frame's
+ * column below it. A tab reads as one space, so the caret stays under the column the frame names.
+ */
+function numberedLine(source, number, frame) {
+    const text = escapeControlCharacters(source.replaceAll('\t', ' '));
+    const failing = number === frame.line;
+    const line = `${failing ? '>' : ' '} ${String(number).padStart(frame.digits)} | ${text}`.trimEnd();
+    if (!failing) {
+        return [line];
+    }
+    return [line, `  ${' '.repeat(frame.digits)} | ${' '.repeat(Math.max(0, frame.column - 1))}^`];
+}
+/** The lines around one frame, numbered, with the failing line marked, or none past the file's end. */
+function excerpt(text, frame) {
+    // A JavaScript engine counts every line terminator, so a frame's line number counts them all.
+    const lines = text.split(lineBreak);
+    if (frame.line < 1 || frame.line > lines.length) {
+        return undefined;
+    }
+    const first = Math.max(1, frame.line - context);
+    const shown = lines.slice(first - 1, Math.min(lines.length, frame.line + context));
+    const digits = String(first + shown.length - 1).length;
+    return shown
+        .flatMap((source, offset) => numberedLine(source, first + offset, { ...frame, digits }))
+        .join('\n');
+}
+/**
+ * The errors an `AggregateError` holds, in order, read defensively, or none for any other Error. A
+ * broken translator's defect holds the translator's throw and then the original throw this way.
+ */
+function heldErrors(cause) {
+    try {
+        if (!(cause instanceof AggregateError)) {
+            return [];
+        }
+    }
+    catch {
+        return [];
+    }
+    const errors = readField(cause, 'errors');
+    return Array.isArray(errors) ? errors : [];
+}
+/** Every frame one cause's stack names, in order, skipping a line that names no location. */
+function framesOf(cause) {
+    return frameLines(cause).flatMap((line) => parseFrame(line) ?? []);
+}
+/**
+ * The author's source for a defect: the first frame that lies under the working directory and
+ * outside `node_modules`, read from the outermost cause's stack, or, for an `AggregateError`, from
+ * the stacks of the errors it holds in order and then its own, because what broke is what it
+ * holds. A read that answers nothing, and stacks with no qualifying frame, leave the outermost
+ * cause's first frame's location alone.
+ */
+function sourceSection(cause, access) {
+    const stacks = [...heldErrors(cause).filter(isError), cause];
+    const frame = stacks
+        .flatMap((stack) => framesOf(stack))
+        .find((candidate) => qualified(candidate.file, access.roots) !== undefined);
+    if (frame === undefined) {
+        const [located] = framesOf(cause);
+        return located === undefined ? undefined : locationText(located, access.roots);
+    }
+    const text = readFile(access, frame.file);
+    const lines = text === undefined ? undefined : excerpt(text, frame);
+    const location = locationText(frame, access.roots);
+    return lines === undefined ? location : `${location}\n\n${lines}`;
+}
+/** One cause as its name, its escaped message, or a declaration fault's sentence, and its frames. */
+function causeLines(cause) {
+    const name = readText(cause, 'name') ?? 'Error';
+    const reason = causeReason(cause);
+    const heading = reason === undefined || reason === '' ? name : `${name}: ${reason}`;
+    return [
+        escapeControlCharacters(heading),
+        ...frameLines(cause).map((line) => `    ${escapeControlCharacters(line)}`),
+    ];
+}
+/**
+ * One link of a cause chain under `prefix`, then each error it holds as an `AggregateError`, each
+ * with its own chain under `Holds`. It answers the link's own cause, or `undefined` for a link that
+ * is not an Error, which prints as a value.
+ */
+function appendLink(cause, prefix, walk) {
+    walk.seen.add(cause);
+    if (!isError(cause)) {
+        walk.lines.push(`${prefix}${valueCode(cause)}`);
+        return undefined;
+    }
+    const [heading = '', ...frames] = causeLines(cause);
+    walk.lines.push(`${prefix}${heading}`, ...frames);
+    for (const held of heldErrors(cause)) {
+        appendChain(held, 'Holds ', walk);
+    }
+    return readField(cause, 'cause');
+}
+/**
+ * One chain from `first`, the first link under `opening` and each later one under `Caused by`,
+ * following `cause` links until one is absent, repeats, or passes the limit.
+ */
+function appendChain(first, opening, walk) {
+    let cause = first;
+    let prefix = opening;
+    while (cause !== undefined && !walk.seen.has(cause) && walk.seen.size < causeLimit) {
+        cause = appendLink(cause, prefix, walk);
+        prefix = 'Caused by ';
+    }
+}
+/**
+ * The cause chain: each cause's name and escaped message and its stack, and each error an
+ * `AggregateError` holds, until the chain ends, repeats, or passes the limit.
+ */
+function causeChain(outermost) {
+    const walk = { lines: [], seen: new Set() };
+    appendChain(outermost, '', walk);
+    return walk.lines.join('\n');
+}
+/**
+ * A defect's findings in a development build: the author's source around the failing frame, read
+ * only here, and the cause chain. A thrown value that is not an Error prints as a value, and a
+ * defect with no cause shows none.
+ */
+function defectEvidence(cause, access) {
+    if (cause === undefined) {
+        return [];
+    }
+    if (!isError(cause)) {
+        return [`Thrown value: ${valueCode(cause)}`];
+    }
+    const source = sourceSection(cause, access);
+    return [...(source === undefined ? [] : [source]), causeChain(cause)];
+}
+export { defectEvidence };

package/dist/developer.d.ts

@@ -0,0 +1,24 @@
+import { DeclarationError } from './errors.js';
+import type { InternalError } from './errors.js';
+import type { ContextualStyle } from './style.js';
+import type { Host } from './types.js';
+/**
+ * Where a development build's diagnostics print: the application name a finding's path opens with,
+ * the stderr width, and the working directory and reader a defect's source comes through.
+ */
+interface DeveloperScene {
+    readonly application: string;
+    readonly host: Pick<Host, 'cwd' | 'readSource' | 'terminal'>;
+}
+/**
+ * One fault's Developer Diagnostic as marked text for stderr, the banner in the error style, and
+ * the hints printed under it after one blank line. It is not a view, so no override replaces it.
+ */
+declare function developerText(fault: DeclarationError | InternalError, scene: DeveloperScene & {
+    readonly hints: readonly string[];
+    readonly style: ContextualStyle;
+}): string;
+/** One fault's Developer Diagnostic as plain text, for the plain fallback path. */
+declare function developerPlainText(fault: DeclarationError | InternalError, scene: DeveloperScene): string;
+export type { DeveloperScene };
+export { developerPlainText, developerText };

package/dist/developer.js

@@ -0,0 +1,52 @@
+import { defectEvidence } from './defect.js';
+import { diagnosticSections, messageWidth } from './diagnostic-text.js';
+import { DeclarationError } from './errors.js';
+import { sourceRoots } from './host.js';
+/** What a defect's source is read through: the host's working directory, its roots, and reader. */
+function sourceAccess({ cwd, readSource }) {
+    return { cwd, readSource, roots: sourceRoots(cwd) };
+}
+/** The parts one fault renders, with a defect's source and causes read here, in development alone. */
+function anatomyOf(fault, host) {
+    if (fault instanceof DeclarationError) {
+        return {
+            correction: fault.correction,
+            evidence: [],
+            fallback: 'INVALID DECLARATION',
+            findings: fault.findings,
+            rule: fault.rule,
+            sentence: fault.sentence,
+        };
+    }
+    return {
+        correction: fault.correction,
+        evidence: defectEvidence(fault.cause, sourceAccess(host)),
+        fallback: 'DEFECT',
+        findings: [],
+        rule: fault.rule,
+        sentence: fault.sentence,
+    };
+}
+/** The banner and body of one fault's diagnostic, laid out for this run's stderr. */
+function sections(fault, scene) {
+    return diagnosticSections(anatomyOf(fault, scene.host), {
+        application: scene.application,
+        width: scene.host.terminal.stderr.columns ?? messageWidth,
+    });
+}
+/**
+ * One fault's Developer Diagnostic as marked text for stderr, the banner in the error style, and
+ * the hints printed under it after one blank line. It is not a view, so no override replaces it.
+ */
+function developerText(fault, scene) {
+    const { banner, body } = sections(fault, scene);
+    const { hints, style } = scene;
+    const hinted = hints.length === 0 ? '' : `\n${hints.map((hint) => `${hint}\n`).join('')}`;
+    return `${style.error(style.escape(banner))}\n\n${style.escape(body)}\n${hinted}`;
+}
+/** One fault's Developer Diagnostic as plain text, for the plain fallback path. */
+function developerPlainText(fault, scene) {
+    const { banner, body } = sections(fault, scene);
+    return `${banner}\n\n${body}\n`;
+}
+export { developerPlainText, developerText };

package/dist/diagnostic-text.d.ts

@@ -0,0 +1,81 @@
+/**
+ * One reason a declaration can be wrong, or one kind of defect: the parts that hold at every site
+ * that raises it. `diagnosticRule()` builds and freezes it.
+ */
+interface DiagnosticRule {
+    readonly identity: string;
+    readonly headline: string;
+    readonly explanation: string;
+    readonly docs: string | undefined;
+}
+/**
+ * One declaration a fault points at, rebuilt from the facts core holds: the Command it sits on, the
+ * authoring call, and the arguments that call received. `mark` is a dotted path into `arguments`
+ * that the diagnostic underlines, and `note` prints beside the marks.
+ */
+interface Finding {
+    readonly path?: readonly string[];
+    readonly call: string;
+    readonly arguments: readonly unknown[];
+    readonly mark?: string;
+    readonly note?: string;
+}
+/** The parts of one fault that differ at each site that raises its rule. */
+interface DiagnosticParts {
+    readonly sentence: string;
+    readonly findings?: readonly Finding[];
+    readonly correction?: string | readonly string[];
+}
+/** Everything one Developer Diagnostic prints, whichever class carries it. */
+interface Anatomy {
+    readonly rule: DiagnosticRule | undefined;
+    /** The banner a fault with no rule prints. */
+    readonly fallback: 'INVALID DECLARATION' | 'DEFECT';
+    readonly sentence: string;
+    readonly findings: readonly Finding[];
+    /** A defect's own findings, already rendered: the author's source and the cause chain. */
+    readonly evidence: readonly string[];
+    readonly correction: string | readonly string[] | undefined;
+}
+/**
+ * Where one diagnostic is printed: the column count its banner fills and its prose wraps to, and
+ * the application name a finding's path opens with when `run()` reports the fault.
+ */
+interface Layout {
+    readonly width: number;
+    readonly application?: string | undefined;
+}
+/** The width a diagnostic takes in a thrown error's message, or when the stderr width is unknown. */
+declare const messageWidth = 80;
+/** The stand-in for a value a finding does not spell out: a function, a validator, or a cycle. */
+declare const elided = "\u2026";
+/** A string as a single-quoted JavaScript literal, with every control escaped. */
+declare function quoteString(text: string): string;
+/** A finding argument that prints as the code given, which the caller has already escaped. */
+declare function spelled(code: string): object;
+/** One value as the JavaScript a finding prints for it. */
+declare function valueCode(value: unknown): string;
+/** Prose wrapped to the width at spaces. A word wider than the width keeps a line of its own. */
+declare function wrap(text: string, width: number): string;
+/**
+ * One Developer Diagnostic as plain text with no trailing newline: the banner, the sentence, the
+ * findings, the explanation, the correction, and the docs link, separated by one blank line, each
+ * left out when the fault does not carry it. The banner is returned apart, so a caller that styles
+ * it can.
+ */
+declare function diagnosticSections(anatomy: Anatomy, layout: Layout): {
+    banner: string;
+    body: string;
+};
+/** The whole diagnostic as the plain text a thrown fault's message holds. */
+declare function diagnosticText(anatomy: Anatomy, layout?: Layout): string;
+/** One frozen descriptor from parts already checked, which every site raising it shares. */
+declare function registerRule(identity: string, definition: {
+    readonly headline: string;
+    readonly explanation: string;
+    readonly docs?: string;
+}): DiagnosticRule;
+/** Whether a value is a descriptor `diagnosticRule()` built. */
+declare function isDiagnosticRule(value: unknown): value is DiagnosticRule;
+export type { Anatomy, DiagnosticParts, DiagnosticRule, Finding, Layout };
+export { diagnosticSections, diagnosticText, elided, isDiagnosticRule, messageWidth, quoteString, registerRule, spelled, valueCode, wrap, };