@sous-io/sous 0.1.1 → 0.2.1

package/src/lib/vars/report.ts

@@ -0,0 +1,228 @@
+/**
+ * The two variable reports the `sous vars` commands print.
+ *
+ * They live here rather than inside a command so that `vars list`, `vars show`
+ * and the bare `sous vars` all print exactly the same thing: the listing is one
+ * function and the detail is another, and each command only decides which one
+ * to call.
+ */
+
+import path from "node:path";
+import { ConfigError } from "../errors.js";
+import {
+  definedVariableKey,
+  definingRecipeKey,
+  type DefinedVariable,
+} from "./definition-source.js";
+import {
+  displayValue,
+  documentationRows,
+  renderFacts,
+  variableFacts,
+} from "./display.js";
+import { renderTable, type TableColumn } from "../../utils/table.js";
+import {
+  diagnoseVariable,
+  RUNG_LABELS,
+  SOURCE_LABELS,
+  type LadderContext,
+} from "./ladder.js";
+import { validateAnswer } from "./validate.js";
+import { answerFileFor } from "./ask.js";
+import { bareName } from "./names.js";
+import {
+  blankLine,
+  heading,
+  indent,
+  log,
+  paragraph,
+  showVariables,
+  subheading,
+  terminalColumns,
+} from "../../utils/formatting.js";
+
+/** How far every line of these reports is indented. */
+const INDENT = 2;
+
+/**
+ * The columns the listing shows. The variable and the value answering it are
+ * what the reader came for, so they stay however narrow the terminal is. An
+ * environment variable name is cut at the front, because the tail of
+ * `SOUS_VAR_LOCAL_QUESTIONS_API_URL` is the part that identifies it.
+ */
+const LIST_COLUMNS: TableColumn[] = [
+  { key: "name", header: "Variable", overflow: "truncate", minWidth: 8 },
+  {
+    key: "recipe",
+    header: "Recipe",
+    kind: "path",
+    overflow: "truncate",
+    priority: "medium",
+    minWidth: 8,
+  },
+  {
+    key: "envName",
+    header: "Answered by",
+    overflow: "truncate",
+    truncate: "start",
+    priority: "medium",
+    minWidth: 11,
+  },
+  {
+    key: "value",
+    header: "Value",
+    overflow: "truncate",
+    truncate: "end",
+    flex: 1,
+    minWidth: 10,
+  },
+  { key: "source", header: "Source", priority: "low" },
+];
+
+/** The columns the detail report's resolution ladder shows. */
+const LADDER_COLUMNS: TableColumn[] = [
+  { key: "envName", header: "Environment variable", overflow: "truncate", truncate: "start" },
+  { key: "rung", header: "Rung", priority: "medium" },
+  { key: "status", header: "Status", flex: 1, priority: "medium" },
+];
+
+/**
+ * Prints the table of every variable in play, sorted by recipe then name.
+ *
+ * @param defined - Every variable the project's recipes (or a file) define.
+ * @param context - The resolution ladder to read answers from.
+ */
+export function printVariableList(
+  defined: DefinedVariable[],
+  context: LadderContext
+): void {
+  heading("Variables in play");
+
+  if (defined.length === 0) {
+    blankLine();
+    paragraph(
+      "No recipe in this project defines any variables yet. Subscribe to a recipe " +
+        "that publishes some, or read a definitions file with --file."
+    );
+    return;
+  }
+
+  const rows = [...defined]
+    .sort((left, right) => definedVariableKey(left).localeCompare(definedVariableKey(right)))
+    .map((entry) => {
+      const { resolved } = diagnoseVariable(entry, context);
+      const value = displayValue(resolved?.value, entry.definition.secret);
+      const source =
+        resolved === undefined
+          ? "nothing yet"
+          : `${RUNG_LABELS[resolved.source.rung]}, ${
+              SOURCE_LABELS[resolved.source.file] ?? resolved.source.file
+            }`;
+      return {
+        name: entry.definition.name,
+        recipe: definingRecipeKey(entry.recipe),
+        envName: resolved?.source.envName ?? "",
+        value,
+        source,
+      };
+    });
+
+  blankLine();
+  for (const line of renderTable(LIST_COLUMNS, rows, { indent: INDENT })) {
+    log(indent(line, INDENT));
+  }
+}
+
+/** What the detail report needs beyond the definitions themselves. */
+export interface VariableDetailOptions {
+  /**
+   * The project's `.sous/` directory, so the storage path can be shown in full.
+   * Without it only the env file's name is shown.
+   */
+  sousDir?: string;
+}
+
+/**
+ * Prints everything about one variable: the question, the documentation, the
+ * labeled facts (the same block the advanced view of a question prints, from
+ * the same renderer), every environment variable name on its resolution ladder,
+ * and which rung actually answered.
+ *
+ * @param defined - Every variable the project's recipes (or a file) define.
+ * @param context - The resolution ladder to read answers from.
+ * @param name - The variable's name, or its `namespace/recipe.name` key.
+ * @param options - Where the project's `.sous/` directory is.
+ */
+export function printVariableDetail(
+  defined: DefinedVariable[],
+  context: LadderContext,
+  name: string,
+  options: VariableDetailOptions = {}
+): void {
+  const matches = defined.filter(
+    (entry) => entry.definition.name === name || definedVariableKey(entry) === name
+  );
+
+  if (matches.length === 0) {
+    throw new ConfigError(
+      `No variable named '${name}' is in play.\n` +
+        `  Run 'sous vars list' to see every variable this project's recipes define.`
+    );
+  }
+
+  for (const entry of matches) {
+    const { definition } = entry;
+    const { resolved, candidates } = diagnoseVariable(entry, context);
+    const validity =
+      resolved === undefined
+        ? undefined
+        : validateAnswer(definition, resolved.value, {
+            recipe: definingRecipeKey(entry.recipe),
+          });
+
+    const file = answerFileFor(definition);
+
+    heading(`${definition.name} (${definingRecipeKey(entry.recipe)})`);
+    blankLine();
+    showVariables({
+      Question: definition.prompt,
+      ...documentationRows(definition),
+      Recipe: `${definingRecipeKey(entry.recipe)} version ${entry.recipe.version} from ${entry.recipe.repo}`,
+      "Stored in": file,
+      Value: displayValue(resolved?.value, definition.secret),
+      Answer:
+        resolved === undefined
+          ? "nothing in scope answers this variable yet"
+          : validity?.ok === true
+            ? "the value in scope fits this definition"
+            : `the value in scope does not fit: ${validity?.ok === false ? validity.message : ""}`,
+    });
+
+    blankLine();
+    const facts = variableFacts({
+      defined: entry,
+      storagePath:
+        options.sousDir === undefined ? file : path.join(options.sousDir, file),
+      storedAs: resolved?.source.envName ?? bareName(definition),
+    });
+    // renderFacts indents the block itself, so every facts block in the CLI
+    // sits at the same depth.
+    for (const line of renderFacts(facts, terminalColumns())) log(line);
+
+    blankLine();
+    subheading("Environment variables sous looks at, most specific first");
+    blankLine();
+
+    const rows = candidates.map((candidate) => ({
+      envName: candidate.envName,
+      rung: RUNG_LABELS[candidate.rung],
+      status:
+        candidate.envName === resolved?.source.envName
+          ? `answered it, from ${SOURCE_LABELS[resolved.source.file] ?? resolved.source.file}`
+          : "not set",
+    }));
+    for (const line of renderTable(LADDER_COLUMNS, rows, { indent: INDENT })) {
+      log(indent(line, INDENT));
+    }
+  }
+}

package/src/lib/vars/safe-regex.ts

@@ -0,0 +1,235 @@
+/**
+ * Running a recipe's regular expression under a time budget.
+ *
+ * A recipe publishes `validate.pattern` as a plain string, and a consuming
+ * project runs it against whatever the person answering types. A pattern with
+ * catastrophic backtracking in it (the classic `(a+)+$`) can take effectively
+ * forever on a short input, which would hang `sous subscription add` or
+ * `sous vars ask` with no way out. So sous never runs a published pattern on
+ * its own thread: the match happens inside a worker, and the caller waits only
+ * for a fixed budget before giving up on it.
+ *
+ * The API is SYNCHRONOUS because every caller of `validateAnswer` is
+ * synchronous, and the whole variables layer would have to become async to
+ * change that. The workable synchronous shape is a worker plus a
+ * `SharedArrayBuffer`: the caller posts the work, blocks in `Atomics.wait` for
+ * at most the budget, and reads the answer the worker stored in shared memory.
+ * The worker thread keeps running while the calling thread is parked, so the
+ * result arrives without an event loop turn on this side.
+ *
+ * COMPILING a pattern is not budgeted, and does not need to be: V8 compiles a
+ * regular expression in time proportional to its source text and has no
+ * pathological compile step, so the `new RegExp(...)` validity check that
+ * `recipe-manifest.ts` runs at parse time is safe as it stands. Only the MATCH
+ * can run away.
+ */
+
+import { Worker } from "node:worker_threads";
+
+/** How long a published pattern may run before sous stops waiting for it. */
+export const DEFAULT_PATTERN_BUDGET_MS = 100;
+
+/** What running a pattern against an input produced. */
+export type MatchOutcome = "match" | "no-match" | "timeout";
+
+/** How long a worker is given to come online before it is written off. */
+const STARTUP_GRACE_MS = 5_000;
+
+/** Slot 0 of the shared array: the outcome the worker wrote. */
+const STATUS = 0;
+
+/** Slot 1 of the shared array: set once the worker has the match in hand. */
+const STARTED = 1;
+
+/** The status words the worker writes into shared memory. */
+const PENDING = 0;
+const MATCHED = 1;
+const DID_NOT_MATCH = 2;
+const FAILED = 3;
+
+/**
+ * The part of a worker this module uses. Narrow on purpose, so a test can hand
+ * in a stand-in (or refuse to make one) without constructing a real thread.
+ */
+export interface MatcherWorker {
+  /** Delivers one match request to the worker thread. */
+  postMessage(message: unknown): void;
+  /** Stops the worker, including one that is stuck inside a runaway match. */
+  terminate(): unknown;
+  /** Lets the process exit while this worker is idle. */
+  unref?(): void;
+}
+
+/**
+ * Makes the worker that runs patterns. Returning `undefined` means workers are
+ * not available here, which sends `matchWithBudget` down its in-process
+ * fallback path.
+ */
+export type MatcherWorkerFactory = () => MatcherWorker | undefined;
+
+/** The source the default worker runs. */
+const WORKER_SOURCE = `
+const { parentPort } = require("node:worker_threads");
+parentPort.on("message", (task) => {
+  const slots = new Int32Array(task.shared);
+  Atomics.store(slots, ${STARTED}, 1);
+  Atomics.notify(slots, ${STARTED});
+  let code = ${FAILED};
+  try {
+    code = new RegExp(task.pattern).test(task.input) ? ${MATCHED} : ${DID_NOT_MATCH};
+  } catch {
+    code = ${FAILED};
+  }
+  Atomics.store(slots, ${STATUS}, code);
+  Atomics.notify(slots, ${STATUS});
+});
+`;
+
+/**
+ * Starts the real worker. The source is passed inline (`eval: true`) rather
+ * than as a file so the worker needs no TypeScript loader of its own, and it is
+ * unreferenced so an idle matcher never holds the process open.
+ */
+const defaultFactory: MatcherWorkerFactory = () => {
+  const worker = new Worker(WORKER_SOURCE, { eval: true });
+  worker.unref();
+  return worker;
+};
+
+let factory: MatcherWorkerFactory = defaultFactory;
+let worker: MatcherWorker | undefined;
+let workersUnavailable = false;
+
+/**
+ * Replaces the worker factory, for tests. Pass nothing to restore the real one.
+ *
+ * @param replacement - The factory to use, or `undefined` to restore the default.
+ */
+export function setMatcherWorkerFactory(replacement?: MatcherWorkerFactory): void {
+  disposeMatcherWorker();
+  factory = replacement ?? defaultFactory;
+  workersUnavailable = false;
+}
+
+/** Stops and forgets the shared worker, if one was ever started. */
+export function disposeMatcherWorker(): void {
+  const running = worker;
+  worker = undefined;
+  if (running === undefined) return;
+  try {
+    running.terminate();
+  } catch {
+    // A worker that cannot be terminated is already gone.
+  }
+}
+
+/**
+ * Returns the shared worker, starting it on first use. One worker serves the
+ * whole process; it is started only when a pattern is actually being checked,
+ * never at import time.
+ */
+function matcher(): MatcherWorker | undefined {
+  if (workersUnavailable) return undefined;
+  if (worker !== undefined) return worker;
+  try {
+    worker = factory();
+  } catch {
+    worker = undefined;
+  }
+  if (worker === undefined) workersUnavailable = true;
+  return worker;
+}
+
+/**
+ * Tests `input` against `pattern`, giving up after `budgetMs`.
+ *
+ * @param pattern - The regular expression source a recipe published.
+ * @param input - The text to test it against.
+ * @param budgetMs - How long the pattern may run, in milliseconds.
+ * @returns Whether it matched, did not match, or ran out of time.
+ *
+ * @example
+ * matchWithBudget("^a+$", "aaa");        // -> "match"
+ * matchWithBudget("^a+$", "b");          // -> "no-match"
+ * matchWithBudget("(a+)+$", "aaaa!");    // -> "timeout", eventually
+ */
+export function matchWithBudget(
+  pattern: string,
+  input: string,
+  budgetMs: number = DEFAULT_PATTERN_BUDGET_MS
+): MatchOutcome {
+  const running = matcher();
+
+  // No worker here, so there is nothing to run the pattern on but this thread.
+  // The budget cannot be enforced in that case; a plain test is still the right
+  // answer, because refusing to validate at all would be worse than the risk.
+  if (running === undefined) return inProcessMatch(pattern, input);
+
+  const shared = new SharedArrayBuffer(2 * Int32Array.BYTES_PER_ELEMENT);
+  const slots = new Int32Array(shared);
+
+  try {
+    running.postMessage({ pattern, input, shared });
+  } catch {
+    disposeMatcherWorker();
+    return inProcessMatch(pattern, input);
+  }
+
+  // Starting a thread takes tens of milliseconds, and that time belongs to sous
+  // rather than to the pattern, so the budget does not start until the worker
+  // says it has the match in hand.
+  if (!waitForStart(slots)) {
+    // The worker never came online at all, so there is no budgeted thread to
+    // run on. This means workers are broken here, not that the pattern is slow.
+    disposeMatcherWorker();
+    workersUnavailable = true;
+    return inProcessMatch(pattern, input);
+  }
+
+  if (Atomics.load(slots, STATUS) === PENDING) {
+    Atomics.wait(slots, STATUS, PENDING, budgetMs);
+  }
+
+  switch (Atomics.load(slots, STATUS)) {
+    case MATCHED:
+      return "match";
+    case DID_NOT_MATCH:
+      return "no-match";
+    case FAILED:
+      // The worker could not compile the pattern. Compiling is cheap and safe,
+      // so repeating it here reproduces the same error for the caller.
+      return inProcessMatch(pattern, input);
+    default:
+      // Still running, and it always might be, so the worker is thrown away and
+      // the next check starts a fresh one.
+      disposeMatcherWorker();
+      return "timeout";
+  }
+}
+
+/**
+ * Blocks until the worker reports that it has started matching, or until the
+ * startup grace runs out.
+ *
+ * @param slots - The shared status slots for this request.
+ * @returns Whether the worker came online.
+ */
+function waitForStart(slots: Int32Array): boolean {
+  const deadline = Date.now() + STARTUP_GRACE_MS;
+  while (Atomics.load(slots, STARTED) === 0 && Atomics.load(slots, STATUS) === PENDING) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) return false;
+    Atomics.wait(slots, STARTED, 0, remaining);
+  }
+  return true;
+}
+
+/**
+ * The unbudgeted fallback: run the pattern right here.
+ *
+ * @param pattern - The regular expression source.
+ * @param input - The text to test it against.
+ */
+function inProcessMatch(pattern: string, input: string): MatchOutcome {
+  return new RegExp(pattern).test(input) ? "match" : "no-match";
+}