sourcemonkey 0.0.0-stage → 0.5.0

package/lib/harness/command-lines.js

@@ -0,0 +1,180 @@
+// Turning lines of input into `sm-dev start` commands, for the prompt,
+// piped input, and a list of commands sent in one go.
+//
+// Most commands are one line. `eval` (its JavaScript), `set` (its
+// JSON), `type` (its text) and `cdp` (one call per line) can take
+// several, as a block:
+//
+//   eval T2 --script {{
+//   const rows = [...document.querySelectorAll('.athing')];
+//   rows.map((r) => r.id)
+//   }}
+//
+// `{{` ending the first line opens the block, and a line that is just
+// `}}` closes it. Not `{` / `}`: a line holding only `}` ends any
+// JavaScript function or JSON object, so it would close the block
+// early, where one holding only `}}` almost never appears.
+//
+// Outside a block, blank lines are skipped and a line starting with `#`
+// is a comment (no command starts with `#`). Inside one, every line is
+// the block's own.
+import { splitWords } from './command-args.js';
+import { echoLine } from './output-style.js';
+import { ALIASES, COMMAND_NAMES, commandSyntax } from './command-list.js';
+const OPEN = '{{';
+const CLOSE = '}}';
+// The commands that take a block, as their syntax says.
+const BLOCK_COMMANDS = new Set(COMMAND_NAMES.filter((name) => commandSyntax(name).base.block).sort());
+/**
+ * A `{{` after a command that takes no block. Its lines up to `}}` are
+ * skipped, not run one by one as commands.
+ */
+export const NOT_A_BLOCK_COMMAND = `Only the ${listed([...BLOCK_COMMANDS])} commands take a {{ block, so its lines up to }} are skipped`;
+/**
+ * A `}}` line with more after it (`}} --nowait`). Only a line of just
+ * `}}` closes a block, so the line would otherwise be taken as the
+ * block's, leaving it open. Not `}});` or `}},`, which end JavaScript
+ * calls and JSON objects: only words after a space.
+ */
+export const TEXT_AFTER_CLOSE = 'Nothing can follow }} on its line, so the block is dropped (put flags before the {{)';
+const CLOSE_WITH_TEXT = /^}}\s+\S/;
+/**
+ * A `{{` with code after it on its line (`eval {{ const x = 1`). The
+ * block's lines would otherwise each run as a command.
+ */
+export const OPEN_NOT_LAST = 'A {{ block\'s content starts on the line after the {{, and its }} goes on a line of its own';
+/** `a, b and c`. */
+export function listed(names) {
+    return names.length < 2 ? names.join('') : `${names.slice(0, -1).join(', ')} and ${names.at(-1)}`;
+}
+/** A block the input ended inside of. */
+export function unclosedBlockMessage(line) {
+    return `The {{ block on line ${line} has no }} line to end it`;
+}
+/**
+ * Collects lines into commands, one line at a time: each line gives a
+ * command, nothing (a blank, a comment, or a line inside a block), or
+ * an error for a line that can't be taken.
+ */
+export class CommandAssembler {
+    block = null;
+    // The block was refused, and its lines are being skipped.
+    refused = false;
+    body = [];
+    count = 0;
+    /** Whether a block is open, waiting for its `}}`. */
+    get open() {
+        return this.block !== null;
+    }
+    push(raw) {
+        const line = raw.replace(/\r$/, '');
+        const n = ++this.count;
+        const trimmed = line.trim();
+        if (this.block) {
+            if (CLOSE_WITH_TEXT.test(trimmed)) {
+                this.drop();
+                return { error: TEXT_AFTER_CLOSE };
+            }
+            if (trimmed !== CLOSE) {
+                this.block.source.push(line);
+                this.body.push(line);
+                return null;
+            }
+            const command = this.block;
+            command.source.push(line);
+            if (this.refused) {
+                this.drop();
+                return null;
+            }
+            // The block keeps its own line breaks, so `//` comments and
+            // statements without semicolons read as they were written.
+            // Even blank lines are content: `type` types them.
+            if (this.body.length > 0)
+                command.text += '\n' + this.body.join('\n');
+            this.block = null;
+            this.body = [];
+            return { command };
+        }
+        if (!trimmed || trimmed.startsWith('#'))
+            return null;
+        const words = trimmed.split(/\s+/);
+        if (words.length > 1 && words.at(-1) === OPEN) {
+            this.block = { text: trimmed.slice(0, -OPEN.length).trimEnd(), source: [line], line: n };
+            this.refused = !BLOCK_COMMANDS.has(ALIASES[words[0]] ?? words[0]);
+            return this.refused ? { error: NOT_A_BLOCK_COMMAND } : null;
+        }
+        // Not where the text may hold the word (type's). Split as a
+        // command's words are, so a {{ in a quoted string is left alone.
+        const name = ALIASES[words[0]] ?? words[0];
+        const split = splitWords(trimmed);
+        if (BLOCK_COMMANDS.has(name) && !commandSyntax(name).base.bracesInText && split.slice(1, -1).some((w) => w.text === OPEN)) {
+            // Unless a }} follows on this line (`eval {{ x }}`, `{{ f()}});`),
+            // the lines up to the }} line are the refused block's: skipped,
+            // not each refused as a command.
+            if (!trimmed.slice(trimmed.indexOf(OPEN) + OPEN.length).includes(CLOSE)) {
+                this.block = { text: trimmed, source: [line], line: n };
+                this.refused = true;
+            }
+            return { error: OPEN_NOT_LAST };
+        }
+        return { command: { text: trimmed, source: [line], line: n } };
+    }
+    /**
+     * Drops an open block, returning the line it started on, or null when
+     * none was open.
+     */
+    drop() {
+        const start = this.block?.line ?? null;
+        this.block = null;
+        this.body = [];
+        this.refused = false;
+        return start;
+    }
+}
+/**
+ * Whether the lines of `text` end outside a `{{` block, so are ready to
+ * run, rather than waiting for a `}}` line.
+ */
+export function endsOutsideBlock(text) {
+    const assembler = new CommandAssembler();
+    for (const line of text.split('\n'))
+        assembler.push(line);
+    return !assembler.open;
+}
+export const NONE_RUN = 'None of the commands were run.';
+/**
+ * A whole list of commands, as sent in one go or read from a file.
+ * Checked in full before any runs, so a mistake anywhere in it (a `{{`
+ * after the wrong command, a block never closed) runs none of it
+ * rather than half.
+ */
+export function parseCommandList(text) {
+    const assembler = new CommandAssembler();
+    const commands = [];
+    const lines = text.split('\n');
+    // A final newline doesn't start another line.
+    if (lines.at(-1) === '')
+        lines.pop();
+    for (const [i, line] of lines.entries()) {
+        const got = assembler.push(line);
+        if (got && 'error' in got)
+            return { error: `Line ${i + 1}: ${got.error}. ${NONE_RUN}` };
+        if (got)
+            commands.push(got.command);
+    }
+    const unclosed = assembler.drop();
+    if (unclosed !== null)
+        return { error: `${unclosedBlockMessage(unclosed)}. ${NONE_RUN}` };
+    return { commands };
+}
+/**
+ * A command as it was written, for heading its output: `mark` before
+ * the first line and `...` before the rest, as the prompt shows them.
+ */
+export function echoCommand(command, mark = '>') {
+    return command.source.map((line, i) => (i === 0 ? echoLine(mark, line.trim()) : echoLine('...', line)));
+}
+/** A word as a shell would need it written, for echoing a command. */
+export function shellWord(word) {
+    return /^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replace(/'/g, "'\\''")}'`;
+}

package/lib/harness/command-list.d.ts

@@ -0,0 +1,206 @@
+import { type ManagerName } from './managers.js';
+export declare const PROBE_MAX = 10;
+export declare const PART_LIMIT = 5;
+export declare const CONTEXT_LINES = 10;
+/**
+ * A term and what it means: an argument, an option, a way to name
+ * something. `commands`: for an option listed in a section rather than
+ * under one command, the commands that take it, or a subcommand alone
+ * (`wait log`).
+ */
+export interface HelpItem {
+    term: string;
+    /** Wrapped to fit; each element starts a new line. */
+    about: string | string[];
+    commands?: string[];
+}
+/**
+ * How a command's words are read (command-args.ts): what its arguments
+ * are, beside its flags.
+ * - `none`: none.
+ * - `words`: separate words, quotes grouping one; `max` of them.
+ * - `selector`: the rest of the line as typed, less the flags, which can
+ *   be anywhere (a selector never starts with --).
+ * - `text`: `before` words, then the rest of the line as typed, less
+ *   the flags in it: a word of its own shaped like one (`--name`,
+ *   `--name=...`) is a flag anywhere, unless the text is one `/regex/`.
+ */
+export interface ArgSyntax {
+    args: 'none' | 'words' | 'selector' | 'text';
+    max?: number;
+    before?: number;
+    /** A tab (T2, targetId=...) can lead its arguments. */
+    tab?: boolean;
+    /** It takes a `{{` block of lines. */
+    block?: boolean;
+    /** Its text can hold a `{{` word (type's), rather than one being a slip. */
+    bracesInText?: boolean;
+    /** Text quoted as a whole is unquoted: `any` quotes (default), `single` (JSON), or `none` (JavaScript). */
+    unquote?: 'any' | 'single' | 'none';
+}
+export interface HelpCommand {
+    /** The command's name, then its arguments. */
+    usage: string;
+    /**
+     * How its words are read; `words` when not given. A form named by a
+     * keyword (`wait log <text>`) has its own.
+     */
+    syntax?: ArgSyntax;
+    about: string | string[];
+    args?: HelpItem[];
+    options?: HelpItem[];
+    /** Options in titled groups, for a command with many (start). */
+    optionGroups?: {
+        title: string;
+        options: HelpItem[];
+    }[];
+    /**
+     * Listed for the reader's sake only: the command's help is elsewhere,
+     * or it is no command (`<command> --help`).
+     */
+    pointer?: boolean;
+    /** A blank line before it in the full help. */
+    gap?: boolean;
+    /** Its line in `help commands`; the first sentence of `about` when not given. */
+    summary?: string;
+    /** The managers (`--manager`) it works with; every one when not given. */
+    managers?: ManagerName[];
+}
+export interface HelpSection {
+    title: string;
+    /**
+     * Its help topic, for `help <name>`, shown after its title: ## Logs [`help logs`].
+     * A section that is just the command of the same name shows that
+     * command's help instead, which has all its options.
+     */
+    name?: string;
+    /** What it covers, beside its name in the `help` index. */
+    summary?: string;
+    /**
+     * Lines before the rest, each wrapped to fit (`textLines`). '' is a
+     * blank line; `- ` or `1. `, after any spaces, starts a bullet; any
+     * other line starting with spaces is code, shown as is.
+     */
+    text?: string[];
+    items?: HelpItem[];
+    commands?: HelpCommand[];
+    /** Options several commands take, or the section's own. */
+    options?: HelpItem[];
+    optionsTitle?: string;
+    subsections?: HelpSection[];
+}
+/** The longest a Node timer can wait, in seconds. */
+export declare const MAX_TIMER_SECONDS: number;
+/** The flag any command takes, listed where it waits on something (command-args.ts). */
+export declare const TIMEOUT_FLAG = "--timeout-seconds";
+/** A `--timeout-seconds` that isn't a number of seconds, on any command. */
+export declare const TIMEOUT_NEEDS_SECONDS: string;
+/** A `--timeout-seconds` value in ms, or null when it isn't a number of seconds (`TIMEOUT_NEEDS_SECONDS`). */
+export declare function timeoutSecondsMs(value: string | true): number | null;
+export declare const HELP_SECTIONS: HelpSection[];
+/** What help shows: a topic (`all`, `commands`, a section), or a command or one of its subcommands. */
+export type HelpTarget = {
+    topic: string;
+} | {
+    command: string;
+    subcommand?: string;
+};
+/**
+ * `sm-dev help [topic|command [subcommand]]`'s words, as what they ask
+ * for: none for the index. An error for a name that is no topic or
+ * command, a subcommand the command doesn't have, or more words.
+ */
+export declare function helpTarget(words: readonly string[]): HelpTarget | null | {
+    error: string;
+};
+/** `sm-dev help`'s text for `target` (the index for null), in color for a terminal that has it. */
+export declare function helpText(target: HelpTarget | null, color?: boolean): string;
+/**
+ * One command's help, or one subcommand's (`save`), or with `''`, its
+ * forms with none (`script <script>`), in color for a terminal that has
+ * it. For `<command> --help`, which always means the command, never a
+ * topic of the same name.
+ */
+export declare function commandHelp(name: string, subcommand?: string, color?: boolean): string;
+/** The managers `name` works with: as its help says, else every one. */
+export declare function commandManagers(name: string): ManagerName[];
+/**
+ * Why `name` can't be used with `manager`, or null when it can. `whose`
+ * says where the manager came from: `this run uses`, `--manager names`.
+ */
+export declare function unsupportedCommand(name: string, manager: ManagerName, whose: string): string | null;
+/** Every command's name, in the list's order; one with several forms once. */
+export declare const COMMAND_NAMES: string[];
+/** The commands sm-dev runs itself, never sent to a run. */
+export declare const CLIENT_COMMANDS: Set<string>;
+/**
+ * The commands sm-dev runs itself when given only files and URLs, and
+ * sends to a run for its scripts and tabs. Both lists name them.
+ */
+export declare const SHARED_COMMANDS: Set<string>;
+/** The commands sm-dev can run itself: its own and the shared ones. */
+export declare const OWN_COMMANDS: Set<string>;
+/** The commands a run takes. */
+export declare const RUN_COMMAND_NAMES: string[];
+/** The names a command also answers to, when run and in `help`. */
+export declare const ALIASES: Record<string, string>;
+/**
+ * Singular and plural names that are one command (`script 2` picks as
+ * `scripts 2` does), whose help is shown together, under the plural.
+ */
+export declare const SAME_COMMANDS: Record<string, string>;
+/** A typed name as the command it is, aliases resolved; null for none. */
+export declare function commandNamed(typed: string): string | null;
+/** A command's subcommands (`list`, `show`, ... for `script`), in its help's order. */
+export declare function subcommandsOf(name: string): string[];
+/**
+ * Said for a subcommand `name` doesn't have, or null when it has it.
+ * `''` names its forms with no subcommand (`script <script>`).
+ */
+export declare function noSuchSubcommand(name: string, subcommand: string): string | null;
+/**
+ * The words a command's forms with no subcommand spell out as they are
+ * (`all` in `wait [T<n>|all]`), which are arguments, not subcommands.
+ */
+export declare function plainFormWords(name: string): string[];
+/** Whether a command has a form with no subcommand (`script <script>`, `wait <time>`), as opposed to only subcommands (`manager`). */
+export declare function hasPlainForm(name: string): boolean;
+/**
+ * The flags a command takes, for checking a sent command's words: the
+ * first word of each option's term.
+ */
+export declare function commandFlags(name: string): string[];
+/**
+ * How a flag takes a value: `--out FILE` takes one, `--visible` none,
+ * and `--script[=<script>]` one only when joined by `=`, so a bare
+ * `--script` never takes the next word.
+ */
+export type FlagKind = 'bool' | 'value' | 'optional';
+/** How command-args.ts reads a command's words. */
+export interface CommandSyntax {
+    /** Its syntax, before any form's keyword. */
+    base: ArgSyntax;
+    /** Each form's, by its keyword (`wait log`). */
+    forms: Record<string, ArgSyntax>;
+    /** The forms that name what they act on before their keyword (`script <script> show`). */
+    subjectForms: Set<string>;
+    /** Its flags, any subcommand's: each takes a value, none, or one only as `--name=value`. */
+    flags: Record<string, FlagKind>;
+    /** The flags each subcommand takes, by its keyword; `''` for the forms with none. */
+    formFlags: Record<string, string[]>;
+    /** What a value flag's value is, as its help names it (`<path>`, `FILE`). */
+    values: Record<string, string>;
+    /** Its usage lines, without `sm-dev`, for messages. */
+    usage: string[];
+}
+/** A command's syntax, from its help; `words` and no flags for a name that is none. */
+export declare function commandSyntax(name: string): CommandSyntax;
+export declare const GLOBAL_FLAGS: string[];
+export declare const VALUE_GLOBALS: Set<string>;
+export declare function globalFlagMistake(flag: string): string;
+/**
+ * A command's flag it doesn't have, naming the ones it does, so a near
+ * miss (`--timeout` for `--timeout-seconds`) shows the right one.
+ * `command` can be a subcommand (`script save`).
+ */
+export declare function noSuchFlag(command: string, flag: string, known?: string[]): string;