@starci/hfs 4.11.21 → 4.12.0

package/scaffold/test-world.d.mts

@@ -0,0 +1,31 @@
+/** A connection of the be side of a full declaration. */
+interface WorldConnection {
+    readonly name: string;
+    readonly envPrefix: string;
+    readonly owner?: string;
+}
+/** An app of the be side. */
+interface WorldBeApp {
+    readonly name: string;
+    readonly kind: string;
+}
+/** The part of a resolved full declaration the test world reads. */
+export interface WorldDeclaration {
+    readonly sides: {
+        readonly be: {
+            readonly apps: readonly WorldBeApp[];
+            readonly connections?: readonly WorldConnection[];
+        };
+    };
+}
+/** The file the jest preset reads to give an app its world projects; its presence means the app has a test world. */
+export declare const WORLD_MARKER = "be/src/tests/world/global-setup.ts";
+/**
+ * The test world files of the full app `app` (a resolved hfs declaration): [{ path, content }], app-relative, in a fixed order.
+ * Refused (HFS_SCAFFOLD_TEST_WORLD) when the declaration has no api app, no connection or no cli app to migrate through.
+ */
+export declare function testWorldFiles(app: WorldDeclaration): Array<{
+    path: string;
+    content: string;
+}>;
+export {};

package/scaffold/test-world.mjs

@@ -14,112 +14,105 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { TEMPLATES_DIR } from '../sync/index.mjs';
 import { ScaffoldError, camelOf, pascalOf } from './service.mjs';
-
 const TEMPLATE_DIR = path.join(TEMPLATES_DIR, 'be', 'test-world');
 const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/u;
-
 /** The file the jest preset reads to give an app its world projects; its presence means the app has a test world. */
 export const WORLD_MARKER = 'be/src/tests/world/global-setup.ts';
-
 const template = (file) => fs.readFileSync(path.join(TEMPLATE_DIR, ...file.split('/')), 'utf8').replace(/\r\n/g, '\n');
-
 /** A template with its `{{name}}` slots filled; every slot must have a value and every value must be used. */
 function fill(file, values) {
-  const used = new Set();
-  const text = template(file).replace(/\{\{([A-Za-z]+)\}\}/gu, (_, key) => {
-    if (!Object.hasOwn(values, key)) throw new ScaffoldError('HFS_SCAFFOLD_TEMPLATE_VARIABLE', `templates/be/test-world/${file} names {{${key}}}, which has no value`);
-    used.add(key);
-    return values[key];
-  });
-  const unused = Object.keys(values).filter((key) => !used.has(key));
-  if (unused.length) throw new ScaffoldError('HFS_SCAFFOLD_TEMPLATE_VARIABLE', `templates/be/test-world/${file} does not use ${unused.join(', ')}`);
-  return text;
+    const used = new Set();
+    const text = template(file).replace(/\{\{([A-Za-z]+)\}\}/gu, (_, key) => {
+        if (!Object.hasOwn(values, key))
+            throw new ScaffoldError('HFS_SCAFFOLD_TEMPLATE_VARIABLE', `templates/be/test-world/${file} names {{${key}}}, which has no value`);
+        used.add(key);
+        return values[key]; // hasOwn above
+    });
+    const unused = Object.keys(values).filter((key) => !used.has(key));
+    if (unused.length)
+        throw new ScaffoldError('HFS_SCAFFOLD_TEMPLATE_VARIABLE', `templates/be/test-world/${file} does not use ${unused.join(', ')}`);
+    return text;
 }
-
 /** `.name` for an identifier, `["name"]` otherwise: how a spec reads a record key. */
 const access = (name) => (IDENTIFIER.test(name) ? `.${name}` : `[${JSON.stringify(name)}]`);
 const constantOf = (name) => name.replace(/[^A-Za-z0-9]+/gu, '_').toUpperCase();
 const union = (names) => names.map((name) => JSON.stringify(name)).join(' | ');
 const migrationsConst = (connection) => `${constantOf(connection.name)}_APPLIED_MIGRATIONS`;
-
 /** The api apps and connections of a full declaration, refused when the world has nothing to boot or migrate. */
 function worldShape(app) {
-  const apis = app.sides.be.apps.filter((entry) => entry.kind === 'api');
-  const connections = app.sides.be.connections ?? [];
-  if (!apis.length) throw new ScaffoldError('HFS_SCAFFOLD_TEST_WORLD', 'the test world boots the api apps of hfs.json, and it declares none');
-  if (!connections.length) throw new ScaffoldError('HFS_SCAFFOLD_TEST_WORLD', 'the test world migrates the connections of hfs.json, and it declares none');
-  if (!app.sides.be.apps.some((entry) => entry.kind === 'cli' && entry.name === 'cli')) throw new ScaffoldError('HFS_SCAFFOLD_TEST_WORLD', 'the test world migrates through the cli app (be/apps/cli), and hfs.json declares none');
-  return { apis, connections };
+    const apis = app.sides.be.apps.filter((entry) => entry.kind === 'api');
+    const connections = app.sides.be.connections ?? [];
+    if (!apis.length)
+        throw new ScaffoldError('HFS_SCAFFOLD_TEST_WORLD', 'the test world boots the api apps of hfs.json, and it declares none');
+    if (!connections.length)
+        throw new ScaffoldError('HFS_SCAFFOLD_TEST_WORLD', 'the test world migrates the connections of hfs.json, and it declares none');
+    if (!app.sides.be.apps.some((entry) => entry.kind === 'cli' && entry.name === 'cli'))
+        throw new ScaffoldError('HFS_SCAFFOLD_TEST_WORLD', 'the test world migrates through the cli app (be/apps/cli), and hfs.json declares none');
+    return { apis, connections };
 }
-
 function worldConfig({ apis, connections }) {
-  return fill('world/test-world.config.ts.tpl', {
-    appModuleImports: apis.map((api) => `import { AppModule as ${pascalOf(api.name)}App } from "../../../apps/${api.name}/src/app.module"`).join('\n'),
-    optionsImports: ['cliOptionsOf', ...apis.map((api) => `${camelOf(api.name)}OptionsOf`), 'migrateCli', 'platformBase'].sort().join(', '),
-    connectionDeclarations: connections.map((connection) => `{ name: ${JSON.stringify(connection.name)} }`).join(', '),
-    worldApps: apis.map((api) => `        ${IDENTIFIER.test(api.name) ? api.name : JSON.stringify(api.name)}: { module: ${pascalOf(api.name)}App, options: ${camelOf(api.name)}OptionsOf, configure: applyCorrelation },`).join('\n'),
-  });
+    return fill('world/test-world.config.ts.tpl', {
+        appModuleImports: apis.map((api) => `import { AppModule as ${pascalOf(api.name)}App } from "../../../apps/${api.name}/src/app.module"`).join('\n'),
+        optionsImports: ['cliOptionsOf', ...apis.map((api) => `${camelOf(api.name)}OptionsOf`), 'migrateCli', 'platformBase'].sort().join(', '),
+        connectionDeclarations: connections.map((connection) => `{ name: ${JSON.stringify(connection.name)} }`).join(', '),
+        worldApps: apis.map((api) => `        ${IDENTIFIER.test(api.name) ? api.name : JSON.stringify(api.name)}: { module: ${pascalOf(api.name)}App, options: ${camelOf(api.name)}OptionsOf, configure: applyCorrelation },`).join('\n'),
+    });
 }
-
 function worldOptions({ apis, connections }) {
-  const appOptions = apis.map((api) => [
-    '',
-    `/** The ${api.name} app, read the way its \`main.ts\` reads its environment, listening on the port the run reserved for it. */`,
-    `export const ${camelOf(api.name)}OptionsOf = (w: AppWiring): ${pascalOf(api.name)}Options =>`,
-    `    read${pascalOf(api.name)}Env(environmentOf(w, { PORT: String(w.apps${access(api.name)}.port) }))`,
-    '',
-  ].join('\n')).join('');
-  return fill('world/test-apps.options.ts.tpl', {
-    appEnvImports: apis.flatMap((api) => [
-      `import { read${pascalOf(api.name)}Env } from "../../../apps/${api.name}/src/${api.name}.env"`,
-      `import type { ${pascalOf(api.name)}Options } from "../../../apps/${api.name}/src/${api.name}.options"`,
-    ]).join('\n'),
-    appsUnion: union(apis.map((api) => api.name)),
-    connectionsUnion: union(connections.map((connection) => connection.name)),
-    environmentConnections: connections.map((connection) => `        ${connection.envPrefix}_URL: w.db${access(connection.name)}.url,`).join('\n'),
-    appOptions,
-  });
+    const appOptions = apis.map((api) => [
+        '',
+        `/** The ${api.name} app, read the way its \`main.ts\` reads its environment, listening on the port the run reserved for it. */`,
+        `export const ${camelOf(api.name)}OptionsOf = (w: AppWiring): ${pascalOf(api.name)}Options =>`,
+        `    read${pascalOf(api.name)}Env(environmentOf(w, { PORT: String(w.apps${access(api.name)}.port) }))`,
+        '',
+    ].join('\n')).join('');
+    return fill('world/test-apps.options.ts.tpl', {
+        appEnvImports: apis.flatMap((api) => [
+            `import { read${pascalOf(api.name)}Env } from "../../../apps/${api.name}/src/${api.name}.env"`,
+            `import type { ${pascalOf(api.name)}Options } from "../../../apps/${api.name}/src/${api.name}.options"`,
+        ]).join('\n'),
+        appsUnion: union(apis.map((api) => api.name)),
+        connectionsUnion: union(connections.map((connection) => connection.name)),
+        environmentConnections: connections.map((connection) => `        ${connection.envPrefix}_URL: w.db${access(connection.name)}.url,`).join('\n'),
+        appOptions,
+    });
 }
-
 function migrationsFixture({ connections }) {
-  return fill('fixtures/migrations.sql.ts.tpl', {
-    migrationQueries: connections.map((connection) => [
-      '',
-      `/** The migrations the run applied to the ${connection.name} connection ($none), oldest first: the ledger the cli migrate step writes. */`,
-      `export const ${migrationsConst(connection)} = sql\`SELECT name FROM ${connection.name}_migrations ORDER BY id LIMIT 500\``,
-      '',
-    ].join('\n')).join(''),
-  });
+    return fill('fixtures/migrations.sql.ts.tpl', {
+        migrationQueries: connections.map((connection) => [
+            '',
+            `/** The migrations the run applied to the ${connection.name} connection ($none), oldest first: the ledger the cli migrate step writes. */`,
+            `export const ${migrationsConst(connection)} = sql\`SELECT name FROM ${connection.name}_migrations ORDER BY id LIMIT 500\``,
+            '',
+        ].join('\n')).join(''),
+    });
 }
-
 /** The connection an api app's e2e reads back: the one it owns, else the first declared. */
-const connectionOf = (api, connections) => connections.find((connection) => connection.owner === api.name) ?? connections[0];
-
+const connectionOf = (api, connections) => connections.find((connection) => connection.owner === api.name) ?? connections[0]; // worldShape refuses an empty list
 function e2eSpec(api, connections) {
-  const connection = connectionOf(api, connections);
-  return fill('e2e/serves-once-migrated.e2e-spec.ts.tpl', {
-    app: api.name,
-    appAccess: access(api.name),
-    connection: connection.name,
-    connectionAccess: access(connection.name),
-    migrationsConst: migrationsConst(connection),
-  });
+    const connection = connectionOf(api, connections);
+    return fill('e2e/serves-once-migrated.e2e-spec.ts.tpl', {
+        app: api.name,
+        appAccess: access(api.name),
+        connection: connection.name,
+        connectionAccess: access(connection.name),
+        migrationsConst: migrationsConst(connection),
+    });
 }
-
 /**
  * The test world files of the full app `app` (a resolved hfs declaration): [{ path, content }], app-relative, in a fixed order.
  * Refused (HFS_SCAFFOLD_TEST_WORLD) when the declaration has no api app, no connection or no cli app to migrate through.
  */
 export function testWorldFiles(app) {
-  const shape = worldShape(app);
-  return [
-    { path: 'be/src/tests/world/test-world.config.ts', content: worldConfig(shape) },
-    { path: 'be/src/tests/world/test-apps.options.ts', content: worldOptions(shape) },
-    { path: 'be/src/tests/world/use-test-world.ts', content: fill('world/use-test-world.ts.tpl', {}) },
-    { path: WORLD_MARKER, content: fill('world/global-setup.ts.tpl', {}) },
-    { path: 'be/src/tests/world/global-teardown.ts', content: fill('world/global-teardown.ts.tpl', {}) },
-    { path: 'be/src/tests/fixtures/persistence/migrations.sql.ts', content: migrationsFixture(shape) },
-    { path: 'be/src/tests/integration/readiness/readiness.integration-spec.ts', content: fill('integration/readiness.integration-spec.ts.tpl', {}) },
-    ...shape.apis.map((api) => ({ path: `be/src/tests/e2e/system-health/${api.name}-serves-once-migrated.e2e-spec.ts`, content: e2eSpec(api, shape.connections) })),
-  ];
+    const shape = worldShape(app);
+    return [
+        { path: 'be/src/tests/world/test-world.config.ts', content: worldConfig(shape) },
+        { path: 'be/src/tests/world/test-apps.options.ts', content: worldOptions(shape) },
+        { path: 'be/src/tests/world/use-test-world.ts', content: fill('world/use-test-world.ts.tpl', {}) },
+        { path: WORLD_MARKER, content: fill('world/global-setup.ts.tpl', {}) },
+        { path: 'be/src/tests/world/global-teardown.ts', content: fill('world/global-teardown.ts.tpl', {}) },
+        { path: 'be/src/tests/fixtures/persistence/migrations.sql.ts', content: migrationsFixture(shape) },
+        { path: 'be/src/tests/integration/readiness/readiness.integration-spec.ts', content: fill('integration/readiness.integration-spec.ts.tpl', {}) },
+        ...shape.apis.map((api) => ({ path: `be/src/tests/e2e/system-health/${api.name}-serves-once-migrated.e2e-spec.ts`, content: e2eSpec(api, shape.connections) })),
+    ];
 }

package/scaffold/yaml-block-edit.d.mts

@@ -0,0 +1,23 @@
+export type YamlDocument = any;
+/** A step of a path: a mapping key, or the sequence item whose `item` key is `is`. */
+export type YamlStep = string | {
+    readonly item: string;
+    readonly is: string;
+};
+/** A YAML text that adds entries under one mapping or items to one block sequence, and applies the same change to its document. */
+export declare class YamlBlockEdit {
+    readonly file: string;
+    readonly newline: string;
+    readonly lines: string[];
+    readonly document: YamlDocument;
+    readonly expected: YamlDocument;
+    constructor(text: string, file: string);
+    /** The parsed document as the edits leave it; mutate it in step with each text edit. */
+    get value(): YamlDocument;
+    /** Appends `block` (YAML lines at indent 0) as the last children of the mapping or sequence at `path`. */
+    append(path: readonly YamlStep[], block: string): this;
+    /** Adds `value` to the flow sequence (`key: [a, b]`) at `path`. */
+    extendFlow(path: readonly YamlStep[], value: string): this;
+    /** The edited text, or a refusal when it does not parse to the expected document. */
+    text(): string;
+}

package/scaffold/yaml-block-edit.mjs

@@ -4,114 +4,122 @@
 import { isDeepStrictEqual } from 'node:util';
 import { parseYaml } from '../runtime/engine/yaml.mjs';
 import { ScaffoldError } from './service.mjs';
-
 const significant = (line) => line.trim() !== '' && !line.trimStart().startsWith('#');
 const indentOf = (line) => line.length - line.trimStart().length;
 const isItem = (line) => /^\s*-(?:\s|$)/.test(line);
-
 /** The key's own indent: a `- key:` item line carries its first key two columns after the dash. */
 const keyIndentOf = (line) => (isItem(line) ? indentOf(line) + 2 : indentOf(line));
-
 /** The body of the value that starts after line `at` (a key line, or an item line for an item's body): its lines and their indent. */
 function bodyOf(lines, at, ownIndent) {
-  let last = at;
-  let childIndent = null;
-  for (let index = at + 1; index < lines.length; index += 1) {
-    const line = lines[index];
-    if (!significant(line)) continue;
-    const indent = indentOf(line);
-    const indentless = indent === ownIndent && isItem(line) && (childIndent === null || childIndent === ownIndent);
-    if (indent <= ownIndent && !indentless) break;
-    childIndent ??= indent;
-    last = index;
-  }
-  return { from: at + 1, to: last + 1, childIndent };
+    let last = at;
+    let childIndent = null;
+    for (let index = at + 1; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (!significant(line))
+            continue;
+        const indent = indentOf(line);
+        const indentless = indent === ownIndent && isItem(line) && (childIndent === null || childIndent === ownIndent);
+        if (indent <= ownIndent && !indentless)
+            break;
+        childIndent ??= indent;
+        last = index;
+    }
+    return { from: at + 1, to: last + 1, childIndent };
 }
-
 /** The line of `key` among the direct children (indent `indent`) of lines [from, to); `itemLine` may hold the first key of an item. */
 function keyLine(lines, { from, to }, indent, key, itemLine = -1) {
-  const pattern = new RegExp(`^\\s*(?:- )?${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:(?:\\s|$)`);
-  for (let index = itemLine >= 0 ? itemLine : from; index < to; index += 1) {
-    const line = lines[index];
-    if (!significant(line) || keyIndentOf(line) !== indent || (isItem(line) && index !== itemLine)) continue;
-    if (pattern.test(line)) return index;
-  }
-  return -1;
+    const pattern = new RegExp(`^\\s*(?:- )?${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}:(?:\\s|$)`);
+    for (let index = itemLine >= 0 ? itemLine : from; index < to; index += 1) {
+        const line = lines[index];
+        if (!significant(line) || keyIndentOf(line) !== indent || (isItem(line) && index !== itemLine))
+            continue;
+        if (pattern.test(line))
+            return index;
+    }
+    return -1;
 }
-
 /**
  * Resolves `path` to the value it names: a string steps into a mapping key, `{ item: key, is: value }` into the sequence item whose
  * `key` is `value`. Returns the line that opens the value (the key or item line), the indent of its keys and its body.
  */
 function locate(lines, path, file) {
-  let at = { line: -1, indent: -1, itemLine: -1, body: { from: 0, to: lines.length, childIndent: 0 } };
-  for (const step of path) {
-    const { body } = at;
-    if (typeof step === 'string') {
-      const indent = at.itemLine >= 0 ? at.indent : body.childIndent;
-      const line = keyLine(lines, body, indent, step, at.itemLine);
-      if (line < 0) throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${file} has no ${path.map(describe).join('.')}; add the declared Redis by hand`);
-      at = { line, indent: keyIndentOf(lines[line]), itemLine: -1, body: bodyOf(lines, line, keyIndentOf(lines[line])) };
-      continue;
+    let at = { line: -1, indent: -1, itemLine: -1, body: { from: 0, to: lines.length, childIndent: 0 } };
+    for (const step of path) {
+        const { body } = at;
+        if (typeof step === 'string') {
+            const indent = at.itemLine >= 0 ? at.indent : body.childIndent;
+            const line = keyLine(lines, body, indent, step, at.itemLine);
+            if (line < 0)
+                throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${file} has no ${path.map(describe).join('.')}; add the declared Redis by hand`);
+            at = { line, indent: keyIndentOf(lines[line]), itemLine: -1, body: bodyOf(lines, line, keyIndentOf(lines[line])) };
+            continue;
+        }
+        const items = [];
+        for (let index = body.from; index < body.to; index += 1)
+            if (significant(lines[index]) && isItem(lines[index]) && indentOf(lines[index]) === body.childIndent)
+                items.push(index);
+        const match = items.find((line, position) => {
+            const end = items[position + 1] ?? body.to;
+            return keyLine(lines, { from: line, to: end }, (body.childIndent ?? 0) + 2, step.item, line) >= 0
+                && new RegExp(`^\\s*(?:- )?${step.item}:\\s*${step.is}\\s*$`).test(lines[keyLine(lines, { from: line, to: end }, (body.childIndent ?? 0) + 2, step.item, line)]);
+        });
+        if (match === undefined)
+            throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${file} has no ${path.map(describe).join('.')}; add the declared Redis by hand`);
+        const itemBody = bodyOf(lines, match, body.childIndent ?? 0);
+        at = { line: match, indent: (body.childIndent ?? 0) + 2, itemLine: match, body: { ...itemBody, from: match, childIndent: (body.childIndent ?? 0) + 2 } };
     }
-    const items = [];
-    for (let index = body.from; index < body.to; index += 1) if (significant(lines[index]) && isItem(lines[index]) && indentOf(lines[index]) === body.childIndent) items.push(index);
-    const match = items.find((line, position) => {
-      const end = items[position + 1] ?? body.to;
-      return keyLine(lines, { from: line, to: end }, body.childIndent + 2, step.item, line) >= 0
-        && new RegExp(`^\\s*(?:- )?${step.item}:\\s*${step.is}\\s*$`).test(lines[keyLine(lines, { from: line, to: end }, body.childIndent + 2, step.item, line)]);
-    });
-    if (match === undefined) throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${file} has no ${path.map(describe).join('.')}; add the declared Redis by hand`);
-    const itemBody = bodyOf(lines, match, body.childIndent);
-    at = { line: match, indent: body.childIndent + 2, itemLine: match, body: { ...itemBody, from: match, childIndent: body.childIndent + 2 } };
-  }
-  return at;
+    return at;
 }
-
 const describe = (step) => (typeof step === 'string' ? step : `[${step.item}=${step.is}]`);
-
 /** The lines of `block` (written at indent 0) moved to `indent`. */
 const indented = (block, indent) => block.replace(/\n$/, '').split('\n').map((line) => (line ? ' '.repeat(indent) + line : line));
-
 /** A YAML text that adds entries under one mapping or items to one block sequence, and applies the same change to its document. */
 export class YamlBlockEdit {
-  constructor(text, file) {
-    this.file = file;
-    this.newline = text.includes('\r\n') ? '\r\n' : '\n';
-    this.lines = text.replace(/\r\n/g, '\n').split('\n');
-    this.document = parseYaml(text);
-    this.expected = structuredClone(this.document);
-  }
-
-  /** The parsed document as the edits leave it; mutate it in step with each text edit. */
-  get value() { return this.expected; }
-
-  /** Appends `block` (YAML lines at indent 0) as the last children of the mapping or sequence at `path`. */
-  append(path, block) {
-    const at = locate(this.lines, path, this.file);
-    const { body } = at;
-    const indent = body.to > body.from && body.childIndent !== null ? body.childIndent : at.indent + 2;
-    this.lines.splice(body.to, 0, ...indented(block, indent));
-    return this;
-  }
-
-  /** Adds `value` to the flow sequence (`key: [a, b]`) at `path`. */
-  extendFlow(path, value) {
-    const at = locate(this.lines, path, this.file);
-    const line = this.lines[at.line];
-    const flow = /^(.*:\s*\[)(.*)\](\s*)$/.exec(line);
-    if (!flow) throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${this.file} writes ${path.map(describe).join('.')} as no one-line flow sequence; add the declared Redis by hand`);
-    const items = flow[2].trim();
-    this.lines[at.line] = `${flow[1]}${items ? `${items}, ` : ''}${value}]${flow[3]}`;
-    return this;
-  }
-
-  /** The edited text, or a refusal when it does not parse to the expected document. */
-  text() {
-    const text = this.lines.join(this.newline);
-    let parsed;
-    try { parsed = parseYaml(text); } catch { parsed = undefined; }
-    if (!isDeepStrictEqual(parsed, this.expected)) throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${this.file} is not in a shape the declared Redis can be added to; add it by hand`);
-    return text;
-  }
+    file;
+    newline;
+    lines;
+    document;
+    expected;
+    constructor(text, file) {
+        this.file = file;
+        this.newline = text.includes('\r\n') ? '\r\n' : '\n';
+        this.lines = text.replace(/\r\n/g, '\n').split('\n');
+        this.document = parseYaml(text);
+        this.expected = structuredClone(this.document);
+    }
+    /** The parsed document as the edits leave it; mutate it in step with each text edit. */
+    get value() { return this.expected; }
+    /** Appends `block` (YAML lines at indent 0) as the last children of the mapping or sequence at `path`. */
+    append(path, block) {
+        const at = locate(this.lines, path, this.file);
+        const { body } = at;
+        const indent = body.to > body.from && body.childIndent !== null ? body.childIndent : at.indent + 2;
+        this.lines.splice(body.to, 0, ...indented(block, indent));
+        return this;
+    }
+    /** Adds `value` to the flow sequence (`key: [a, b]`) at `path`. */
+    extendFlow(path, value) {
+        const at = locate(this.lines, path, this.file);
+        const line = this.lines[at.line];
+        const flow = /^(.*:\s*\[)(.*)\](\s*)$/.exec(line);
+        if (!flow)
+            throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${this.file} writes ${path.map(describe).join('.')} as no one-line flow sequence; add the declared Redis by hand`);
+        const items = flow[2].trim();
+        this.lines[at.line] = `${flow[1]}${items ? `${items}, ` : ''}${value}]${flow[3]}`;
+        return this;
+    }
+    /** The edited text, or a refusal when it does not parse to the expected document. */
+    text() {
+        const text = this.lines.join(this.newline);
+        let parsed;
+        try {
+            parsed = parseYaml(text);
+        }
+        catch {
+            parsed = undefined;
+        }
+        if (!isDeepStrictEqual(parsed, this.expected))
+            throw new ScaffoldError('HFS_ADD_STACK_SHAPE', `${this.file} is not in a shape the declared Redis can be added to; add it by hand`);
+        return text;
+    }
 }

package/scripts/sync-bundles.d.mts

@@ -0,0 +1,31 @@
+export declare const bundlePackages: readonly ["eslint-canon-be", "eslint-canon-fe", "eslint-grammar-core", "eslint-grammar-offset-pop"];
+export declare const manifestName = "bundle.json";
+export interface BundleManifest {
+    readonly generated: readonly string[];
+    readonly own: readonly string[];
+}
+export interface Drift {
+    readonly pkg: string;
+    readonly path: string;
+    readonly reason: "differs" | "missing" | "hfs-missing" | "unlisted" | "listed-twice" | "own-missing";
+}
+export interface SyncResult {
+    readonly written: readonly string[];
+    readonly drift: readonly Drift[];
+}
+/** Every file under a package's runtime/ as a forward-slash path relative to runtime/, the manifest itself left out. */
+export declare function runtimeFiles(runtimeDir: string): string[];
+export declare function readManifest(file: string): BundleManifest;
+export declare function manifestText(manifest: BundleManifest): string;
+/** The manifest of a runtime folder today: a file hfs also has, byte for byte, is generated; any other file is the bundle's own. */
+export declare function classifyRuntime(runtimeDir: string, hfsRuntimeDir: string): BundleManifest;
+/**
+ * Syncs (or, with `check`, only judges) every bundling package under `packagesDir`.
+ * `hfsRuntimeDir` is hfs's runtime/ folder: the build output beside the sources.
+ */
+export declare function syncBundles(options: {
+    readonly packagesDir: string;
+    readonly hfsRuntimeDir: string;
+    readonly check: boolean;
+    readonly packages?: readonly string[];
+}): SyncResult;

package/src/fixtures/bypass-index.d.mts

@@ -0,0 +1,4 @@
+import type { Form, Lookalike } from './loosening/forms.mjs';
+
+export declare const FORBIDDEN_INDEX: readonly Form[];
+export declare const LOOKALIKES_INDEX: readonly Lookalike[];

package/src/fixtures/hfs-stack-tooling/passing.d.mts

@@ -0,0 +1,8 @@
+import type { StackToolingFiles } from './violating.mjs';
+
+declare const record: {
+  readonly schema: string;
+  readonly description: string;
+  readonly files: StackToolingFiles;
+};
+export default record;

package/src/fixtures/hfs-stack-tooling/violating.d.mts

@@ -0,0 +1,19 @@
+/** The files a stack-tooling fixture app writes: the two JSON documents and the text of every other file. */
+export type StackToolingFiles = {
+  readonly 'hfs.json': { readonly hfs: number; readonly kind: string; readonly project: string };
+  readonly 'package.json': { readonly name: string; readonly scripts: Readonly<Record<string, string>> };
+} & { readonly [path: string]: string | object };
+
+/** A finding expected of a file: the path and the canon verb it re-implements. */
+export interface StackToolingExpectation {
+  readonly path: string;
+  readonly verb: string;
+}
+
+declare const record: {
+  readonly schema: string;
+  readonly description: string;
+  readonly files: StackToolingFiles;
+  readonly expect: readonly StackToolingExpectation[];
+};
+export default record;

package/src/fixtures/hfs-stacks-full/model-unavailable.d.mts

@@ -0,0 +1,10 @@
+import type { StacksExpectation, StacksFiles } from './passing.mjs';
+
+declare const record: {
+  readonly schema: string;
+  readonly edition: string;
+  readonly description: string;
+  readonly files: StacksFiles;
+  readonly expect: StacksExpectation;
+};
+export default record;

package/src/fixtures/hfs-stacks-full/passing.d.mts

@@ -0,0 +1,19 @@
+/** The files of a repository: `hfs.json` and the YAML models as documents, every other file as text. */
+export type StacksFiles = { readonly 'hfs.json': object } & { readonly [path: string]: string | object };
+
+/** The finding codes each of the rules R266, R267, R268 and R275 is expected to report. */
+export interface StacksExpectation {
+  readonly R266: readonly string[];
+  readonly R267: readonly string[];
+  readonly R268: readonly string[];
+  readonly R275: readonly string[];
+}
+
+declare const record: {
+  readonly schema: string;
+  readonly edition: string;
+  readonly description: string;
+  readonly files: StacksFiles;
+  readonly expect: StacksExpectation;
+};
+export default record;

package/src/fixtures/hfs-stacks-full/violating.d.mts

@@ -0,0 +1,10 @@
+import type { StacksExpectation, StacksFiles } from './passing.mjs';
+
+declare const record: {
+  readonly schema: string;
+  readonly edition: string;
+  readonly description: string;
+  readonly files: StacksFiles;
+  readonly expect: StacksExpectation;
+};
+export default record;

package/src/fixtures/loosening/adversarial.d.mts

@@ -0,0 +1,4 @@
+import type { Form, Lookalike } from './forms.mjs';
+
+export declare const ADVERSARIAL: readonly Form[];
+export declare const SAFE: readonly Lookalike[];

package/src/fixtures/loosening/forms.d.mts

@@ -0,0 +1,16 @@
+/** A tree { [file]: text } holding a loosening of `kind`, with the `detail` its finding names when given. */
+export interface Form {
+  readonly id: string;
+  readonly file: string;
+  readonly text: string;
+  readonly kind: string;
+  readonly detail?: string;
+}
+/** The same words as data or prose, which the check leaves alone. */
+export interface Lookalike {
+  readonly id: string;
+  readonly file: string;
+  readonly text: string;
+}
+export declare const FORBIDDEN: readonly Form[];
+export declare const LOOKALIKES: readonly Lookalike[];

package/src/fixtures/loosening/swallows.d.mts

@@ -0,0 +1,5 @@
+export declare const OR_TRUE: string;
+export declare const OR_COLON: string;
+export declare const SEMI_TRUE: string;
+export declare const OR_ECHO: string;
+export declare const OR_EXIT_ZERO: string;