@cplieger/deadset-ts 8.0.0-dev.1 → 8.0.0-dev.10

package/src/text/named-files.ts

@@ -0,0 +1,68 @@
+/**
+ * The files a command's text names, read as plain text: the text is searched for each file's
+ * names, which every spelling of its path contains, so no part of it is split, unquoted or
+ * skipped first.
+ */
+
+import { dirnamePath, normalizePath, relativePath } from "../paths.ts";
+
+/** The extension a source or an emitted file carries: a JavaScript or TypeScript one, or a declaration's. */
+const SOURCE_EXTENSION = /\.(?:d\.[cm]?ts|[cm]?[jt]s|[jt]sx)$/u;
+
+/** One file, and every path it is spelled by: its own and each one the project writes it to. */
+interface Spelled<File> {
+  readonly file: File;
+  readonly paths: readonly string[];
+}
+
+/**
+ * The names whose presence in a text holds one path below `dir`: its last name without the
+ * extension, or with it where nothing else is left, and for an `index` file its directory's
+ * last name, and `.` too where that is `dir`. Every spelling of the path relative to `dir`,
+ * with or without `./`, `/` or `\`, its extension or its `/index` part, and every longer path
+ * ending in one, holds one of them. None is empty, because an empty name is in every text.
+ */
+function stemsOf(path: string, dir: string): readonly string[] {
+  const last = path.slice(path.lastIndexOf("/") + 1);
+  const bare = last.replace(SOURCE_EXTENSION, "");
+  const name = bare === "" ? last : bare;
+  if (name !== "index") {
+    return [name];
+  }
+  const parent = dirnamePath(path);
+  return [
+    name,
+    parent.slice(parent.lastIndexOf("/") + 1),
+    ...(parent === normalizePath(dir) ? ["."] : []),
+  ].filter((stem) => stem !== "");
+}
+
+/**
+ * Every file of `files` below `dir` that `text` names: one whose {@link stemsOf} a path of it
+ * spells appears anywhere in the text. A file the text does not name may be held too, and no
+ * file it names is missed.
+ */
+export function spelledFiles<File>(
+  text: string,
+  dir: string,
+  files: readonly Spelled<File>[],
+): readonly File[] {
+  const byStem = new Map<string, File[]>();
+  for (const { file, paths } of files) {
+    const [own] = paths;
+    if (own === undefined || relativePath(dir, own) === undefined) {
+      continue;
+    }
+    for (const stem of new Set(paths.flatMap((path) => stemsOf(path, dir)))) {
+      byStem.set(stem, [...(byStem.get(stem) ?? []), file]);
+    }
+  }
+  const found = new Set<File>();
+  // One pass per stem length: each place of the text is looked up once for every length.
+  for (const length of new Set([...byStem.keys()].map((stem) => stem.length))) {
+    for (let at = 0; at + length <= text.length; at += 1) {
+      byStem.get(text.slice(at, at + length))?.forEach((file) => found.add(file));
+    }
+  }
+  return [...found];
+}

package/src/text/shell.ts

@@ -0,0 +1,161 @@
+/**
+ * Shell command lines read as text, never run: the commands a line runs, the tokens the
+ * Contract splits a command into, and the words POSIX token recognition reads.
+ */
+
+/**
+ * The shell's list and pipeline operators, each of which ends one command. An `&` beside a
+ * redirection's `<` or `>` (`2>&1`, and bash's `&>log`) is part of the redirection.
+ */
+const COMMAND_OPERATORS = /&&|\|\||;|\||(?<![<>])&(?!>)/u;
+
+/** Where a command splits into tokens: white space and the operators the Contract names. */
+const TOKEN_SEPARATORS = /\s+|&&|\|\||;|\|/u;
+
+/** A text written inside one pair of quotes. */
+const QUOTED = /^(["'])(.*)\1$/su;
+
+/** The commands one line runs, the text between two of the shell's list and pipeline operators. */
+export function commandsOf(line: string): readonly string[] {
+  return line.split(COMMAND_OPERATORS);
+}
+
+/** One text with one pair of enclosing quotes removed. */
+export function unquoted(text: string): string {
+  return text.replace(QUOTED, "$2");
+}
+
+/**
+ * Every token one script's command line holds, each with one pair of enclosing quotes
+ * removed. A token holding a wildcard is a pattern rather than a path, and names no
+ * entry point.
+ */
+export function scriptTokens(command: string): readonly string[] {
+  return command
+    .split(TOKEN_SEPARATORS)
+    .map(unquoted)
+    .filter((token) => token !== "" && !token.includes("*"));
+}
+
+/** One shell line up to its comment: a `#` that starts a word outside quotes. */
+export function withoutComment(line: string): string {
+  let quote = "";
+  for (let at = 0; at < line.length; at += 1) {
+    const char = line[at];
+    if (quote !== "") {
+      if (char === quote) {
+        quote = "";
+      } else if (char === "\\" && quote === '"') {
+        at += 1;
+      }
+    } else if (char === "'" || char === '"') {
+      quote = char;
+    } else if (char === "\\") {
+      at += 1;
+    } else if (char === "#" && (at === 0 || /\s/u.test(line[at - 1] ?? ""))) {
+      return line.slice(0, at);
+    }
+  }
+  return line;
+}
+
+/** The characters that end a word outside quotes and separate nothing: blanks. */
+// Stryker disable next-line Regex: its \v to \V mutant is no valid escape under the u flag, so the whole module fails to parse
+const BLANK = /[ \t\r\f\v]/u;
+
+/** The characters that end a word outside quotes and begin an operator: newline included. */
+const OPERATOR = /[\n;&|()<>]/u;
+
+/** The characters a backslash escapes inside double quotes; before any other it stands for itself. */
+const DOUBLE_QUOTE_ESCAPES = new Set(["$", "`", '"', "\\"]);
+
+/**
+ * The words of one command line, as POSIX token recognition reads quotes, backslashes,
+ * line continuations, comments and operators. A word an expansion may change (an unquoted
+ * `$`, backquote, glob character or leading `~`, or a `$` or backquote in double quotes)
+ * is computed, and so is the rest of a line whose quote is never closed. A computed word
+ * and each operator are undefined, so a flag's file is never read across them.
+ */
+export function shellWords(command: string): readonly (string | undefined)[] {
+  const words: (string | undefined)[] = [];
+  let word: string | undefined;
+  let computed = false;
+  const end = (): void => {
+    if (word !== undefined) {
+      words.push(computed ? undefined : word);
+    }
+    word = undefined;
+    computed = false;
+  };
+  for (let at = 0; at < command.length; at += 1) {
+    const char = command.charAt(at);
+    if (char === "\\" && command.charAt(at + 1) === "\n") {
+      at += 1;
+    } else if (BLANK.test(char)) {
+      end();
+    } else if (OPERATOR.test(char)) {
+      end();
+      words.push(undefined);
+    } else if (char === "#" && word === undefined) {
+      const newline = command.indexOf("\n", at);
+      at = newline < 0 ? command.length : newline - 1;
+    } else if (char === "\\") {
+      at += 1;
+      word = (word ?? "") + command.charAt(at);
+    } else if (char === "'" || char === '"') {
+      const close = closingQuote(command, at);
+      if (close < 0) {
+        word ??= "";
+        computed = true;
+        break;
+      }
+      const quoted =
+        char === "'"
+          ? { text: command.slice(at + 1, close), computed: false }
+          : doubleQuoted(command.slice(at + 1, close));
+      word = (word ?? "") + quoted.text;
+      computed ||= quoted.computed;
+      at = close;
+    } else {
+      computed ||= /[$`*?[]/u.test(char) || (char === "~" && word === undefined);
+      word = (word ?? "") + char;
+    }
+  }
+  end();
+  return words;
+}
+
+/** The text between one pair of double quotes, unescaped, and whether an expansion may change it. */
+function doubleQuoted(inner: string): { readonly text: string; readonly computed: boolean } {
+  let text = "";
+  let computed = false;
+  for (let at = 0; at < inner.length; at += 1) {
+    const char = inner.charAt(at);
+    const next = inner.charAt(at + 1);
+    if (char === "\\" && next === "\n") {
+      at += 1;
+    } else if (char === "\\" && DOUBLE_QUOTE_ESCAPES.has(next)) {
+      text += next;
+      at += 1;
+    } else {
+      computed ||= char === "$" || char === "`";
+      text += char;
+    }
+  }
+  return { text, computed };
+}
+
+/** The index of the quote that closes the one at `open`, or -1 where none does. */
+function closingQuote(command: string, open: number): number {
+  const quote = command.charAt(open);
+  for (let at = open + 1; at < command.length; at += 1) {
+    const char = command.charAt(at);
+    if (char === quote) {
+      return at;
+    }
+    if (quote === '"' && char === "\\") {
+      at += 1;
+    }
+  }
+  return -1;
+}

package/src/text/yaml.ts

@@ -0,0 +1,423 @@
+/**
+ * The value of a YAML configuration document in the subset tool configurations write:
+ * block mappings and sequences, flow mappings and sequences, and plain, single-quoted and
+ * double-quoted scalars, with comments. A document using anything else, an anchor, an
+ * alias, a tag, a block scalar, a complex key or a second document, has no value here,
+ * as a JSON document that does not parse has none.
+ */
+
+import { isRecord } from "../json-document.ts";
+
+/** One line of the document with its comment removed, by its indentation and its content. */
+interface Line {
+  readonly indent: number;
+  readonly text: string;
+}
+
+/** A failure to read the document within the subset; it ends the whole reading. */
+class Unsupported extends Error {}
+
+/** The characters after which a quote opens a quoted scalar rather than standing in a plain one. */
+const SCALAR_START = new Set(["", ":", "-", "[", "{", ","]);
+
+/** The plain scalars YAML's core schema reads as something other than a string. */
+const CORE: ReadonlyMap<string, unknown> = new Map<string, unknown>([
+  ["true", true],
+  ["True", true],
+  ["TRUE", true],
+  ["false", false],
+  ["False", false],
+  ["FALSE", false],
+  ["null", null],
+  ["Null", null],
+  ["NULL", null],
+  ["~", null],
+  ["", null],
+]);
+
+const NUMBER = /^[-+]?(?:\d+|\d*\.\d+|\d+\.\d*)(?:[eE][-+]?\d+)?$/u;
+
+/** The text of one line before its comment: a `#` at the line's start or after a blank, outside quotes. */
+function withoutComment(line: string): string {
+  let quote: string | undefined;
+  let previous = "";
+  for (let at = 0; at < line.length; at += 1) {
+    const char = line.charAt(at);
+    if (quote !== undefined) {
+      if (quote === '"' && char === "\\") {
+        at += 1;
+      } else if (char === quote) {
+        quote = undefined;
+      }
+      continue;
+    }
+    if ((char === "'" || char === '"') && SCALAR_START.has(previous)) {
+      quote = char;
+    } else if (char === "#" && (at === 0 || /\s/u.test(line.charAt(at - 1)))) {
+      return line.slice(0, at);
+    }
+    if (!/\s/u.test(char)) {
+      previous = char;
+    }
+  }
+  return line;
+}
+
+/** The value one scalar's text denotes, quoted or plain. */
+function scalar(text: string): unknown {
+  const value = text.trim();
+  if (value.startsWith("'")) {
+    if (!value.endsWith("'") || value.length < 2) {
+      throw new Unsupported();
+    }
+    return value.slice(1, -1).replaceAll("''", "'");
+  }
+  if (value.startsWith('"')) {
+    try {
+      return JSON.parse(value) as unknown;
+    } catch {
+      throw new Unsupported();
+    }
+  }
+  if (/^[&*!|>%@`?]/u.test(value) || value === "---" || value === "...") {
+    throw new Unsupported();
+  }
+  if (/:(?:\s|$)/u.test(value)) {
+    throw new Unsupported();
+  }
+  if (CORE.has(value)) {
+    return CORE.get(value);
+  }
+  return NUMBER.test(value) ? Number(value) : value;
+}
+
+/** Reads one flow collection or flow scalar from `text` at `at`, answering the value and where it ends. */
+function flow(text: string, start: number): { readonly value: unknown; readonly end: number } {
+  let at = start;
+  const skip = (): void => {
+    while (at < text.length && /\s/u.test(text.charAt(at))) {
+      at += 1;
+    }
+  };
+  skip();
+  const open = text.charAt(at);
+  if (open === "[" || open === "{") {
+    const close = open === "[" ? "]" : "}";
+    const items: unknown[] = [];
+    const object: Record<string, unknown> = {};
+    at += 1;
+    for (;;) {
+      skip();
+      if (text.charAt(at) === close) {
+        return { value: open === "[" ? items : object, end: at + 1 };
+      }
+      const item = flow(text, at);
+      at = item.end;
+      skip();
+      if (open === "{") {
+        if (text.charAt(at) !== ":" || typeof item.value !== "string") {
+          throw new Unsupported();
+        }
+        const held = flow(text, at + 1);
+        object[item.value] = held.value;
+        at = held.end;
+        skip();
+      } else {
+        items.push(item.value);
+      }
+      if (text.charAt(at) === ",") {
+        at += 1;
+      } else if (text.charAt(at) !== close) {
+        throw new Unsupported();
+      }
+    }
+  }
+  if (open === "'" || open === '"') {
+    let end = at + 1;
+    for (; end < text.length; end += 1) {
+      const char = text.charAt(end);
+      if (open === '"' && char === "\\") {
+        end += 1;
+      } else if (char === open && !(open === "'" && text.charAt(end + 1) === "'")) {
+        break;
+      } else if (char === open) {
+        end += 1;
+      }
+    }
+    if (end >= text.length) {
+      throw new Unsupported();
+    }
+    return { value: scalar(text.slice(at, end + 1)), end: end + 1 };
+  }
+  let end = at;
+  while (end < text.length && !",]}".includes(text.charAt(end))) {
+    if (text.charAt(end) === ":" && /[\s,\]}]/u.test(text.charAt(end + 1) || " ")) {
+      break;
+    }
+    end += 1;
+  }
+  return { value: scalar(text.slice(at, end)), end };
+}
+
+/** A value written on one or more lines of a block, read whole: a flow node, else one plain scalar. */
+function flowValue(text: string): unknown {
+  if (!/^["'[{]/u.test(text)) {
+    return scalar(text);
+  }
+  const read = flow(text, 0);
+  if (text.slice(read.end).trim() !== "") {
+    throw new Unsupported();
+  }
+  return read.value;
+}
+
+/** The position of a mapping key's `:` in one line's content, or -1 where the content is no mapping entry. */
+function keyEnd(text: string): number {
+  let quote: string | undefined;
+  for (let at = 0; at < text.length; at += 1) {
+    const char = text.charAt(at);
+    if (quote !== undefined) {
+      if (quote === '"' && char === "\\") {
+        at += 1;
+      } else if (char === quote) {
+        quote = undefined;
+      }
+    } else if (at === 0 && (char === "'" || char === '"')) {
+      quote = char;
+    } else if (char === "[" || char === "{") {
+      return -1;
+    } else if (char === ":" && (at + 1 === text.length || /\s/u.test(text.charAt(at + 1)))) {
+      return at;
+    }
+  }
+  return -1;
+}
+
+/** How many flow collections one text opens and leaves unclosed, quotes read through. */
+function openCollections(text: string): number {
+  let depth = 0;
+  let quote: string | undefined;
+  for (let at = 0; at < text.length; at += 1) {
+    const char = text.charAt(at);
+    if (quote !== undefined) {
+      if (quote === '"' && char === "\\") {
+        at += 1;
+      } else if (char === quote) {
+        quote = undefined;
+      }
+    } else if (
+      (char === "'" || char === '"') &&
+      SCALAR_START.has(text.slice(0, at).trim().slice(-1))
+    ) {
+      quote = char;
+    } else if (char === "[" || char === "{") {
+      depth += 1;
+    } else if (char === "]" || char === "}") {
+      depth -= 1;
+    }
+  }
+  return depth;
+}
+
+/** Whether one line's content is a block sequence item. */
+function isItem(text: string): boolean {
+  return text === "-" || text.startsWith("- ");
+}
+
+/** Reads the document's lines as one value. */
+class Reader {
+  private at = 0;
+  private readonly lines: Line[];
+
+  constructor(lines: Line[]) {
+    this.lines = lines;
+  }
+
+  /** The whole document's value. */
+  document(): unknown {
+    const first = this.lines[0];
+    if (first === undefined) {
+      return null;
+    }
+    const value = this.block(first.indent);
+    if (this.at < this.lines.length) {
+      throw new Unsupported();
+    }
+    return value;
+  }
+
+  /** The block node whose first line is the next one, at `indent`. */
+  private block(indent: number): unknown {
+    const line = this.lines[this.at];
+    if (line === undefined) {
+      return null;
+    }
+    if (isItem(line.text)) {
+      return this.sequence(indent);
+    }
+    if (keyEnd(line.text) >= 0) {
+      return this.mapping(indent);
+    }
+    return this.multiline(indent);
+  }
+
+  /** A scalar or a flow collection whose text runs over the next lines indented deeper than `indent`. */
+  private multiline(indent: number): unknown {
+    const parts: string[] = [];
+    for (
+      let line = this.lines[this.at];
+      line !== undefined && (parts.length === 0 || line.indent > indent);
+      line = this.lines[this.at]
+    ) {
+      parts.push(line.text);
+      this.at += 1;
+    }
+    return flowValue(parts.join(" "));
+  }
+
+  /** The value after a key or an item marker: inline text, else the deeper block below it. */
+  private valueAfter(inline: string, indent: number, sequenceAtIndent: boolean): unknown {
+    if (inline !== "") {
+      const parts = [inline];
+      // A flow collection's closing bracket may stand at the key's own column.
+      for (
+        let line = this.lines[this.at];
+        line !== undefined && (line.indent > indent || openCollections(parts.join(" ")) > 0);
+        line = this.lines[this.at]
+      ) {
+        parts.push(line.text);
+        this.at += 1;
+      }
+      return flowValue(parts.join(" "));
+    }
+    const next = this.lines[this.at];
+    if (next === undefined) {
+      return null;
+    }
+    if (next.indent > indent || (sequenceAtIndent && next.indent === indent && isItem(next.text))) {
+      return this.block(next.indent);
+    }
+    return null;
+  }
+
+  private mapping(indent: number): Record<string, unknown> {
+    const object: Record<string, unknown> = {};
+    for (let line = this.lines[this.at]; line?.indent === indent; line = this.lines[this.at]) {
+      const end = keyEnd(line.text);
+      if (end < 0) {
+        throw new Unsupported();
+      }
+      const key = scalar(line.text.slice(0, end));
+      if (typeof key === "object" && key !== null) {
+        throw new Unsupported();
+      }
+      this.at += 1;
+      object[String(key)] = this.valueAfter(line.text.slice(end + 1).trim(), indent, true);
+    }
+    const left = this.lines[this.at];
+    if (left !== undefined && left.indent > indent) {
+      throw new Unsupported();
+    }
+    return object;
+  }
+
+  private sequence(indent: number): unknown[] {
+    const items: unknown[] = [];
+    for (
+      let line = this.lines[this.at];
+      line?.indent === indent && isItem(line.text);
+      line = this.lines[this.at]
+    ) {
+      const content = line.text.slice(1);
+      const inline = content.trimStart();
+      if (inline !== "" && (isItem(inline) || keyEnd(inline) >= 0)) {
+        // A node on the item's own line continues at its own column: read it as a block there.
+        const moved = { indent: indent + 1 + content.length - inline.length, text: inline };
+        this.lines[this.at] = moved;
+        items.push(this.block(moved.indent));
+      } else {
+        this.at += 1;
+        items.push(this.valueAfter(inline, indent, false));
+      }
+    }
+    const left = this.lines[this.at];
+    if (left !== undefined && left.indent > indent) {
+      throw new Unsupported();
+    }
+    return items;
+  }
+}
+
+/** The JSON value one YAML document's text denotes, or undefined where it lies outside the subset. */
+export function yamlDocument(text: string): unknown {
+  const lines: Line[] = [];
+  for (const raw of text.replace(/^\uFEFF/u, "").split(/\r?\n/u)) {
+    if (/^ *\t/u.test(raw)) {
+      return undefined;
+    }
+    const content = withoutComment(raw).trimEnd();
+    const trimmed = content.trimStart();
+    if (trimmed === "") {
+      continue;
+    }
+    if (trimmed === "---" && lines.length === 0) {
+      continue;
+    }
+    if (trimmed.startsWith("%") || trimmed === "---" || trimmed === "...") {
+      return undefined;
+    }
+    lines.push({ indent: content.length - trimmed.length, text: trimmed });
+  }
+  try {
+    return new Reader(lines).document();
+  } catch (error) {
+    if (error instanceof Unsupported) {
+      return undefined;
+    }
+    throw error;
+  }
+}
+
+/** What one top-level key of a YAML document holds, read by {@link yamlKey}. */
+type YamlKey =
+  | { readonly kind: "value"; readonly value: unknown }
+  | { readonly kind: "absent" }
+  | { readonly kind: "refused"; readonly reason: string };
+
+/** The key one line of the document's top-level mapping opens, or undefined where it opens none. */
+function topLevelKey(raw: string): string | undefined {
+  const content = withoutComment(raw).trimEnd();
+  const end = /^\s/u.test(content) ? -1 : keyEnd(content);
+  if (end < 0) {
+    return undefined;
+  }
+  try {
+    const key = scalar(content.slice(0, end));
+    return typeof key === "object" && key !== null ? undefined : String(key);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The value of one key of a document's top-level block mapping, read from that key's lines
+ * alone, so a document whose other keys lie outside the subset still yields it. A key
+ * declared twice, or one whose own lines lie outside the subset, is refused.
+ */
+export function yamlKey(text: string, key: string): YamlKey {
+  const lines = text.replace(/^\uFEFF/u, "").split(/\r?\n/u);
+  const starts = lines.flatMap((line, at) => (topLevelKey(line) === undefined ? [] : [at]));
+  const named = starts.filter((at) => topLevelKey(lines[at] ?? "") === key);
+  const [start] = named;
+  if (start === undefined) {
+    return { kind: "absent" };
+  }
+  if (named.length > 1) {
+    return { kind: "refused", reason: `the ${key} key is declared more than once` };
+  }
+  const end = starts.find((at) => at > start) ?? lines.length;
+  const value = yamlDocument(lines.slice(start, end).join("\n"));
+  return isRecord(value)
+    ? { kind: "value", value: value[key] }
+    : { kind: "refused", reason: `the value of ${key} is outside the YAML subset read here` };
+}