@platforma-sdk/block-tools 2.10.14 → 2.10.15

package/src/structure/engine/fs/memory.ts

@@ -0,0 +1,132 @@
+// In-memory FS implementation. Files are stored as a flat
+// `Map<path, string>`; directories exist implicitly when any contained
+// file exists. Used by tests, by `simulateInit`, and by the runner's
+// post-run recheck dry-run pass.
+
+import type { DirEntry, FileSystem } from "./api";
+
+function normalise(p: string): string {
+  // Collapse repeated slashes, strip leading "./" and trailing "/".
+  let out = p.replace(/\/{2,}/g, "/");
+  if (out.startsWith("./")) out = out.slice(2);
+  if (out.length > 1 && out.endsWith("/")) out = out.slice(0, -1);
+  return out;
+}
+
+export class MemoryFileSystem implements FileSystem {
+  private files = new Map<string, string | Uint8Array>();
+
+  constructor(initial?: Record<string, string>) {
+    if (initial) {
+      for (const [k, v] of Object.entries(initial)) {
+        this.files.set(normalise(k), v);
+      }
+    }
+  }
+
+  /** Snapshot of all files — handy for assertions. Binary entries are
+   *  rendered as a placeholder so the snapshot stays a string map. */
+  snapshot(): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const [k, v] of [...this.files.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+      out[k] = typeof v === "string" ? v : `<binary:${v.byteLength} bytes>`;
+    }
+    return out;
+  }
+
+  read(path: string): string {
+    const n = normalise(path);
+    const v = this.files.get(n);
+    if (v === undefined) throw new Error(`ENOENT: ${path}`);
+    if (typeof v !== "string") throw new Error(`read: ${path} is a binary file`);
+    return v;
+  }
+
+  write(path: string, content: string): void {
+    this.files.set(normalise(path), content);
+  }
+
+  writeBinary(path: string, content: Uint8Array): void {
+    this.files.set(normalise(path), content);
+  }
+
+  exists(path: string): boolean {
+    const n = normalise(path);
+    if (this.files.has(n)) return true;
+    // Directory if any file is under `n/`.
+    const prefix = n.endsWith("/") ? n : `${n}/`;
+    for (const k of this.files.keys()) {
+      if (k.startsWith(prefix)) return true;
+    }
+    return false;
+  }
+
+  list(dir: string): string[] {
+    const n = normalise(dir);
+    const prefix = n === "" ? "" : `${n}/`;
+    const out: string[] = [];
+    for (const k of this.files.keys()) {
+      if (n === "" || k.startsWith(prefix)) out.push(k);
+    }
+    return out.sort();
+  }
+
+  listDir(dir: string): DirEntry[] {
+    const n = normalise(dir);
+    const prefix = n === "" ? "" : `${n}/`;
+    // Map immediate child name → isDirectory (a child is a directory if
+    // the remainder after the first segment still contains a "/").
+    const children = new Map<string, boolean>();
+    for (const k of this.files.keys()) {
+      if (n !== "" && !k.startsWith(prefix)) continue;
+      const rest = n === "" ? k : k.slice(prefix.length);
+      if (rest === "") continue;
+      const slash = rest.indexOf("/");
+      if (slash < 0) {
+        children.set(rest, children.get(rest) ?? false);
+      } else {
+        children.set(rest.slice(0, slash), true);
+      }
+    }
+    return [...children.entries()]
+      .map(([name, isDirectory]) => ({ name, isDirectory }))
+      .sort((a, b) => a.name.localeCompare(b.name));
+  }
+
+  move(from: string, to: string): void {
+    const fromN = normalise(from);
+    const toN = normalise(to);
+    const fromPrefix = `${fromN}/`;
+    const toPrefix = `${toN}/`;
+    const moved: Array<[string, string]> = [];
+    if (this.files.has(fromN)) {
+      moved.push([fromN, toN]);
+    }
+    for (const k of this.files.keys()) {
+      if (k.startsWith(fromPrefix)) {
+        moved.push([k, toPrefix + k.slice(fromPrefix.length)]);
+      }
+    }
+    if (moved.length === 0) {
+      throw new Error(`move: source missing: ${from}`);
+    }
+    if (this.exists(to)) {
+      throw new Error(`move: dest exists: ${to}`);
+    }
+    for (const [src, dst] of moved) {
+      this.files.set(dst, this.files.get(src)!);
+      this.files.delete(src);
+    }
+  }
+
+  delete(path: string): void {
+    const n = normalise(path);
+    const prefix = `${n}/`;
+    this.files.delete(n);
+    const toDelete: string[] = [];
+    for (const k of this.files.keys()) {
+      if (k.startsWith(prefix)) toDelete.push(k);
+    }
+    for (const k of toDelete) this.files.delete(k);
+  }
+}

package/src/structure/engine/fs/node.ts

@@ -0,0 +1,89 @@
+// node:fs-backed implementation (synchronous). Anchored at a configured
+// `root`. All FileSystem methods take block-relative paths; this wrapper
+// joins them against root before touching disk.
+
+import fs from "node:fs";
+import path from "node:path";
+import type { DirEntry, FileSystem } from "./api";
+
+export class NodeFileSystem implements FileSystem {
+  constructor(private root: string) {}
+
+  private abs(p: string): string {
+    return path.resolve(this.root, p);
+  }
+
+  read(p: string): string {
+    return fs.readFileSync(this.abs(p), "utf-8");
+  }
+
+  write(p: string, content: string): void {
+    const a = this.abs(p);
+    fs.mkdirSync(path.dirname(a), { recursive: true });
+    fs.writeFileSync(a, content, "utf-8");
+  }
+
+  writeBinary(p: string, content: Uint8Array): void {
+    const a = this.abs(p);
+    fs.mkdirSync(path.dirname(a), { recursive: true });
+    fs.writeFileSync(a, content);
+  }
+
+  exists(p: string): boolean {
+    try {
+      fs.statSync(this.abs(p));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  list(dir: string): string[] {
+    const a = this.abs(dir);
+    try {
+      const stat = fs.statSync(a);
+      if (!stat.isDirectory()) return [];
+    } catch {
+      return [];
+    }
+    const out: string[] = [];
+    function walk(rel: string, absDir: string): void {
+      const entries = fs.readdirSync(absDir, { withFileTypes: true });
+      for (const e of entries) {
+        const childRel = rel ? `${rel}/${e.name}` : e.name;
+        const childAbs = path.join(absDir, e.name);
+        if (e.isDirectory()) {
+          walk(childRel, childAbs);
+        } else if (e.isFile()) {
+          out.push(childRel);
+        }
+      }
+    }
+    walk(dir === "" || dir === "." ? "" : dir, a);
+    return out.sort();
+  }
+
+  listDir(dir: string): DirEntry[] {
+    const a = this.abs(dir);
+    let entries;
+    try {
+      entries = fs.readdirSync(a, { withFileTypes: true });
+    } catch {
+      return [];
+    }
+    return entries
+      .map((e) => ({ name: e.name, isDirectory: e.isDirectory() }))
+      .sort((x, y) => x.name.localeCompare(y.name));
+  }
+
+  move(from: string, to: string): void {
+    const fromA = this.abs(from);
+    const toA = this.abs(to);
+    fs.mkdirSync(path.dirname(toA), { recursive: true });
+    fs.renameSync(fromA, toA);
+  }
+
+  delete(p: string): void {
+    fs.rmSync(this.abs(p), { recursive: true, force: true });
+  }
+}

package/src/structure/engine/glob.ts

@@ -0,0 +1,42 @@
+// Minimal glob matcher for the structurer's file-existence triggers.
+//
+// Supports `**` (any number of path segments, including none), `*` (any
+// run of chars except `/`), and `?` (a single non-`/` char); every other
+// character is matched literally. No brace expansion / char classes — the
+// patterns we match are deliberately simple (e.g. `src/**/*.test.ts`).
+// Paths are matched whole (anchored at both ends).
+
+const REGEXP_SPECIALS = /[.+^${}()|[\]\\]/g;
+
+/** Compile a glob to an anchored RegExp. */
+export function globToRegExp(glob: string): RegExp {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]!;
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        // `**`: any path segments. Absorb a following `/` so `**/x` also
+        // matches `x` at depth 0 (zero segments).
+        i++;
+        if (glob[i + 1] === "/") {
+          i++;
+          re += "(?:.*/)?";
+        } else {
+          re += ".*";
+        }
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") {
+      re += "[^/]";
+    } else {
+      re += c.replace(REGEXP_SPECIALS, "\\$&");
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/** True if `path` matches `glob` (whole-path, anchored). */
+export function matchesGlob(glob: string, path: string): boolean {
+  return globToRegExp(glob).test(path);
+}

package/src/structure/engine/ir.ts

@@ -0,0 +1,149 @@
+// Tree IR for the structurer engine.
+//
+// `defineStructure(fn)` invokes module-global builders that append to a
+// tree of group frames (`scope` / `when` / mode frames) and leaf
+// primitives (file / folder actions). `flatten` walks this tree to a
+// flat ordered list of `FlatItem`s — each with concrete scope, bound
+// module path, composed trigger, resolved filesystem path, and the set
+// of run modes the leaf fires in.
+
+import type { Scope, RunContext } from "./api";
+
+/** The three leaf-firing modes. `check` and `refresh` share the
+ *  `"default"` mode — they run the same leaves, the `dryRun` flag (carried
+ *  separately on `RunContext`) only decides whether writes happen.
+ *  `"updateDeps"` is `--update-deps-only`; `"init"` is the init
+ *  constructor. A leaf declares which modes it fires in via its enclosing
+ *  mode frame (see `ModeFrame`); the runner derives the current mode from
+ *  the run context and keeps only the leaves whose membership includes it. */
+export type RunMode = "default" | "updateDeps" | "init";
+
+/** Predicate evaluated against derived trigger context. */
+export type TriggerContext = {
+  ctx: RunContext;
+  version: number;
+  /** Block-relative path queries against the post-structural FS snapshot. */
+  pathExists(path: string): boolean;
+  pathMissing(path: string): boolean;
+  /** True if any file in the snapshot matches `glob`, resolved
+   *  MODULE-RELATIVE to the leaf's bound module: a co-located-test glob
+   *  inside `scope("model")` is checked under the `model/` dir. At the
+   *  block root the glob is block-relative. Unlike `pathExists`/`pathMissing`
+   *  (block-relative), `filesMatch` is the module-aware predicate used by
+   *  `whenFilesExist`. */
+  filesMatch(glob: string): boolean;
+};
+
+export type TriggerFn = (tctx: TriggerContext) => boolean;
+
+/** Content forms — what to write into a file when creating it.
+ *  `tpl.vars` may be a record or a thunk returning a record; the latter
+ *  lets rule authors call `blockVars()` lazily at resolve time. */
+export type TplVarsLike = Record<string, string> | (() => Record<string, string>);
+export type ContentForm =
+  | { kind: "file"; path: string }
+  | { kind: "text"; value: string }
+  | { kind: "tpl"; path: string; vars: TplVarsLike }
+  | { kind: "generate"; fn: () => unknown }
+  // A binary static asset (e.g. a logo PNG) copied verbatim from the
+  // template tree. Carried as raw bytes, never decoded to a string —
+  // only `seed` / `scaffold` consume it (via fs.writeBinary).
+  | { kind: "binary"; path: string };
+
+/** Builder-body for a `managed` file (the content-rules lambda). */
+export type ManagedBody = () => void;
+
+// --- Leaf primitives ---
+
+export type FixedItem = {
+  kind: "fixed";
+  path: string;
+  content: ContentForm;
+};
+
+export type ManagedItem = {
+  kind: "managed";
+  path: string;
+  initial: ContentForm;
+  body: ManagedBody;
+};
+
+export type ScaffoldItem = {
+  kind: "scaffold";
+  path: string;
+  initial: ContentForm;
+};
+
+export type SeedItem = {
+  kind: "seed";
+  path: string;
+  initial: ContentForm;
+};
+
+export type RemoveItem = {
+  kind: "remove";
+  path: string;
+};
+
+export type RenameItem = {
+  kind: "rename";
+  from: string;
+  to: string;
+};
+
+export type LeafItem = FixedItem | ManagedItem | ScaffoldItem | SeedItem | RemoveItem | RenameItem;
+
+// --- Group frames ---
+
+export type ScopeFrame = {
+  kind: "scope";
+  scope: Scope;
+  children: TreeNode[];
+};
+
+export type WhenFrame = {
+  kind: "when";
+  trigger: TriggerFn;
+  children: TreeNode[];
+};
+
+/** Top-level mode frame: contained leaves fire only in the listed run
+ *  modes. Leaves outside any mode frame fire in `["default", "init"]`
+ *  (refresh/check + init). `onUpdateDeps()` produces `["updateDeps"]`;
+ *  `onInitOrUpdate()` produces `["init", "updateDeps"]`. */
+export type ModeFrame = {
+  kind: "mode";
+  modes: RunMode[];
+  children: TreeNode[];
+};
+
+export type TreeNode = LeafItem | ScopeFrame | WhenFrame | ModeFrame;
+
+/** Structure object returned by `defineStructure`. */
+export type Structure = {
+  /** Top-level children — may contain leaves, scope frames, when
+   *  frames, and mode frames. */
+  children: TreeNode[];
+};
+
+// --- Post-flatten ---
+
+/**
+ * After fan-out: one entry per (leaf × matching module). `scope` is
+ * always set; `modulePath` is the workspace path the leaf is bound to
+ * (empty string for the workspace root). `triggers` is the AND of all
+ * enclosing `when` predicates. `modes` is the set of run modes the leaf
+ * fires in — `["default", "init"]` outside any mode frame, otherwise the
+ * enclosing mode frame's `modes`.
+ */
+export type FlatItem = {
+  leaf: LeafItem;
+  scope: Scope;
+  modulePath: string;
+  /** Block-relative resolved path(s). */
+  resolvedPath: string;
+  /** For rename, the resolved destination. */
+  resolvedTo?: string;
+  triggers: TriggerFn[];
+  modes: RunMode[];
+};

package/src/structure/engine/parsers/json.ts

@@ -0,0 +1,212 @@
+// JSON parser + serialiser + jsonPath helpers + top-level key reorder.
+//
+// `parseJson`/`stringifyJson` are the canonical round-trip primitives the
+// managed pass uses. The dot-notation helpers (`getAtPath`, `setAtPath`,
+// `hasAtPath`, `deleteAtPath`) back the content-rule builders. `reorderTopLevel`
+// implements the "known keys in declared order, unknown keys stay adjacent to
+// preceding known key" projection.
+
+export type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+
+export type JsonObject = { [k: string]: unknown };
+
+/** Parse JSON; throws on invalid input. */
+export function parseJson(raw: string): unknown {
+  return JSON.parse(raw);
+}
+
+// oxfmt formats JSON two ways, keyed on filename:
+//   - package.json: every array/object fully expanded, one element per line,
+//     regardless of width (what `JSON.stringify(…, 2)` already produces).
+//   - any other .json (e.g. tsconfig.json): oxfmt's generic shape —
+//       * objects: always expanded, one property per line (oxfmt preserves
+//         the brace newline, so the expanded form is a fixpoint);
+//       * arrays: collapsed onto one line when that line — its indent, the
+//         `"key": ` prefix, the flat array, and a trailing comma if a sibling
+//         follows — fits `PRINT_WIDTH` (oxfmt's default 100), else broken one
+//         element per line.
+//     This is exactly the form `oxfmt` itself produces, verified against
+//     oxfmt 0.35 at the array boundary (≤100 collapses, 101 breaks; a
+//     trailing comma counts) and across all in-mono blocks. The single-
+//     element `include` array was the regression: `JSON.stringify` expanded
+//     it while oxfmt collapses it.
+// `stringifyJson` defaults to the expanded form; callers serialising a
+// generic .json pass `{ collapse: true }` so the output is oxfmt-clean by
+// construction (no prior `pnpm fmt` needed for `check` — the same
+// emit-clean-by-design contract as the canonical key/dependency ordering).
+const PRINT_WIDTH = 100;
+const INDENT = 2;
+
+/** One-line rendering of an array, matching oxfmt's flat spacing: `[a, b]`
+ *  (no inner padding), nested objects inline as `{ "k": v }`, empty `[]`.
+ *  Only arrays collapse, so this is the array-fits primitive. */
+function flatArray(value: unknown[]): string {
+  if (value.length === 0) return "[]";
+  return "[" + value.map(flatValue).join(", ") + "]";
+}
+
+/** One-line rendering of any value (used inside a collapsed array, where
+ *  contained objects render inline). */
+function flatValue(value: unknown): string {
+  if (Array.isArray(value)) return flatArray(value);
+  if (isObject(value)) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+    return (
+      "{ " + entries.map(([k, v]) => `${JSON.stringify(k)}: ${flatValue(v)}`).join(", ") + " }"
+    );
+  }
+  return JSON.stringify(value);
+}
+
+/** Print `value` starting at `column`. Objects always break (one property per
+ *  line); arrays collapse when their flat line — `column` + the flat array +
+ *  `reserved` (1 for a trailing comma when a sibling follows) — fits
+ *  `PRINT_WIDTH`, else break. `indent` is the leading-space width of the line
+ *  the container opens on. */
+function printValue(value: unknown, indent: number, column: number, reserved: number): string {
+  const inner = indent + INDENT;
+  const pad = " ".repeat(inner);
+  if (Array.isArray(value)) {
+    const flat = flatArray(value);
+    if (column + flat.length + reserved <= PRINT_WIDTH) return flat;
+    const last = value.length - 1;
+    const lines = value.map((item, i) => pad + printValue(item, inner, inner, i === last ? 0 : 1));
+    return "[\n" + lines.join(",\n") + "\n" + " ".repeat(indent) + "]";
+  }
+  if (isObject(value)) {
+    const entries = Object.entries(value);
+    if (entries.length === 0) return "{}";
+    const last = entries.length - 1;
+    const lines = entries.map(([k, v], i) => {
+      const prefix = `${pad}${JSON.stringify(k)}: `;
+      return prefix + printValue(v, inner, prefix.length, i === last ? 0 : 1);
+    });
+    return "{\n" + lines.join(",\n") + "\n" + " ".repeat(indent) + "}";
+  }
+  return JSON.stringify(value);
+}
+
+/** Canonical serialiser: 2-space indent, trailing newline.
+ *  Default — every container expanded (the package.json shape, byte-identical
+ *  to `JSON.stringify(…, 2)`).
+ *  `{ collapse: true }` — oxfmt's generic-.json shape: containers that fit
+ *  `PRINT_WIDTH` collapse onto one line. Used for tsconfig.json and any other
+ *  non-package.json the engine emits, so `oxfmt --check` passes without a
+ *  prior format pass. */
+export function stringifyJson(value: unknown, opts?: { collapse?: boolean }): string {
+  if (!opts?.collapse) return JSON.stringify(value, null, 2) + "\n";
+  // Normalise through a round-trip so non-JSON inputs (undefined values,
+  // functions) are dropped exactly as `JSON.stringify` would.
+  const normalized = JSON.parse(JSON.stringify(value ?? null));
+  return printValue(normalized, 0, 0, 0) + "\n";
+}
+
+function splitPath(jsonPath: string): string[] {
+  if (jsonPath === "" || jsonPath === undefined) return [];
+  return jsonPath.split(".");
+}
+
+function isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Get the value at `jsonPath`. Returns `undefined` if any segment is
+ *  missing or not an object. */
+export function getAtPath(obj: JsonObject, jsonPath: string): unknown {
+  const parts = splitPath(jsonPath);
+  let cur: unknown = obj;
+  for (const p of parts) {
+    if (!isObject(cur)) return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+/** True if `jsonPath` resolves to a defined value (including `null`). */
+export function hasAtPath(obj: JsonObject, jsonPath: string): boolean {
+  const parts = splitPath(jsonPath);
+  if (parts.length === 0) return true;
+  let cur: unknown = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (!isObject(cur)) return false;
+    cur = cur[parts[i]!];
+  }
+  if (!isObject(cur)) return false;
+  return parts[parts.length - 1]! in cur;
+}
+
+/** Set `value` at `jsonPath`. Auto-creates intermediate objects. Throws
+ *  if a non-object value is on the path (would be silently overwritten
+ *  otherwise — caller bug). */
+export function setAtPath(obj: JsonObject, jsonPath: string, value: unknown): void {
+  const parts = splitPath(jsonPath);
+  if (parts.length === 0) {
+    throw new Error("setAtPath: jsonPath must be non-empty");
+  }
+  let cur: JsonObject = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const k = parts[i]!;
+    const next = cur[k];
+    if (next === undefined) {
+      const fresh: JsonObject = {};
+      cur[k] = fresh;
+      cur = fresh;
+    } else if (isObject(next)) {
+      cur = next;
+    } else {
+      throw new Error(
+        `setAtPath: cannot descend into non-object at '${parts.slice(0, i + 1).join(".")}'`,
+      );
+    }
+  }
+  cur[parts[parts.length - 1]!] = value;
+}
+
+/** Delete the value at `jsonPath`. No-op if any segment is missing. */
+export function deleteAtPath(obj: JsonObject, jsonPath: string): void {
+  const parts = splitPath(jsonPath);
+  if (parts.length === 0) {
+    throw new Error("deleteAtPath: jsonPath must be non-empty");
+  }
+  let cur: unknown = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (!isObject(cur)) return;
+    cur = cur[parts[i]!];
+  }
+  if (!isObject(cur)) return;
+  delete cur[parts[parts.length - 1]!];
+}
+
+/**
+ * Reorder top-level keys of `obj`:
+ *  - Known keys (those listed in `order`) appear in declared order.
+ *  - Unknown keys (not in `order`) stay adjacent to the preceding known
+ *    key they followed in the source. Unknown keys appearing before any
+ *    known key go first, in source order.
+ */
+export function reorderTopLevel(obj: JsonObject, order: readonly string[]): JsonObject {
+  const known = new Set(order);
+  const sourceKeys = Object.keys(obj);
+
+  const adjacents = new Map<string, string[]>();
+  adjacents.set("", []);
+  let anchor = "";
+  for (const k of sourceKeys) {
+    if (known.has(k)) {
+      anchor = k;
+      adjacents.set(anchor, []);
+    } else {
+      adjacents.get(anchor)!.push(k);
+    }
+  }
+
+  const out: JsonObject = {};
+  for (const k of adjacents.get("")!) out[k] = obj[k];
+  for (const k of order) {
+    if (!(k in obj)) continue;
+    out[k] = obj[k];
+    for (const u of adjacents.get(k) ?? []) out[u] = obj[u];
+  }
+  return out;
+}

package/src/structure/engine/parsers/lines.ts

@@ -0,0 +1,42 @@
+// .gitignore-style line list parser/serialiser.
+//
+// `parseLines` keeps the file verbatim as an array of lines (one per
+// "\n"). `serializeLines` joins them with "\n" and guarantees a trailing
+// newline. `normaliseLine` strips comments and surrounding whitespace —
+// used by the `ensureGitignoreEntries` family to compare an existing
+// line to a required entry without being fooled by inline `#` comments
+// or extra indentation.
+
+export function parseLines(raw: string): string[] {
+  // Drop the synthetic empty entry caused by a trailing newline so a
+  // serialise-then-parse round-trip is stable.
+  const lines = raw.split("\n");
+  if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+
+export function serializeLines(lines: readonly string[]): string {
+  return lines.join("\n") + "\n";
+}
+
+/** Strip leading/trailing whitespace and trailing inline `# ...` comments.
+ *  Returns empty string for blank / comment-only lines. */
+export function normaliseLine(line: string): string {
+  const noComment = line.replace(/(^|\s)#.*$/, "$1");
+  return noComment.trim();
+}
+
+/** True if `line` (after normalisation) equals `entry` (after trim). */
+export function lineEqualsEntry(line: string, entry: string): boolean {
+  const n = normaliseLine(line);
+  if (n === "") return false;
+  return n === entry.trim();
+}
+
+/** True if any line in `lines` normalises to `entry`. */
+export function containsEntry(lines: readonly string[], entry: string): boolean {
+  for (const line of lines) {
+    if (lineEqualsEntry(line, entry)) return true;
+  }
+  return false;
+}