@onlineapps/conn-orch-validator 7.0.0 → 8.0.0

package/src/sync/serviceTemplate.js

@@ -0,0 +1,583 @@
+'use strict';
+
+/**
+ * The business-service template, as a renderer.
+ *
+ * The template ships INSIDE this package (confirmation `biz-service-manifest`
+ * 001 §2), so the shape a service is created from is pinned by the same version
+ * that pins the manifest it is checked against. `api/templates/business-service`
+ * is no longer the source: it is this renderer's output, committed for reading
+ * (§5), and `templateMirror.test.js` is what keeps that true.
+ *
+ * Everything here is text in, text out. Nothing reads `process.env`, nothing
+ * writes a file, nothing decides where a service lives
+ * (`.claude/rules/architecture-principles.md` §1) — the CLI does all three. That
+ * is what lets the identity render be compared byte for byte against the
+ * template itself, which is the only way §9's acceptance ("the directory in
+ * api/ differs from the generator's output by nothing") can be measured rather
+ * than asserted.
+ *
+ * @see api/docs/governance/confirmations/biz-service-manifest.md §2, §5, §9
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/** The template as it lies in this package. */
+const TEMPLATE_ROOT = path.join(__dirname, '..', '..', 'templates', 'business-service');
+
+/**
+ * One placeholder, one fact — and the reason there are four rather than three.
+ *
+ * The template used to spend `__SERVICE_NAME__` on two different facts: the
+ * registry identity (`biz-reporting`) and the directory-derived paths
+ * (`config/env-active/reporting.env`). Substitution cannot satisfy both, so the
+ * scaffold patched the identity back in afterwards with two `jq` calls — which
+ * is a second writer of one file, and it reformatted the JSON while it was
+ * there. `__REGISTRY_NAME__` is that second fact given its own name, and it is
+ * what makes rendering a pure text substitution.
+ */
+const PLACEHOLDERS = Object.freeze({
+  service_name: '__SERVICE_NAME__',
+  container_name: '__CONTAINER_NAME__',
+  repo_name: '__REPO_NAME__',
+  registry_name: '__REGISTRY_NAME__',
+  description: '__SERVICE_DESCRIPTION__'
+});
+
+/**
+ * The parameters that render the template into itself.
+ *
+ * Not a test fixture: it is the definition of what `api/templates/business-service`
+ * IS. Rendering with these values substitutes every placeholder by itself, so
+ * the output is the template — which is exactly the claim §9 makes, expressed
+ * as something a run can compare.
+ */
+const IDENTITY_PARAMS = Object.freeze({
+  service_name: PLACEHOLDERS.service_name,
+  container_name: PLACEHOLDERS.container_name,
+  repo_name: PLACEHOLDERS.repo_name,
+  registry_name: PLACEHOLDERS.registry_name,
+  description: null
+});
+
+/**
+ * What a platform pin looks like in the template, until the run that creates a
+ * service resolves it.
+ *
+ * A version number typed into `package.json.template` is a descriptive fact
+ * written by hand: true on the day it was typed and a lie from the next publish
+ * onwards (`.claude/rules/doc-code-binding.md` §1). Measured 2026-09-14, the day
+ * this placeholder landed: the template pinned `@onlineapps/service-wrapper`
+ * 2.1.119 and `@onlineapps/service-common` 1.1.1, while `api/config/libraries.json`
+ * - the platform SSOT - held 7.0.0 and 2.0.1. The numbers had never done any
+ * work either: `oa-sync-template --new` has overwritten every `@onlineapps/*`
+ * pin from the SSOT since the template moved into this package, so what the
+ * template carried only ever misled the reader of the template.
+ *
+ * It is NOT a `PLACEHOLDERS` entry, and the difference is the point: `renderText`
+ * substitutes facts about the service being created, which the caller types.
+ * This one is a fact about the PLATFORM, and only the SSOT knows it - so the
+ * renderer leaves it standing and the CLI's pin step is the single place that
+ * resolves it (`.claude/rules/change-discipline.md` § One rail per concern).
+ * An identity render therefore shows the placeholder, which is what
+ * `api/templates/business-service/package.json` reads as: "this pin comes from
+ * the SSOT".
+ *
+ * Where an EXISTING service's pins come from is a different rail, and it is not
+ * this one: `api/scripts/publish-library.sh` STEP 5 rewrites every dependent's
+ * `package.json` when a library is published. The template pins the first
+ * install; the cascade pins every install after it.
+ */
+const SSOT_PIN = '__SSOT_PIN__';
+
+/**
+ * Files whose packed name differs from the name they are written under, because
+ * something outside this package reserves the written name.
+ *
+ * Both entries were measured on 2026-09-09, and neither is a matter of taste:
+ *
+ *   * `gitignore` — npm never packs a file called `.gitignore`. It was the one
+ *     file of 22 missing from `npm pack --dry-run` while every other dotfile
+ *     (`.gitlab-ci.yml`) shipped, and this package's own `.npmignore` does not
+ *     mention it.
+ *   * `package.json.template` — a `package.json` inside a package is a SECOND
+ *     package to every tool that walks a package tree. With the file under its
+ *     written name, `oa-validate --library --all` reported eight findings about
+ *     the template (U-ORPHAN, U-MISMATCH, L-PINS ×2, L-PACK-TESTS, L-CHANGELOG,
+ *     L-README, L-CONSUMER) and `scripts/ci/verify-manifest-pins.mjs`, step 1 of
+ *     the pre-push hook, reported two more. All ten are false: the template's
+ *     pins are DELIBERATELY not the platform's — the generator writes the SSOT's
+ *     versions when it creates a service, which is the property
+ *     `api/tests/scripts/add-service.bats` asserts — and the template is not a
+ *     published library at all.
+ *
+ * The name is where the fact lives, so no walker has to be taught an exception,
+ * now or later. One map, applied in one place, rather than a rule each caller
+ * remembers.
+ */
+const PACKED_NAMES = Object.freeze({
+  gitignore: '.gitignore',
+  'package.json.template': 'package.json'
+});
+
+/**
+ * The files a service is expected to EXECUTE, so the ones written executable.
+ *
+ * `init.sh` is the file a service is started through. `scripts/verify-deploy-uniform.sh`
+ * is invoked by name from the `deploy-production` job of the rendered
+ * `.gitlab-ci.yml`, so a copy without the bit fails that job with "permission
+ * denied" instead of measuring the uniform — and a gate that cannot run is the
+ * false guarantee `automation-gates.md` §5 names.
+ */
+const EXECUTABLE_FILES = Object.freeze(['init.sh', 'scripts/verify-deploy-uniform.sh']);
+
+/**
+ * The env template's name in the template, and the name it is written under.
+ *
+ * The service's own env template is called after the service in every live repo
+ * (`api_biz/emailer/config/env-templates/emailer.env`), so the name is
+ * per-service and cannot be a fixed file name in the template. The rename is a
+ * step of creating a service, NOT of rendering: `renderTree` substitutes TEXT,
+ * and a file NAME is not text it touches.
+ *
+ * The source is named with the placeholder rather than with a word of its own,
+ * so that an identity render — the one `api/templates/business-service` is
+ * (001 §5, §9) — is self-consistent: the compose files load
+ * `env-active/__SERVICE_NAME__.env`, and that is what the template carries.
+ * Until d.236 it was called `service.env`, which made the template the one
+ * bearer wearing two names, and `C-IDENTITY` said so the day it landed.
+ */
+const ENV_TEMPLATE_SOURCE = 'config/env-templates/__SERVICE_NAME__.env';
+const envTemplateTarget = (serviceName) => `config/env-templates/${serviceName}.env`;
+
+/** The directory name of a business service, which every derived fact comes from. */
+const SERVICE_NAME = /^[a-z][a-z0-9-]*$/;
+
+/**
+ * The identity of one service, derived from the one thing a caller types.
+ *
+ * @param {{name: string, description?: string|null}} params
+ * @returns {{service_name: string, container_name: string, repo_name: string,
+ *            registry_name: string, description: string|null}}
+ */
+function deriveParams({ name, description = null } = {}) {
+  if (typeof name !== 'string' || !SERVICE_NAME.test(name)) {
+    throw new Error(`[ServiceTemplate] Invalid service name ${JSON.stringify(name)} - expected the `
+      + 'directory name under api_biz/: lower-case letters, digits and hyphens, starting with a letter. '
+      + 'Fix: oa-sync-template --new <name>, e.g. --new reporting.');
+  }
+  if (description !== null && (typeof description !== 'string' || description.trim() === '')) {
+    throw new Error(`[ServiceTemplate] Invalid description ${JSON.stringify(description)} - a description `
+      + 'is a sentence or it is absent; an empty one would write a blank line where the template asks what '
+      + 'this service is for. Fix: pass --description "<sentence>", or leave it out.');
+  }
+
+  return {
+    service_name: name,
+    container_name: `api_service_${name.replace(/-/g, '_')}`,
+    repo_name: `biz-${name}`,
+    registry_name: `biz-${name}`,
+    description
+  };
+}
+
+/**
+ * The name a packed template file is written under.
+ *
+ * @param {string} packed template-relative path, as it lies in the package
+ * @returns {string} service-relative path
+ */
+function outputRelative(packed) {
+  const target = PACKED_NAMES[packed];
+  return target === undefined ? packed : target;
+}
+
+/**
+ * The template's own ignore file, under the name it is PACKED as. It is the one
+ * place saying which paths of a rendered service tree are generated output, and
+ * every reader of that rule reads it here.
+ */
+const GITIGNORE_SOURCE = 'gitignore';
+
+/**
+ * One `.gitignore` line as a rule, or `null` for a line that is not one.
+ *
+ * @param {string} line the line, verbatim
+ * @returns {{negated: boolean, directoryOnly: boolean, anchored: boolean, match: RegExp}|null}
+ */
+function compileRule(line) {
+  const trimmed = line.replace(/\r$/, '').trim();
+  if (trimmed === '' || trimmed.startsWith('#')) return null;
+
+  let pattern = trimmed;
+  const negated = pattern.startsWith('!');
+  if (negated) pattern = pattern.slice(1);
+
+  const directoryOnly = pattern.endsWith('/');
+  if (directoryOnly) pattern = pattern.slice(0, -1);
+
+  const anchored = pattern.startsWith('/') || pattern.includes('/');
+  if (pattern.startsWith('/')) pattern = pattern.slice(1);
+
+  return { negated, directoryOnly, anchored, match: globToRegExp(pattern) };
+}
+
+/**
+ * A `.gitignore` glob as a regular expression: `*` stays inside one segment,
+ * `**` crosses them, `?` is one character, everything else is literal.
+ *
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+function globToRegExp(glob) {
+  let source = '^';
+  for (let index = 0; index < glob.length; index += 1) {
+    const character = glob[index];
+    if (character === '*') {
+      if (glob[index + 1] === '*') {
+        source += '.*';
+        index += 1;
+      } else {
+        source += '[^/]*';
+      }
+    } else if (character === '?') {
+      source += '[^/]';
+    } else {
+      source += character.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`${source}$`);
+}
+
+/**
+ * Read a `.gitignore` and return the question it answers: is this path ignored?
+ *
+ * Git's own reading, in the part of it these files use: a rule ending in `/`
+ * covers directories only, a rule carrying a `/` is anchored at the root and one
+ * without matches a name at any depth, a matched DIRECTORY carries everything
+ * under it, and the LAST rule that matches decides — which is what makes a `!`
+ * exception work.
+ *
+ * @param {string} text the file, verbatim
+ * @returns {(relative: string) => boolean} for a path relative to the tree root, `/`-separated
+ */
+function compileGitignore(text) {
+  const rules = text.split('\n').map(compileRule).filter((rule) => rule !== null);
+
+  return (relative) => {
+    const segments = relative.split('/');
+
+    // Every ancestor directory of the path, then the path itself. An ancestor
+    // that matches ignores everything below it, which is how `ci/` covers
+    // `ci/deployability.json`.
+    const candidates = segments.slice(0, -1)
+      .map((_, index) => ({ path: segments.slice(0, index + 1).join('/'), directory: true }));
+    candidates.push({ path: relative, directory: false });
+
+    let ignored = false;
+    for (const rule of rules) {
+      const hit = candidates.some((candidate) => {
+        if (rule.directoryOnly && !candidate.directory) return false;
+        const subject = rule.anchored ? candidate.path : candidate.path.split('/').pop();
+        return rule.match.test(subject);
+      });
+      if (hit) ignored = !rule.negated;
+    }
+    return ignored;
+  };
+}
+
+/**
+ * The template's ignore rules, as the packaged template writes them.
+ *
+ * @returns {(relative: string) => boolean}
+ */
+function templateIgnores() {
+  return compileGitignore(fs.readFileSync(path.join(TEMPLATE_ROOT, GITIGNORE_SOURCE), 'utf8'));
+}
+
+/**
+ * The files of a rendered template directory that the mirror comparison is
+ * ABOUT: everything the tree carries, minus what the template's own `.gitignore`
+ * covers.
+ *
+ * `oa-validate` records its verdict in the tree it measured (d.232), so a run
+ * over `api/templates/business-service` leaves `ci/deployability.json` there.
+ * Git does not see that file — the template's `.gitignore` says so — and calling
+ * it a stale copy made a legitimate run look like drift (d.237). The rule has
+ * ONE owner, the template's `.gitignore`, and no reader keeps a list of names
+ * beside it (`.claude/rules/change-discipline.md` § One rail per concern).
+ *
+ * @param {string} root a rendered template directory
+ * @returns {string[]} output-relative paths, sorted
+ */
+function listOutputFiles(root) {
+  const ignored = templateIgnores();
+  return listTemplateFiles(root).filter((relative) => !ignored(relative));
+}
+
+/**
+ * Every file of a template root, template-relative, sorted so two runs list them
+ * in the same order.
+ *
+ * @param {string} root
+ * @returns {string[]}
+ */
+function listTemplateFiles(root) {
+  if (!fs.existsSync(root)) {
+    throw new Error(`[ServiceTemplate] Template root does not exist - ${root}. `
+      + 'Fix: reinstall @onlineapps/conn-orch-validator; the template ships inside the package '
+      + '(confirmation biz-service-manifest 001 §2).');
+  }
+
+  const collected = [];
+  const walk = (dir, prefix) => {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      const relative = prefix === '' ? entry.name : `${prefix}/${entry.name}`;
+      if (entry.isDirectory()) walk(path.join(dir, entry.name), relative);
+      else collected.push(relative);
+    }
+  };
+  walk(root, '');
+  return collected.sort();
+}
+
+/**
+ * One file's text with the service's parameters in it.
+ *
+ * `__SERVICE_DESCRIPTION__` is substituted only when a description was given.
+ * With none, it is LEFT STANDING on purpose: this run has no description, and
+ * writing a plausible one would put a fact in the repository that nobody stated
+ * (`.claude/rules/doc-code-binding.md` §1). The caller reports the files that
+ * still carry it, which is what `add-service.sh` has always done.
+ *
+ * @param {string} text
+ * @param {object} params from `deriveParams`
+ * @returns {string}
+ */
+function renderText(text, params) {
+  if (typeof text !== 'string') {
+    throw new Error(`[ServiceTemplate] File text is required - renderText(text, params) got ${
+      text === null ? 'null' : typeof text}. Fix: read the template file before rendering it.`);
+  }
+
+  let rendered = text;
+  for (const key of ['service_name', 'container_name', 'repo_name', 'registry_name']) {
+    const value = params && params[key];
+    if (typeof value !== 'string') {
+      throw new Error(`[ServiceTemplate] Missing parameter "${key}" - the template spends a placeholder `
+        + `${PLACEHOLDERS[key]} on it and nothing else can supply it. `
+        + 'Fix: build the parameters with deriveParams({ name }).');
+    }
+    rendered = rendered.split(PLACEHOLDERS[key]).join(value);
+  }
+
+  if (params.description !== null && params.description !== undefined) {
+    rendered = rendered.split(PLACEHOLDERS.description).join(params.description);
+  }
+  return rendered;
+}
+
+/**
+ * The whole template rendered for one service, keyed by the path each file is
+ * written under.
+ *
+ * The env-template rename is deliberately NOT here — see `ENV_TEMPLATE_SOURCE`.
+ *
+ * @param {{templateRoot?: string, params: object}} args
+ * @returns {Map<string, string>} service-relative path → file text
+ */
+function renderTree({ templateRoot = TEMPLATE_ROOT, params } = {}) {
+  const tree = new Map();
+  for (const packed of listTemplateFiles(templateRoot)) {
+    const text = fs.readFileSync(path.join(templateRoot, packed), 'utf8');
+    tree.set(outputRelative(packed), renderText(text, params));
+  }
+  return tree;
+}
+
+/**
+ * The marker lines of a delimited block, in the one spelling
+ * `api/tests/scripts/infra-init-scripts.bats` and the manifest check
+ * `template-block` already read: `# --- <name>` … `# --- end <name>`.
+ */
+const blockOpen = (block) => `# --- ${block}`;
+const blockClose = (block) => `# --- end ${block}`;
+
+/**
+ * The markers are matched TRIMMED, the same way `checks/serviceFiles.js` reads
+ * them: `oa-deps-guard v1` sits at column 0 in a shell script, `oa-test-runner
+ * v1` two spaces in, inside a compose file's `services:` mapping. A comment is a
+ * comment at either column, and one spelling of the rule is what keeps the check
+ * and the splice from disagreeing about where a block begins.
+ */
+
+/**
+ * A file with one delimited block replaced, and every other line of it left
+ * exactly as it was.
+ *
+ * A file that carries no such block is REFUSED rather than repaired: where the
+ * block belongs is a decision about that service's own install steps, and a
+ * generator that picks a position is guessing (`.claude/rules/change-discipline.md`
+ * — no workarounds, fix at source). That reasoning holds for `init.sh`, whose
+ * block sits after install steps only that service knows about; it does NOT hold
+ * for a compose file, where a mapping key has exactly one place its entries can
+ * start — see `insertBlockUnder`, which is why F-RUNNER's fix is a command and
+ * F-INIT's still is not.
+ *
+ * @param {{text: string, block: string, replacement: string[]}} args
+ * @returns {string}
+ */
+function spliceBlock({ text, block, replacement }) {
+  const lines = text.split('\n');
+  const open = blockOpen(block);
+  const close = blockClose(block);
+
+  const start = lines.findIndex((line) => line.trim().startsWith(open) && !line.trim().startsWith(close));
+  if (start === -1) {
+    throw new Error(`[ServiceTemplate] No "${block}" block to replace - the file carries no line opening `
+      + `with "${open}". Fix: paste the block from the template once, at the place it belongs in this `
+      + 'file — after this file\'s own install steps in an init.sh, under services: in a compose file; '
+      + 'from then on the sync keeps it current.');
+  }
+
+  const end = lines.findIndex((line, index) => index >= start && line.trim().startsWith(close));
+  if (end === -1) {
+    throw new Error(`[ServiceTemplate] The "${block}" block never closes - "${open}" is there, "${close}" `
+      + 'is not, so what would be replaced is undefined. Fix: close the block, then run the sync again.');
+  }
+
+  return [...lines.slice(0, start), ...replacement, ...lines.slice(end + 1)].join('\n');
+}
+
+/**
+ * A file with a delimited block INSERTED as the first entry of a mapping, and
+ * every other line of it left exactly as it was.
+ *
+ * The position is not a guess, which is what separates this from `spliceBlock`'s
+ * refusal: `services:` is a mapping, its entries are unordered by the language,
+ * and "immediately under the key" is the one place that needs no judgement about
+ * the file's contents. Measured 2026-09-09: seven of the eight biz repositories
+ * carried no runner block at all, so the row's `fix` read "BLOCKED — paste it in
+ * by hand once", which is advice rather than the command confirmation
+ * `biz-service-manifest` 001 §3.2 requires of every finding.
+ *
+ * Text in, text out: the rest of the file is not re-serialized, so a comment,
+ * a quoting style and a blank line survive a run that only had to add a block
+ * (`.claude/rules/automation-gates.md` §1 requirement 3).
+ *
+ * @param {{text: string, key: string, replacement: string[]}} args the file, the
+ *   top-level mapping key the block belongs under, and the block's lines
+ * @returns {string}
+ */
+function insertBlockUnder({ text, key, replacement }) {
+  const lines = text.split('\n');
+  const at = lines.findIndex((line) => line.trimEnd() === `${key}:`);
+  if (at === -1) {
+    throw new Error(`[ServiceTemplate] No "${key}:" mapping to insert the block under - the file declares no `
+      + `line reading exactly "${key}:", so there is no unambiguous place for it. `
+      + `Fix: give the file its "${key}:" mapping, then run the sync again.`);
+  }
+
+  return [...lines.slice(0, at + 1), ...replacement, '', ...lines.slice(at + 1)].join('\n');
+}
+
+/** A top-level mapping key: a line that starts in column 0 and ends its key with a colon. */
+const TOP_LEVEL_KEY = /^([A-Za-z_][A-Za-z0-9_.-]*):/;
+
+/**
+ * The top-level mapping keys a run of lines declares, in the order it declares
+ * them.
+ *
+ * ONE OWNER for "what does this block claim". The check names them in its
+ * finding and the sync removes exactly those from a file that predates the
+ * markers; deriving them twice would be two answers to one question
+ * (`.claude/rules/change-discipline.md` § One rail per concern), and the day the
+ * block gained a job the two would disagree about which file had drifted.
+ *
+ * Column 0 is the whole rule, and it is enough for the one file this reads:
+ * a `.gitlab-ci.yml` job is a top-level key and everything it owns is indented
+ * under it. Text in, text out — nothing is re-serialized, so a comment and a
+ * quoting style survive (`.claude/rules/automation-gates.md` §1 requirement 3).
+ *
+ * @param {string[]} lines
+ * @returns {string[]}
+ */
+function topLevelKeys(lines) {
+  return lines.map((line) => (TOP_LEVEL_KEY.exec(line) || [])[1]).filter((key) => key !== undefined);
+}
+
+/**
+ * A file with the named top-level keys REMOVED and a block put where the first
+ * of them stood.
+ *
+ * This is the migration `spliceBlock` cannot do and `insertBlockUnder` must not:
+ * measured over the eight biz repositories on 2026-09-11, every one carries the
+ * platform's jobs as unmarked top-level keys copied before the markers existed.
+ * Inserting the block beside them would give the file a second `build:` and a
+ * second `deploy-production:` — duplicate mapping keys, which GitLab either
+ * refuses or resolves by taking the last one. Neither is a sync.
+ *
+ * The position is not a guess either: the block lands exactly where the platform
+ * keys already were, so a file nobody has to re-read comes back in the order its
+ * author left it. A key's span starts at the KEY and not at a comment above it —
+ * that comment is the repository's prose, the same rule `composeRunnerBlock.js`
+ * § serviceSpan states for a compose node.
+ *
+ * @param {{text: string, keys: string[], replacement: string[]}} args
+ * @returns {string}
+ */
+function replaceTopLevelKeys({ text, keys, replacement }) {
+  const lines = text.split('\n');
+  const starts = lines
+    .map((line, index) => ({ key: (TOP_LEVEL_KEY.exec(line) || [])[1], index }))
+    .filter((entry) => entry.key !== undefined);
+
+  const doomed = new Set();
+  for (let i = 0; i < starts.length; i += 1) {
+    if (!keys.includes(starts[i].key)) continue;
+    const end = i + 1 < starts.length ? starts[i + 1].index : lines.length;
+    for (let line = starts[i].index; line < end; line += 1) doomed.add(line);
+  }
+
+  const at = doomed.size === 0 ? 0 : Math.min(...doomed);
+  const kept = [];
+  for (let line = 0; line < lines.length; line += 1) {
+    if (line === at) kept.push(...replacement, '');
+    if (!doomed.has(line)) kept.push(lines[line]);
+  }
+  if (at >= lines.length) kept.push(...replacement, '');
+
+  // No tidying pass over the rest of the file: a removed span reaches to the
+  // next top-level key, so it takes its own trailing blank line with it, and the
+  // block brings exactly one of its own. Collapsing blank lines globally would
+  // rewrite text outside the block, which is the one thing this run must not do
+  // (`.claude/rules/automation-gates.md` §1 requirement 3). Measured over all
+  // eight biz pipelines on 2026-09-11: no stacked blank line in any output.
+  return kept.join('\n');
+}
+
+module.exports = {
+  TEMPLATE_ROOT,
+  PLACEHOLDERS,
+  IDENTITY_PARAMS,
+  SSOT_PIN,
+  PACKED_NAMES,
+  EXECUTABLE_FILES,
+  ENV_TEMPLATE_SOURCE,
+  envTemplateTarget,
+  deriveParams,
+  outputRelative,
+  listTemplateFiles,
+  listOutputFiles,
+  templateIgnores,
+  compileGitignore,
+  GITIGNORE_SOURCE,
+  renderText,
+  renderTree,
+  spliceBlock,
+  topLevelKeys,
+  replaceTopLevelKeys,
+  insertBlockUnder
+};