@timiagama/ecr 0.0.1 → 0.1.0

package/dist/cli/project-ignore.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Project Ignore File
+ *
+ * `.ecrignore` holds a project's ignore patterns, so they need not be repeated
+ * with `--ignore` on every command. Like `.gitignore` it lives at the project
+ * root, which the CLI takes to be the working directory, as Prettier and
+ * ESLint do; it does not search upwards.
+ *
+ * Patterns use the same glob rules as `--ignore`, one per line, with blank
+ * lines and `#` comments allowed. They are relative to the working directory,
+ * whereas `--ignore` patterns are relative to the directory being linted.
+ */
+/** The file's name, at the project root. */
+export declare const PROJECT_IGNORE_FILENAME: string;
+/** What reading the project ignore file found. */
+export type ProjectIgnoreRead = {
+    readonly kind: 'patterns';
+    readonly patterns: readonly string[];
+} | {
+    readonly kind: 'missing';
+} | {
+    readonly kind: 'unreadable';
+    readonly reason: string;
+};
+/** The `.ecrignore` entry an installation needs, or why none can be made. */
+export type InstallExclusion = {
+    readonly kind: 'pattern';
+    readonly pattern: string;
+} | {
+    readonly kind: 'outside';
+} | {
+    readonly kind: 'invalid';
+    readonly reason: string;
+};
+/**
+ * Reads, parses and updates a project's `.ecrignore`.
+ */
+export declare class ProjectIgnoreFile {
+    /** Path of the `.ecrignore` file. */
+    private readonly path;
+    /**
+     * Creates a handle on the ignore file of a project.
+     *
+     * @param workingDirectory - The project root: the directory the command runs from
+     */
+    constructor(workingDirectory: string);
+    /**
+     * Reads the ignore file's patterns. A missing file is normal; one that
+     * exists but cannot be read is reported, not treated as empty.
+     *
+     * @returns The patterns, or that there is no file, or why it could not be read
+     */
+    read(): ProjectIgnoreRead;
+    /**
+     * Adds a pattern unless the file already holds it, keeping everything else
+     * in the file exactly as it was. Creates the file if it does not exist.
+     *
+     * The new contents are written to a temporary file beside it, which then
+     * replaces it, so a write that fails part-way leaves the existing patterns
+     * untouched rather than truncated.
+     *
+     * @param pattern - The pattern to add
+     * @returns Whether the pattern was added or was already there
+     * @throws When the file cannot be read or replaced; it is then unchanged
+     */
+    addPattern(pattern: string): 'added' | 'present';
+    /**
+     * Removes a temporary file this class created, ignoring any failure to do
+     * so: the error being reported is the write, and a leftover temporary file
+     * does not change what the user must do about it.
+     *
+     * @param path - Path of the temporary file
+     */
+    private static removeQuietly;
+    /**
+     * Writes the replacement contents to a temporary file beside the ignore
+     * file, which this call creates itself.
+     *
+     * The name is unpredictable and the file is created exclusively, so nothing
+     * already at that path is opened: a link planted there, pointing anywhere on
+     * the disk, makes creation fail rather than be written through. That also
+     * means only a file this call created is ever removed.
+     *
+     * @param contents - The complete new contents of the ignore file
+     * @returns Path of the temporary file, which now holds those contents
+     * @throws When no temporary file could be created
+     */
+    private writeTemporaryFile;
+    /**
+     * Splits an ignore file into its patterns.
+     *
+     * @param text - The file's contents
+     * @returns Each pattern, trimmed, without blank lines or `#` comments
+     */
+    static parse(text: string): readonly string[];
+    /**
+     * Works out the exact `.ecrignore` pattern that excludes an installation
+     * directory, and nothing else.
+     *
+     * @param workingDirectory - The project root
+     * @param destination - The directory being installed into
+     * @returns The pattern; or that the destination lies outside the project and needs none; or why no safe pattern exists
+     */
+    static readInstallExclusion(workingDirectory: string, destination: string): InstallExclusion;
+    /**
+     * Describes a file-system error briefly.
+     *
+     * @param error - What was thrown
+     * @returns The error's code, such as `EACCES`, or its message
+     */
+    static showReason(error: unknown): string;
+}
+//# sourceMappingURL=project-ignore.d.ts.map

package/dist/cli/project-ignore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-ignore.d.ts","sourceRoot":"","sources":["../../src/cli/project-ignore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAMH,4CAA4C;AAC5C,eAAO,MAAM,uBAAuB,EAAE,MAAqB,CAAC;AAE5D,kDAAkD;AAClD,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GACnE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7D,6EAA6E;AAC7E,MAAM,MAAM,gBAAgB,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE,GAC5B;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAkB1D;;GAEG;AACH,qBAAa,iBAAiB;IAC5B,qCAAqC;IACrC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;IAE9B;;;;OAIG;gBACgB,gBAAgB,EAAE,MAAM;IAI3C;;;;;OAKG;IACI,IAAI,IAAI,iBAAiB;IAYhC;;;;;;;;;;;OAWG;IACI,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS;IAqBvD;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAQ5B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,kBAAkB;IA2B1B;;;;;OAKG;WACW,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE;IAOpD;;;;;;;OAOG;WACW,oBAAoB,CAAC,gBAAgB,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,gBAAgB;IAgCnG;;;;;OAKG;WACW,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM;CAQjD"}

package/dist/cli/project-ignore.js

@@ -0,0 +1,199 @@
+/**
+ * Project Ignore File
+ *
+ * `.ecrignore` holds a project's ignore patterns, so they need not be repeated
+ * with `--ignore` on every command. Like `.gitignore` it lives at the project
+ * root, which the CLI takes to be the working directory, as Prettier and
+ * ESLint do; it does not search upwards.
+ *
+ * Patterns use the same glob rules as `--ignore`, one per line, with blank
+ * lines and `#` comments allowed. They are relative to the working directory,
+ * whereas `--ignore` patterns are relative to the directory being linted.
+ */
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { isAbsolute, join, relative } from 'node:path';
+/** The file's name, at the project root. */
+export const PROJECT_IGNORE_FILENAME = '.ecrignore';
+/**
+ * Characters that would change a destination's meaning if written into
+ * `.ecrignore` as a literal path: glob wildcards, and line breaks.
+ */
+const UNSAFE_PATH_CHARACTERS = /[*?\r\n]/;
+/** A relative path that leaves the directory it is relative to. */
+const PARENT_PREFIX = /^\.\.(?:[\\/]|$)/;
+/**
+ * How many names to try when creating the temporary file. A name collision
+ * needs 16 random hexadecimal digits to repeat, so one retry would do; a few
+ * cost nothing and keep a wedged directory from failing on chance alone.
+ */
+const TEMPORARY_NAME_ATTEMPTS = 5;
+/**
+ * Reads, parses and updates a project's `.ecrignore`.
+ */
+export class ProjectIgnoreFile {
+    /** Path of the `.ecrignore` file. */
+    path;
+    /**
+     * Creates a handle on the ignore file of a project.
+     *
+     * @param workingDirectory - The project root: the directory the command runs from
+     */
+    constructor(workingDirectory) {
+        this.path = join(workingDirectory, PROJECT_IGNORE_FILENAME);
+    }
+    /**
+     * Reads the ignore file's patterns. A missing file is normal; one that
+     * exists but cannot be read is reported, not treated as empty.
+     *
+     * @returns The patterns, or that there is no file, or why it could not be read
+     */
+    read() {
+        if (!existsSync(this.path)) {
+            return { kind: 'missing' };
+        }
+        try {
+            return { kind: 'patterns', patterns: ProjectIgnoreFile.parse(readFileSync(this.path, 'utf8')) };
+        }
+        catch (error) {
+            return { kind: 'unreadable', reason: ProjectIgnoreFile.showReason(error) };
+        }
+    }
+    /**
+     * Adds a pattern unless the file already holds it, keeping everything else
+     * in the file exactly as it was. Creates the file if it does not exist.
+     *
+     * The new contents are written to a temporary file beside it, which then
+     * replaces it, so a write that fails part-way leaves the existing patterns
+     * untouched rather than truncated.
+     *
+     * @param pattern - The pattern to add
+     * @returns Whether the pattern was added or was already there
+     * @throws When the file cannot be read or replaced; it is then unchanged
+     */
+    addPattern(pattern) {
+        const existing = existsSync(this.path) ? readFileSync(this.path, 'utf8') : '';
+        if (ProjectIgnoreFile.parse(existing).includes(pattern)) {
+            return 'present';
+        }
+        const separator = existing === '' || existing.endsWith('\n') ? '' : '\n';
+        const temporaryPath = this.writeTemporaryFile(`${existing}${separator}${pattern}\n`);
+        try {
+            renameSync(temporaryPath, this.path);
+        }
+        catch (error) {
+            ProjectIgnoreFile.removeQuietly(temporaryPath);
+            throw error;
+        }
+        return 'added';
+    }
+    /**
+     * Removes a temporary file this class created, ignoring any failure to do
+     * so: the error being reported is the write, and a leftover temporary file
+     * does not change what the user must do about it.
+     *
+     * @param path - Path of the temporary file
+     */
+    static removeQuietly(path) {
+        try {
+            rmSync(path, { force: true });
+        }
+        catch {
+            // Nothing useful can be done, and nothing more needs saying.
+        }
+    }
+    /**
+     * Writes the replacement contents to a temporary file beside the ignore
+     * file, which this call creates itself.
+     *
+     * The name is unpredictable and the file is created exclusively, so nothing
+     * already at that path is opened: a link planted there, pointing anywhere on
+     * the disk, makes creation fail rather than be written through. That also
+     * means only a file this call created is ever removed.
+     *
+     * @param contents - The complete new contents of the ignore file
+     * @returns Path of the temporary file, which now holds those contents
+     * @throws When no temporary file could be created
+     */
+    writeTemporaryFile(contents) {
+        let lastError;
+        for (let attempt = 0; attempt < TEMPORARY_NAME_ATTEMPTS; attempt += 1) {
+            const candidate = `${this.path}.${randomBytes(8).toString('hex')}.tmp`;
+            try {
+                writeFileSync(candidate, contents, { encoding: 'utf8', flag: 'wx' });
+                return candidate;
+            }
+            catch (error) {
+                if (error.code === 'EEXIST') {
+                    // Something is already at that name. It is not this call's to
+                    // read, write or remove: try another name.
+                    lastError = error;
+                    continue;
+                }
+                // Anything else means the name was free, so whatever is there now was
+                // created by the call that just failed, perhaps written only in part.
+                ProjectIgnoreFile.removeQuietly(candidate);
+                throw error;
+            }
+        }
+        throw lastError;
+    }
+    /**
+     * Splits an ignore file into its patterns.
+     *
+     * @param text - The file's contents
+     * @returns Each pattern, trimmed, without blank lines or `#` comments
+     */
+    static parse(text) {
+        return text
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .filter((line) => line !== '' && !line.startsWith('#'));
+    }
+    /**
+     * Works out the exact `.ecrignore` pattern that excludes an installation
+     * directory, and nothing else.
+     *
+     * @param workingDirectory - The project root
+     * @param destination - The directory being installed into
+     * @returns The pattern; or that the destination lies outside the project and needs none; or why no safe pattern exists
+     */
+    static readInstallExclusion(workingDirectory, destination) {
+        const relativePath = relative(workingDirectory, destination);
+        if (relativePath === '') {
+            return {
+                kind: 'invalid',
+                reason: 'it is the working directory itself, and excluding it would exclude the whole project',
+            };
+        }
+        // Another drive on Windows gives an absolute path; a parent gives `..`.
+        if (isAbsolute(relativePath) || PARENT_PREFIX.test(relativePath)) {
+            return { kind: 'outside' };
+        }
+        const path = relativePath.replaceAll('\\', '/');
+        if (UNSAFE_PATH_CHARACTERS.test(path)) {
+            return { kind: 'invalid', reason: 'its name contains `*`, `?` or a line break, which .ecrignore would read as a pattern' };
+        }
+        if (path.startsWith('#')) {
+            return { kind: 'invalid', reason: 'its name starts with `#`, which .ecrignore would read as a comment' };
+        }
+        if (path !== path.trim()) {
+            return { kind: 'invalid', reason: 'its name starts or ends with a space, which .ecrignore would drop' };
+        }
+        return { kind: 'pattern', pattern: `${path}/**` };
+    }
+    /**
+     * Describes a file-system error briefly.
+     *
+     * @param error - What was thrown
+     * @returns The error's code, such as `EACCES`, or its message
+     */
+    static showReason(error) {
+        if (error instanceof Error) {
+            const code = error.code;
+            return typeof code === 'string' ? code : error.message;
+        }
+        return String(error);
+    }
+}
+//# sourceMappingURL=project-ignore.js.map

package/dist/cli/project-ignore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-ignore.js","sourceRoot":"","sources":["../../src/cli/project-ignore.ts"],"names":[],"mappings":"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"}

package/dist/cli/safe-text.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Terminal-Safe Text
+ *
+ * The CLI prints text it did not write: titles and headings quoted back from
+ * documents, and the paths of files it found. A terminal reads some characters
+ * as commands rather than as text — an escape sequence can clear the screen,
+ * move the cursor, recolour what is already there or overwrite a line — so a
+ * document could otherwise decide what the report of it appears to say.
+ *
+ * Anything printed as text is therefore written with those characters shown
+ * rather than obeyed. The JSON form needs no such treatment, because a
+ * consumer of it is not a terminal, and escaping there would change the data.
+ */
+/**
+ * Shows the characters a terminal would act on, rather than letting it act on
+ * them, writing each as the `\uXXXX` escape that names it.
+ *
+ * Tab and newline are left alone: the report is made of lines, and neither
+ * can misrepresent what it says.
+ *
+ * @param text - Text about to be printed to a terminal
+ * @returns The same text with every acted-on character shown
+ */
+export declare function showControlCharacters(text: string): string;
+//# sourceMappingURL=safe-text.d.ts.map

package/dist/cli/safe-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-text.d.ts","sourceRoot":"","sources":["../../src/cli/safe-text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM1D"}

package/dist/cli/safe-text.js

@@ -0,0 +1,34 @@
+/**
+ * Terminal-Safe Text
+ *
+ * The CLI prints text it did not write: titles and headings quoted back from
+ * documents, and the paths of files it found. A terminal reads some characters
+ * as commands rather than as text — an escape sequence can clear the screen,
+ * move the cursor, recolour what is already there or overwrite a line — so a
+ * document could otherwise decide what the report of it appears to say.
+ *
+ * Anything printed as text is therefore written with those characters shown
+ * rather than obeyed. The JSON form needs no such treatment, because a
+ * consumer of it is not a terminal, and escaping there would change the data.
+ */
+/**
+ * Characters a terminal acts on rather than displays: the C0 controls apart
+ * from tab and newline, delete, the C1 controls, and the bidirectional
+ * formatting characters, which reorder the text around them.
+ */
+// eslint-disable-next-line no-control-regex -- Matching control characters is the point.
+const ACTED_ON_BY_TERMINALS = /[\u0000-\u0008\u000B-\u001F\u007F-\u009F‪-‮⁦-⁩]/g;
+/**
+ * Shows the characters a terminal would act on, rather than letting it act on
+ * them, writing each as the `\uXXXX` escape that names it.
+ *
+ * Tab and newline are left alone: the report is made of lines, and neither
+ * can misrepresent what it says.
+ *
+ * @param text - Text about to be printed to a terminal
+ * @returns The same text with every acted-on character shown
+ */
+export function showControlCharacters(text) {
+    return text.replace(ACTED_ON_BY_TERMINALS, (character) => `\\u${character.codePointAt(0)?.toString(16).padStart(4, '0') ?? ''}`);
+}
+//# sourceMappingURL=safe-text.js.map

package/dist/cli/safe-text.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"safe-text.js","sourceRoot":"","sources":["../../src/cli/safe-text.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,yFAAyF;AACzF,MAAM,qBAAqB,GAAW,kDAAkD,CAAC;AAEzF;;;;;;;;;GASG;AACH,MAAM,UAAU,qBAAqB,CAAC,IAAY;IAChD,OAAO,IAAI,CAAC,OAAO,CACjB,qBAAqB,EACrB,CAAC,SAAiB,EAAU,EAAE,CAC5B,MAAM,SAAS,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CACxE,CAAC;AACJ,CAAC"}

package/dist/cli/supervisor.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Bounded Execution
+ *
+ * Parsing Markdown is where a corpus stops being data and starts being work
+ * the command cannot predict. The parser is recursive and, on some inputs,
+ * quadratic: four thousand nested bold spans inside a link label -- 16 KB --
+ * exhaust the call stack, and four thousand nested images -- 35 KB -- parse
+ * for the best part of a minute. Neither is a fault in a document anyone
+ * wrote on purpose, and neither can be found by inspecting a document before
+ * parsing it, since the cost is the parse.
+ *
+ * So `lint` and `stats` do their work in a child process this one starts and
+ * can stop. The child is this same executable, run once for the whole corpus,
+ * with a time limit and a heap limit; whatever it prints is relayed. If it
+ * has to be stopped, nothing it printed is relayed, because a report of a
+ * corpus that was never finished is worse than no report: half a JSON
+ * document still parses as JSON.
+ *
+ * This bounds the command, not the library. A host calling `lintDocument`
+ * directly runs the parser in its own process and must bound it itself.
+ */
+/**
+ * The environment variable marking the child, so that it does the work
+ * rather than starting a child of its own.
+ */
+export declare const SUPERVISED_VARIABLE: string;
+/** The limits a supervised run is given. */
+export interface SupervisionLimits {
+    /** Milliseconds the child may run for; `0` for no limit. */
+    readonly timeoutMs: number;
+    /**
+     * Mebibytes the child's V8 old-generation heap may grow to; `0` leaves
+     * Node's own default. This bounds the heap where a parse accumulates, not
+     * the process's total memory: stacks, buffers and the young generation sit
+     * outside it, so it is a brake rather than a ceiling.
+     */
+    readonly memoryMib: number;
+    /** Bytes of output the child may produce before it is stopped. */
+    readonly maxOutputBytes: number;
+}
+/** A child that finished by itself: its output and exit code stand. */
+export interface CompletedRun {
+    /** Distinguishes this from a run that was stopped. */
+    readonly kind: 'completed';
+    /** Everything the child wrote to standard output. */
+    readonly stdout: string;
+    /** Everything the child wrote to standard error. */
+    readonly stderr: string;
+    /** The code the child exited with. */
+    readonly exitCode: number;
+}
+/** A child that was stopped, or never ran; nothing it printed is usable. */
+export interface StoppedRun {
+    /** Distinguishes this from a run that completed. */
+    readonly kind: 'stopped';
+    /** Why it did not finish, as a phrase completing "the run did not finish because...". */
+    readonly reason: string;
+}
+/** What a supervised run produced. */
+export type SupervisedOutcome = CompletedRun | StoppedRun;
+/**
+ * Default limits: generous for a real corpus, finite for a hostile one.
+ *
+ * The heap limit is V8's old-generation size. It bounds where a parse
+ * accumulates, not the process: a child can still be stopped for reasons
+ * this number does not govern, and a child given too little cannot start at
+ * all, which the command reports rather than passing on.
+ */
+export declare const DEFAULT_SUPERVISION_LIMITS: SupervisionLimits;
+/**
+ * Runs a command in a child process that can be stopped.
+ */
+export declare class Supervisor {
+    /** The script the child runs: this package's executable. */
+    private readonly entryPoint;
+    /** The limits placed on the child. */
+    private readonly limits;
+    /**
+     * The directory the child runs in. Relative paths in the arguments, and the
+     * project whose `.ecrignore` applies, are resolved against it, so it must be
+     * the directory the command was configured with rather than whichever
+     * directory this process happens to be in.
+     */
+    private readonly workingDirectory;
+    /**
+     * Creates a supervisor.
+     *
+     * @param entryPoint - Path of the script the child runs
+     * @param limits - The limits to place on it
+     * @param workingDirectory - The directory the child runs in
+     */
+    constructor(entryPoint: string, limits?: SupervisionLimits, workingDirectory?: string);
+    /**
+     * Runs one command in a child process and waits for it.
+     *
+     * @param argv - The arguments to pass on, exactly as they were given
+     * @returns What the child produced, or why it was stopped
+     */
+    run(argv: readonly string[]): SupervisedOutcome;
+    /**
+     * Describes why a child did not finish, in terms of the limit it met.
+     *
+     * @param error - What `spawnSync` reported
+     * @returns The reason, as a phrase completing "the run did not finish because..."
+     */
+    private showFailure;
+}
+//# sourceMappingURL=supervisor.d.ts.map

package/dist/cli/supervisor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.d.ts","sourceRoot":"","sources":["../../src/cli/supervisor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAKH;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,MAAyB,CAAC;AAE5D,4CAA4C;AAC5C,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,uEAAuE;AACvE,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,4EAA4E;AAC5E,MAAM,WAAW,UAAU;IACzB,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,yFAAyF;IACzF,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,sCAAsC;AACtC,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,UAAU,CAAC;AAE1D;;;;;;;GAOG;AACH,eAAO,MAAM,0BAA0B,EAAE,iBAIxC,CAAC;AAEF;;GAEG;AACH,qBAAa,UAAU;IACrB,4DAA4D;IAC5D,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IAEpC,sCAAsC;IACtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAE3C;;;;;OAKG;IACH,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAE1C;;;;;;OAMG;gBAED,UAAU,EAAE,MAAM,EAClB,MAAM,GAAE,iBAA8C,EACtD,gBAAgB,GAAE,MAAsB;IAO1C;;;;;OAKG;IACI,GAAG,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,iBAAiB;IAiDtD;;;;;OAKG;IACH,OAAO,CAAC,WAAW;CAwBpB"}

package/dist/cli/supervisor.js

@@ -0,0 +1,139 @@
+/**
+ * Bounded Execution
+ *
+ * Parsing Markdown is where a corpus stops being data and starts being work
+ * the command cannot predict. The parser is recursive and, on some inputs,
+ * quadratic: four thousand nested bold spans inside a link label -- 16 KB --
+ * exhaust the call stack, and four thousand nested images -- 35 KB -- parse
+ * for the best part of a minute. Neither is a fault in a document anyone
+ * wrote on purpose, and neither can be found by inspecting a document before
+ * parsing it, since the cost is the parse.
+ *
+ * So `lint` and `stats` do their work in a child process this one starts and
+ * can stop. The child is this same executable, run once for the whole corpus,
+ * with a time limit and a heap limit; whatever it prints is relayed. If it
+ * has to be stopped, nothing it printed is relayed, because a report of a
+ * corpus that was never finished is worse than no report: half a JSON
+ * document still parses as JSON.
+ *
+ * This bounds the command, not the library. A host calling `lintDocument`
+ * directly runs the parser in its own process and must bound it itself.
+ */
+import { spawnSync } from 'node:child_process';
+/**
+ * The environment variable marking the child, so that it does the work
+ * rather than starting a child of its own.
+ */
+export const SUPERVISED_VARIABLE = 'ECR_SUPERVISED';
+/**
+ * Default limits: generous for a real corpus, finite for a hostile one.
+ *
+ * The heap limit is V8's old-generation size. It bounds where a parse
+ * accumulates, not the process: a child can still be stopped for reasons
+ * this number does not govern, and a child given too little cannot start at
+ * all, which the command reports rather than passing on.
+ */
+export const DEFAULT_SUPERVISION_LIMITS = {
+    timeoutMs: 120_000,
+    memoryMib: 2048,
+    maxOutputBytes: 64 * 1024 * 1024,
+};
+/**
+ * Runs a command in a child process that can be stopped.
+ */
+export class Supervisor {
+    /** The script the child runs: this package's executable. */
+    entryPoint;
+    /** The limits placed on the child. */
+    limits;
+    /**
+     * The directory the child runs in. Relative paths in the arguments, and the
+     * project whose `.ecrignore` applies, are resolved against it, so it must be
+     * the directory the command was configured with rather than whichever
+     * directory this process happens to be in.
+     */
+    workingDirectory;
+    /**
+     * Creates a supervisor.
+     *
+     * @param entryPoint - Path of the script the child runs
+     * @param limits - The limits to place on it
+     * @param workingDirectory - The directory the child runs in
+     */
+    constructor(entryPoint, limits = DEFAULT_SUPERVISION_LIMITS, workingDirectory = process.cwd()) {
+        this.entryPoint = entryPoint;
+        this.limits = limits;
+        this.workingDirectory = workingDirectory;
+    }
+    /**
+     * Runs one command in a child process and waits for it.
+     *
+     * @param argv - The arguments to pass on, exactly as they were given
+     * @returns What the child produced, or why it was stopped
+     */
+    run(argv) {
+        const nodeOptions = this.limits.memoryMib > 0 ? [`--max-old-space-size=${String(this.limits.memoryMib)}`] : [];
+        let child;
+        try {
+            child = spawnSync(process.execPath, [...nodeOptions, this.entryPoint, ...argv], {
+                encoding: 'utf8',
+                cwd: this.workingDirectory,
+                maxBuffer: this.limits.maxOutputBytes,
+                ...(this.limits.timeoutMs > 0 ? { timeout: this.limits.timeoutMs } : {}),
+                // A child busy in synchronous JavaScript cannot run a handler for a
+                // signal, but an idle one can, and a handled SIGTERM would leave this
+                // process waiting past the limit it just imposed. Nothing here needs
+                // the child's cooperation, so it is not asked for.
+                killSignal: 'SIGKILL',
+                env: { ...process.env, [SUPERVISED_VARIABLE]: '1' },
+            });
+        }
+        catch (error) {
+            // Starting a process can fail outright -- a limit node will not accept,
+            // a directory that is not there -- and that is a run that did not happen.
+            return {
+                kind: 'stopped',
+                reason: `it could not be started (${error instanceof Error ? error.message : String(error)})`,
+            };
+        }
+        if (child.error !== undefined) {
+            return { kind: 'stopped', reason: this.showFailure(child.error) };
+        }
+        // A child killed by a signal reports no exit code. Whatever reached this
+        // process before it died says nothing about the corpus as a whole.
+        if (child.status === null) {
+            return {
+                kind: 'stopped',
+                reason: `it was stopped (${child.signal ?? 'unknown signal'}) before it finished`,
+            };
+        }
+        return {
+            kind: 'completed',
+            stdout: child.stdout,
+            stderr: child.stderr,
+            exitCode: child.status,
+        };
+    }
+    /**
+     * Describes why a child did not finish, in terms of the limit it met.
+     *
+     * @param error - What `spawnSync` reported
+     * @returns The reason, as a phrase completing "the run did not finish because..."
+     */
+    showFailure(error) {
+        const code = error.code;
+        if (code === 'ETIMEDOUT') {
+            const seconds = (this.limits.timeoutMs / 1000).toFixed(0);
+            return (`it reached its time limit of ${seconds} second(s). One document can take that long ` +
+                `to parse when its Markdown is deeply nested. Raise the limit with --timeout <seconds>, ` +
+                `or narrow the corpus`);
+        }
+        if (code === 'ENOBUFS') {
+            const mebibytes = (this.limits.maxOutputBytes / (1024 * 1024)).toFixed(0);
+            return (`it produced more than ${mebibytes} MiB of output, which cannot be passed on whole. ` +
+                `Part of a report is not a report, so none of it was printed`);
+        }
+        return `it could not be run (${code ?? error.message})`;
+    }
+}
+//# sourceMappingURL=supervisor.js.map

package/dist/cli/supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervisor.js","sourceRoot":"","sources":["../../src/cli/supervisor.ts"],"names":[],"mappings":"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"}