@timiagama/ecr 0.0.1 → 0.1.0

package/dist/cli.d.ts

@@ -0,0 +1,247 @@
+/**
+ * ECR Command Line
+ *
+ * The executable entry point is `bin.ts`; this module only defines the
+ * commands, so that tests can drive them without spawning a process.
+ *
+ * Three commands, and deliberately no more:
+ *
+ * - `lint`  validates a corpus against the ECR structural rules
+ * - `stats` measures the explicit structure a corpus already carries
+ * - `init`  installs the ECR documentation, including the agent navigation
+ *           protocol, beside a corpus
+ *
+ * There is no `backlinks` command, and there should never be one. ECR's claim
+ * is that a corpus is navigable with `grep` alone; a navigation command here
+ * would quietly make the tool a dependency of the thing it exists to prove
+ * unnecessary. Navigation belongs in the protocol `init` installs, not in this
+ * binary.
+ */
+import type { ReportFormat } from './cli/diagnostic-reporter.js';
+import type { SupervisionLimits } from './cli/supervisor.js';
+/** Commands the CLI accepts. */
+export type CommandName = 'lint' | 'stats' | 'init';
+/**
+ * The stream a command's output belongs on.
+ *
+ * Results go to stdout; problems with the invocation itself go to stderr, so
+ * that `--format json` output piped into another tool is never interleaved
+ * with, or replaced by, an error message.
+ */
+export type OutputStream = 'stdout' | 'stderr';
+/**
+ * The result of running one command: what to print, where, and how to exit.
+ */
+export interface CommandOutcome {
+    /** Text to write. */
+    readonly output: string;
+    /** The stream to write it to. */
+    readonly stream: OutputStream;
+    /** Process exit code. */
+    readonly exitCode: number;
+}
+/**
+ * A parsed command line.
+ */
+export interface ParsedArguments {
+    /** The command to run. */
+    readonly command: CommandName;
+    /** Directory the command operates on. */
+    readonly corpusRoot: string;
+    /** Whether to run against the example corpus bundled with the package. */
+    readonly useExample: boolean;
+    /** Output format for `lint` and `stats`. */
+    readonly format: ReportFormat;
+    /** Glob patterns excluding project-specific meta-documents. */
+    readonly ignorePatterns: readonly string[];
+    /**
+     * Seconds a `lint` or `stats` run may take, when the command line said so;
+     * `0` for no limit, and absent when it did not say, which leaves whatever
+     * limit the run was configured with.
+     */
+    readonly timeoutSeconds?: number;
+    /** Mebibytes the run's heap may grow to, on the same terms. */
+    readonly maxMemoryMib?: number;
+}
+/**
+ * Where a command-line runner works. Both default to the real ones; tests
+ * supply their own so that nothing is written into this repository.
+ */
+export interface EcrCommandLineOptions {
+    /** The directory the command runs from, and the project root for `.ecrignore`. */
+    readonly workingDirectory?: string;
+    /** The package's own root: where `init` copies from and `--example` reads. */
+    readonly packageRoot?: string;
+    /**
+     * How to run `lint` and `stats` in a child process that can be stopped.
+     * Absent, they run in this process: the executable asks for supervision,
+     * because only it knows the script a child would have to run, and a host
+     * embedding the library bounds its own work.
+     */
+    readonly supervision?: SupervisionSettings;
+}
+/** How a supervised run is started and bounded. */
+export interface SupervisionSettings {
+    /** Path of the script the child runs: this package's executable. */
+    readonly entryPoint: string;
+    /** Limits overriding {@link DEFAULT_SUPERVISION_LIMITS}. */
+    readonly limits?: Partial<SupervisionLimits>;
+}
+/**
+ * Parses command-line arguments.
+ *
+ * Throws on anything it cannot understand rather than guessing, because a
+ * silently misread `--ignore` would quietly exclude documents from validation.
+ */
+export declare class ArgumentParser {
+    /**
+     * Parses an argument list.
+     *
+     * @param argv - Arguments, excluding the node executable and script path
+     * @returns The parsed command line
+     * @throws Error when the arguments cannot be understood
+     */
+    parse(argv: readonly string[]): ParsedArguments;
+    /**
+     * Reads an option's value as a whole number of some unit, where zero means
+     * no limit.
+     *
+     * @param value - The argument following the option
+     * @param option - The option's name, for the message
+     * @param unit - What the number counts, for the message
+     * @param maximum - The largest value the limit can be applied as
+     * @returns The number
+     * @throws When the value is missing, is not a whole number, or is beyond what can be applied
+     */
+    private static readWholeNumber;
+    /**
+     * Determines whether a string names a supported command.
+     *
+     * @param candidate - The string to test
+     * @returns `true` when the string is a command name
+     */
+    private isCommandName;
+}
+/**
+ * Runs the CLI commands.
+ *
+ * Output is returned rather than printed so that the commands can be exercised
+ * directly by tests without capturing a stream.
+ */
+export declare class EcrCommandLine {
+    /** Parses the command line. */
+    private readonly argumentParser;
+    /**
+     * The directory the command runs from: relative directories resolve against
+     * it, and it is the project root whose `.ecrignore` applies.
+     */
+    private readonly workingDirectory;
+    /** The package's own root, holding `package.json` and what `init` installs. */
+    private readonly packageRoot;
+    /** How to run the parsing commands in a child process, when asked to. */
+    private readonly supervision;
+    /**
+     * Creates a command-line runner.
+     *
+     * @param options - Where the command runs from and where the package lives; both default to the real ones
+     */
+    constructor(options?: EcrCommandLineOptions);
+    /**
+     * Runs one invocation.
+     *
+     * @param argv - Arguments, excluding the node executable and script path
+     * @returns The text to print and the process exit code
+     */
+    run(argv: readonly string[]): CommandOutcome;
+    /**
+     * Runs `lint` or `stats` against a corpus.
+     *
+     * @param parsed - The parsed command line
+     * @param corpusRoot - Resolved corpus directory
+     * @param displayedRoot - How to name the corpus in messages
+     * @param applyProjectIgnore - Whether the project's `.ecrignore` applies
+     * @returns The text to print and the process exit code
+     */
+    private runValidation;
+    /**
+     * Installs the ECR documentation into a new or empty directory, keeping the
+     * repository's layout, and adds that directory to the project's
+     * `.ecrignore` so that linting the project does not validate it.
+     *
+     * Everything that could stop the installation is checked before anything is
+     * written, and a failure part-way removes what was copied.
+     *
+     * @param destination - Resolved installation directory
+     * @param displayedDestination - The directory as the user typed it, for messages
+     * @returns The text to print and the process exit code
+     */
+    private runInit;
+    /**
+     * Removes what a failed installation copied. The destination was new or
+     * empty, so nothing of the user's is inside it.
+     *
+     * @param destination - The installation directory
+     * @param existed - Whether it existed, empty, before installation began
+     * @returns Why removal failed, or `undefined` when everything copied was removed
+     */
+    private removePartialInstallation;
+    /**
+     * Reads how this invocation should bound its parsing, if at all.
+     *
+     * @returns The supervision settings, or `undefined` when this invocation does the work itself
+     */
+    private readSupervision;
+    /**
+     * Runs `lint` or `stats` in a child process with a time limit and a heap
+     * limit, and passes on what it produced.
+     *
+     * A child that had to be stopped produced no usable report, however much of
+     * one reached this process, so none of it is passed on: the invocation
+     * failed, and says why.
+     *
+     * @param settings - Where the child's script is, and any limits overriding the defaults
+     * @param argv - The arguments to pass on, exactly as they were given
+     * @param parsed - The same arguments, for the limits they carry
+     * @returns The child's output and exit code, or the reason it was stopped
+     */
+    private runSupervised;
+    /**
+     * Describes a child that ended in a way this command never ends.
+     *
+     * Running out of heap is worth naming, because it is the one such ending a
+     * user can do anything about, and the limit that caused it is one they set.
+     *
+     * @param outcome - What the child produced before it ended
+     * @param limits - The limits it was given
+     * @returns The reason, as a phrase completing "ecr did not finish..."
+     */
+    private showAbnormalExit;
+    /**
+     * Builds a successful outcome, written to stdout.
+     *
+     * @param output - The text to print
+     * @returns The outcome
+     */
+    private succeed;
+    /**
+     * Builds the outcome of an invocation that could not run, written to stderr.
+     *
+     * @param output - The message to print
+     * @returns The outcome
+     */
+    private fail;
+    /**
+     * Reads the published package version from `package.json`.
+     *
+     * @returns The package version
+     */
+    private showPackageVersion;
+    /**
+     * Determines whether a corpus result contains any error-severity diagnostic.
+     *
+     * @param corpusResult - The result to inspect
+     * @returns `true` when at least one error was reported
+     */
+    private tellCorpusHasErrors;
+}
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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