@nci-gis/js-tmpl 0.0.1 → 0.1.1

package/src/config/valuePartials.js

@@ -0,0 +1,114 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+import {
+  assertNoDuplicate,
+  assertValidSegments,
+  deriveNamespace,
+} from '../utils/namespacing.js';
+import { loadYamlOrJson } from './loader.js';
+
+const DEFAULT_EXTS = ['.yaml', '.yml', '.json'];
+
+/**
+ * Place a value into the namespaced tree. Assumes prefix-shadow collisions
+ * have already been ruled out by the caller, so intermediate segments can
+ * be created freely.
+ *
+ * @param {Record<string, unknown>} tree
+ * @param {string[]} chain
+ * @param {unknown} value
+ */
+function placeInTree(tree, chain, value) {
+  /** @type {Record<string, unknown>} */
+  let cur = tree;
+  for (let i = 0; i < chain.length - 1; i++) {
+    const seg = chain[i];
+    if (!(seg in cur)) {
+      cur[seg] = {};
+    }
+    cur = /** @type {Record<string, unknown>} */ (cur[seg]);
+  }
+  cur[/** @type {string} */ (chain.at(-1))] = value;
+}
+
+/**
+ * Cross-check for prefix-shadow collisions: two files whose dotted keys are
+ * such that one is a strict prefix of the other (e.g. `env` vs `env.prod`).
+ * A file's contents can't simultaneously be a leaf *and* a sub-tree.
+ *
+ * @param {Array<{ key: string, abs: string }>} entries
+ * @param {string} rootDir
+ */
+function assertNoPrefixShadow(entries, rootDir) {
+  const byKey = new Map(entries.map((e) => [e.key, e.abs]));
+  for (const { key, abs } of entries) {
+    for (const other of byKey.keys()) {
+      if (other === key) {
+        continue;
+      }
+      if (key.startsWith(`${other}.`)) {
+        throw new Error(
+          `Value partial shadow collision between '${other}' and '${key}':\n` +
+            `  - ${path.relative(rootDir, /** @type {string} */ (byKey.get(other)))}\n` +
+            `  - ${path.relative(rootDir, abs)}\n` +
+            `A file's contents cannot be both a leaf and a sub-tree.`,
+        );
+      }
+    }
+  }
+}
+
+/**
+ * Scan `valuesDir` recursively and assemble a namespaced tree of values.
+ *
+ * - Files are classified by path via `deriveNamespace` — `@<name>/` anywhere
+ *   in the chain triggers flatten (root-independent).
+ * - Supported formats per VP-10: `.yaml`, `.yml`, `.json` (first-match wins
+ *   if a file ends with multiple listed extensions — not a realistic case).
+ * - VP-4 is enforced via duplicate-throws and shadow-collision detection.
+ * - Empty or absent `valuesDir` returns an empty tree.
+ *
+ * Synchronous to match `loadYamlOrJson` and `resolveConfig`'s sync-all-the-way
+ * model. File counts in a values tree are small, so blocking I/O is fine.
+ *
+ * @param {string} valuesDir - Absolute path to the value-partials root.
+ * @param {string[]} [exts] - Accepted extensions (defaults to VP-10 set).
+ * @returns {Record<string, unknown>}
+ */
+export function scanValuePartials(valuesDir, exts = DEFAULT_EXTS) {
+  if (!valuesDir || !fs.existsSync(valuesDir)) {
+    return {};
+  }
+
+  const all = /** @type {string[]} */ (
+    fs.readdirSync(valuesDir, { recursive: true })
+  );
+  const files = all.filter((f) => exts.some((e) => f.endsWith(e)));
+
+  /** @type {Map<string, string>} */
+  const seen = new Map();
+  /** @type {Array<{ key: string, chain: string[], abs: string }>} */
+  const entries = [];
+
+  for (const rel of files) {
+    const ext = /** @type {string} */ (exts.find((e) => rel.endsWith(e)));
+    const abs = path.join(valuesDir, rel);
+    const chain = deriveNamespace({ relPath: rel, ext });
+
+    assertValidSegments(chain, abs, 'value partial');
+
+    const key = chain.join('.');
+    assertNoDuplicate(seen, key, abs, valuesDir, 'value partial');
+    entries.push({ key, chain, abs });
+  }
+
+  assertNoPrefixShadow(entries, valuesDir);
+
+  /** @type {Record<string, unknown>} */
+  const tree = {};
+  for (const e of entries) {
+    placeInTree(tree, e.chain, loadYamlOrJson(e.abs));
+  }
+  return tree;
+}

package/src/config/view.js

@@ -1,25 +1,98 @@
 /**
- * Build the view object by merging values with environment data.
+ * @typedef {object} BuildViewArgs
+ * @property {Record<string, unknown>} [rootValues]   - Top-level values from `valuesFile`.
+ * @property {Record<string, unknown>} [partials]     - Namespaced tree from `valuesDir`.
+ * @property {Record<string, string>}  [env]          - Allowlisted environment variables.
+ * @property {string}                  [valuesFile]   - Source path, for error messages.
+ * @property {string}                  [valuesDir]    - Source path, for error messages.
+ */
+
+const RESERVED_ENV = 'env';
+
+/**
+ * Build the view object from root values + namespaced partials + env.
  *
- * **Reserved key:** `env` is always set to the provided environment object.
- * If `values` contains a top-level `env` key, a warning is logged and
- * the key is overwritten.
+ * Collision rules (from plan):
+ * - **C-2** — a top-level key in `rootValues` that also appears as a top-level
+ *   namespace in `partials` is a hard error naming both sources.
+ * - **C-3** — a top-level namespace named `env` in `partials` is a hard error
+ *   (reserved for environment variables).
  *
- * @param {Record<string, unknown>} values
- * @param {Record<string, string>} [env]
+ * The `env` reserved key is always set from the provided `env` object. If
+ * `rootValues` contains a top-level `env`, a warning is logged and the key
+ * is overwritten (existing behavior preserved for back-compat).
+ *
+ * @param {BuildViewArgs} [args]
  * @returns {Record<string, unknown>}
  */
-export function buildView(values, env = {}) {
-  if ('env' in values) {
+export function buildView(args = {}) {
+  const rootValues = args.rootValues ?? {};
+  const partials = args.partials ?? {};
+  const env = args.env ?? {};
+  const valuesFile = args.valuesFile ?? '<valuesFile>';
+  const valuesDir = args.valuesDir ?? '<valuesDir>';
+
+  assertReservedEnvNotInPartials(partials, valuesDir);
+  assertNoRootNamespaceCollision(rootValues, partials, valuesFile, valuesDir);
+  warnOnReservedEnvInValuesFile(rootValues);
+
+  return {
+    ...rootValues,
+    ...partials,
+    [RESERVED_ENV]: env,
+  };
+}
+
+/**
+ * @param {Record<string, unknown>} partials
+ * @param {string} valuesDir
+ */
+function assertReservedEnvNotInPartials(partials, valuesDir) {
+  if (RESERVED_ENV in partials) {
+    throw new Error(
+      `Value partial conflicts with reserved 'env' namespace.\n` +
+        `  Source: ${valuesDir} produced a top-level 'env' namespace.\n` +
+        `  Rename the directory/file so it does not resolve to 'env'.`,
+    );
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} rootValues
+ * @param {Record<string, unknown>} partials
+ * @param {string} valuesFile
+ * @param {string} valuesDir
+ */
+function assertNoRootNamespaceCollision(
+  rootValues,
+  partials,
+  valuesFile,
+  valuesDir,
+) {
+  for (const key of Object.keys(rootValues)) {
+    if (key === RESERVED_ENV) {
+      continue;
+    }
+    if (key in partials) {
+      throw new Error(
+        `Duplicate view key '${key}' — registered by both:\n` +
+          `  - ${valuesFile} top-level key\n` +
+          `  - ${valuesDir}/${key}.(yaml|yml|json)`,
+      );
+    }
+  }
+}
+
+/**
+ * @param {Record<string, unknown>} values
+ */
+function warnOnReservedEnvInValuesFile(values) {
+  if (RESERVED_ENV in values) {
     console.warn(
       'Warning: "env" is a reserved key in js-tmpl and will be overwritten.\n' +
         'Rename the "env" key in your values file to avoid this.',
     );
   }
-  return {
-    ...values,
-    env,
-  };
 }
 
 /**

package/src/engine/contentRenderer.js

@@ -1,16 +1,29 @@
 import fs from 'node:fs/promises';
+import path from 'node:path';
 
 import Handlebars from 'handlebars';
 
 /**
- * Render template file with Handlebars & view object.
- * @param {string} filePath
+ * Render a template file with Handlebars against the view.
+ *
+ * Strict mode (VP-9): `{{var}}` on an undefined path throws rather than
+ * rendering empty. The error includes the template's relative path — this
+ * makes forgotten values a loud failure, not a silent blank.
+ *
+ * @param {string} filePath - Absolute path to the template file.
  * @param {Record<string, unknown>} view
- * @param {typeof Handlebars} [hbs] - Scoped Handlebars instance; falls back to global
+ * @param {typeof Handlebars} [hbs] - Scoped Handlebars instance; falls back to global.
+ * @param {string} [relPath] - Relative path (from templateDir), used in error messages.
  * @returns {Promise<string>}
  */
-export async function renderContent(filePath, view, hbs) {
+export async function renderContent(filePath, view, hbs, relPath) {
   const raw = await fs.readFile(filePath, 'utf8');
-  const compile = (hbs || Handlebars).compile(raw);
-  return compile(view);
+  const compile = (hbs || Handlebars).compile(raw, { strict: true });
+  try {
+    return compile(view);
+  } catch (err) {
+    const label = relPath || path.basename(filePath);
+    const msg = err instanceof Error ? err.message : String(err);
+    throw new Error(`Template '${label}': ${msg}`);
+  }
 }

package/src/engine/helpers.js

@@ -0,0 +1,93 @@
+/**
+ * Bare-identifier rule for helper names: `{{name}}` must parse without
+ * bracket notation. Hyphens are allowed (`date-format` is idiomatic).
+ */
+const HELPER_NAME_RE = /^[a-zA-Z_$][\w$-]*$/;
+
+/**
+ * Describe a value's type for error messages (`null` and arrays included).
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeType(value) {
+  if (value === null) {
+    return 'null';
+  }
+  if (Array.isArray(value)) {
+    return 'array';
+  }
+  return typeof value;
+}
+
+/**
+ * Throw if a single helper entry is invalid or collides on `hbs`.
+ *
+ * @param {string} name
+ * @param {unknown} fn
+ * @param {typeof import('handlebars')} hbs
+ */
+function assertValidHelper(name, fn, hbs) {
+  if (!HELPER_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid helper name '${name}' — must start with a letter, underscore, or\n` +
+        'dollar sign, and contain only letters, digits, underscores, dollars, or hyphens.\n' +
+        'For exotic names, use hbs.registerHelper() directly.',
+    );
+  }
+  if (typeof fn !== 'function') {
+    throw new Error(
+      `Helper '${name}' must be a function, got ${describeType(fn)}.\n` +
+        'Each value in helpersMap must be a callable function.',
+    );
+  }
+  if (Object.hasOwn(hbs.helpers, name)) {
+    throw new Error(
+      `Helper '${name}' is already registered on this Handlebars instance.\n` +
+        'To intentionally override a built-in, use hbs.registerHelper() directly.',
+    );
+  }
+}
+
+/**
+ * Register custom helpers on a scoped Handlebars instance.
+ *
+ * Validates every entry before registering any (atomic): a map with one
+ * invalid entry registers nothing. Names must be bare identifiers
+ * (`/^[a-zA-Z_$][\w$-]*$/`), values must be functions, and a name already
+ * registered on `hbs` (built-ins included) throws. Skips silently if
+ * `helpersMap` is falsy or empty.
+ *
+ * Helpers must be pure: same arguments, same result. js-tmpl cannot enforce
+ * this; a helper reading the clock, randomness, env, or disk makes output
+ * non-deterministic.
+ *
+ * @param {typeof import('handlebars')} hbs - Handlebars instance to register on
+ * @param {Record<string, import('handlebars').HelperDelegate>} [helpersMap] - Helper name → function
+ * @returns {void}
+ */
+export function registerHelpers(hbs, helpersMap) {
+  if (!hbs || typeof hbs.registerHelper !== 'function') {
+    throw new Error(
+      'registerHelpers requires a Handlebars instance as its first argument.\n' +
+        'Create one with Handlebars.create() and pass it to renderDirectory too.',
+    );
+  }
+  if (!helpersMap) {
+    return;
+  }
+  if (typeof helpersMap !== 'object' || Array.isArray(helpersMap)) {
+    throw new Error(
+      `helpersMap must be an object of name → function, got ${describeType(helpersMap)}.\n` +
+        'Example: registerHelpers(hbs, { upper: (s) => s.toUpperCase() })',
+    );
+  }
+
+  const entries = Object.entries(helpersMap);
+  for (const [name, fn] of entries) {
+    assertValidHelper(name, fn, hbs);
+  }
+  for (const [name, fn] of entries) {
+    hbs.registerHelper(name, fn);
+  }
+}

package/src/engine/partials.js

@@ -1,51 +1,29 @@
 import fs from 'node:fs/promises';
-import path from 'node:path';
 
-const VALID_SEGMENT = /^\w+$/;
+import {
+  assertNoDuplicate,
+  assertValidSegments,
+  deriveNamespace,
+} from '../utils/namespacing.js';
 
 /**
- * Validate a partial name segment (directory or file basename).
- * @param {string[]} segments
- * @param {string} filePath
- */
-function validateSegments(segments, filePath) {
-  if (!VALID_SEGMENT.test(segments.join(''))) {
-    throw new Error(
-      `Invalid partial name segment '${segments.join('>')}' in ${filePath} — only alphanumeric and underscore allowed`,
-    );
-  }
-}
-
-/**
- * Derive a partial entry from a file path.
+ * Derive a partial entry from a relative file path.
  *
  * @param {string} partialsDir - Root partials directory
  * @param {string} ext - Template extension (e.g. ".hbs")
  * @param {string} filePath - Relative path from partialsDir
- * @param {boolean} isFlat - If true, register by filename only; otherwise namespace by path
  * @returns {{ name: string, source: string }}
  */
-function processPartialFile(partialsDir, ext, filePath, isFlat) {
-  const abs = path.join(partialsDir, filePath);
-
-  // Flat by filename: "name.hbs" → "name"
-  if (isFlat) {
-    const name = path.basename(filePath, ext);
-    validateSegments([name], abs);
-    return { name, source: abs };
-  }
-
-  // Namespace by path, e.g.:
-  // - "dir/name.hbs" → "dir.name"
-  // - "dir/sub/name.hbs" → "dir.sub.name"
-  // - "name.hbs" → "name" (no nesting).
-  const segments = filePath.slice(0, -ext.length).split(path.sep);
-  validateSegments(segments, abs);
+function processPartialFile(partialsDir, ext, filePath) {
+  const abs = `${partialsDir}/${filePath}`;
+  const segments = deriveNamespace({ relPath: filePath, ext });
+  assertValidSegments(segments, abs, 'partial name');
   return { name: segments.join('.'), source: abs };
 }
 
 /**
  * Scan partialsDir recursively and collect all partial entries.
+ *
  * @param {string} partialsDir
  * @param {string} ext
  * @returns {Promise<Array<{ name: string, source: string }>>}
@@ -55,34 +33,26 @@ async function scanPartialFiles(partialsDir, ext) {
 
   return allFiles
     .filter((f) => f.endsWith(ext))
-    .map((f) => {
-      const isFlat = f.startsWith('@');
-      return processPartialFile(partialsDir, ext, f, isFlat);
-    });
+    .map((f) => processPartialFile(partialsDir, ext, f));
 }
 
 /**
- * Check for duplicate partial names and throw if found.
+ * Throw on duplicate partial names.
+ *
  * @param {Array<{ name: string, source: string }>} entries
  * @param {string} partialsDir
  */
 function checkDuplicates(entries, partialsDir) {
   /** @type {Map<string, string>} */
   const seen = new Map();
-
   for (const entry of entries) {
-    const existing = seen.get(entry.name);
-    if (existing) {
-      const rel1 = path.relative(partialsDir, existing);
-      const rel2 = path.relative(partialsDir, entry.source);
-      throw new Error(
-        `Duplicate partial name '${entry.name}' — registered by both:\n` +
-          `  - ${rel1}\n` +
-          `  - ${rel2}\n` +
-          `Use namespaced directories to avoid collisions.`,
-      );
-    }
-    seen.set(entry.name, entry.source);
+    assertNoDuplicate(
+      seen,
+      entry.name,
+      entry.source,
+      partialsDir,
+      'partial name',
+    );
   }
 }
 
@@ -90,9 +60,11 @@ function checkDuplicates(entries, partialsDir) {
  * Register partials from a directory onto a Handlebars instance.
  *
  * Naming conventions:
- *   - `name.hbs` in root → "name"
- *   - `dir/name.hbs` → "dir.name" (namespaced by directory path)
- *   - `@dir/` at root → flatten entire subtree (filename only)
+ * - `name.hbs` in root → "name"
+ * - `dir/name.hbs` → "dir.name" (namespaced by directory path)
+ * - `@<name>/` anywhere in the path flattens the chain: the key is the
+ *   file's basename. Root-independent — scanning `partials/` vs
+ *   `partials/foo/` yields the same key for `partials/foo/@shared/x.hbs`.
  *
  * Throws on duplicate partial names or invalid name segments.
  * Skips silently if partialsDir is falsy. Throws if the directory does not exist.

package/src/engine/pathFormula.js

@@ -0,0 +1,74 @@
+import { getNested } from '../utils/object.js';
+import { classifySegment } from './pathSegment.js';
+
+/**
+ * Check whether a dotted key path is *present* in `view` as an own property.
+ *
+ * Distinct from `getNested`, which can't tell "missing" from "present but null/undefined".
+ * Required by G-4 (missing var throws) vs G-3 (present-but-falsy fails).
+ *
+ * @param {unknown} view
+ * @param {string} key
+ * @returns {boolean}
+ */
+function hasNested(view, key) {
+  const parts = key.split('.');
+  let cur = view;
+  for (let i = 0; i < parts.length - 1; i++) {
+    if (cur === null || cur === undefined || typeof cur !== 'object') {
+      return false;
+    }
+    cur = /** @type {Record<string, unknown>} */ (cur)[parts[i]];
+  }
+  if (cur === null || cur === undefined || typeof cur !== 'object') {
+    return false;
+  }
+  return Object.hasOwn(cur, parts[parts.length - 1]); // NOSONAR
+}
+
+/**
+ * Evaluate a single path segment against `view`.
+ *
+ * Returns `'pass'` for non-formula segments (literal, interpolation) and for
+ * formulas whose condition is satisfied. Returns `'skip'` when a formula's
+ * condition fails. Throws on malformed segments (G-5) or missing vars (G-4).
+ *
+ * Semantics (from plan):
+ * - G-3 JS-truthy rule: `false`, `0`, `''`, `null`, `undefined` → falsy.
+ * - G-4 Missing var throws with var name + containing relPath.
+ * - `$ifn` inverts `$if`.
+ *
+ * @param {string} segment
+ * @param {Record<string, unknown>} view
+ * @param {string} [relPath] - Used to enrich error messages; optional.
+ * @returns {'pass' | 'skip'}
+ */
+export function evalFormula(segment, view, relPath) {
+  const c = classifySegment(segment);
+
+  if (c.kind === 'literal' || c.kind === 'interpolation') {
+    return 'pass';
+  }
+
+  if (c.kind === 'malformed') {
+    throw new Error(
+      relPath
+        ? `${c.reason} (in '${relPath}')`
+        : /** @type {string} */ (c.reason),
+    );
+  }
+
+  const varPath = /** @type {string} */ (c.var);
+
+  if (!hasNested(view, varPath)) {
+    const where = relPath ? ` in '${relPath}'` : '';
+    throw new Error(
+      `Path formula '${segment}'${where} references undefined view variable '${varPath}'`,
+    );
+  }
+
+  const value = getNested(view, varPath);
+  const truthy = Boolean(value);
+  const condition = c.kind === 'if-formula' ? truthy : !truthy;
+  return condition ? 'pass' : 'skip';
+}

package/src/engine/pathRenderer.js

@@ -1,23 +1,71 @@
 import path from 'node:path';
 
 import { getNested } from '../utils/object.js';
+import { classifySegment } from './pathSegment.js';
 
 /**
- * Render `${var}` placeholders in each segment of the relPath.
+ * Replace every `${var}` placeholder in a segment with the nested view value.
+ * Missing values render as empty strings (existing behavior, unchanged).
+ *
+ * @param {string} seg
+ * @param {Record<string, unknown>} view
+ * @returns {string}
+ */
+function expandInterpolations(seg, view) {
+  return seg.replaceAll(/\$\{([^}]+)\}/g, (_, expr) => {
+    const v = getNested(view, expr.trim());
+    return String(v ?? ''); // NOSONAR -- String conversion is intentional here
+  });
+}
+
+/**
+ * Render a single segment. Formulas are rejected in filename position (G-5);
+ * formulas in directory position are assumed pre-approved by the walker and
+ * collapse to an empty string (G-2). Malformed segments throw.
+ *
+ * @param {string} seg
+ * @param {boolean} isFilename
+ * @param {Record<string, unknown>} view
+ * @param {string} relPath
+ * @returns {string}
+ */
+function renderSegment(seg, isFilename, view, relPath) {
+  const c = classifySegment(seg);
+
+  if (c.kind === 'literal') {
+    return seg;
+  }
+  if (c.kind === 'interpolation') {
+    return expandInterpolations(seg, view);
+  }
+  if (c.kind === 'malformed') {
+    throw new Error(`${c.reason} (in '${relPath}')`);
+  }
+
+  // if-formula or ifn-formula
+  if (isFilename) {
+    throw new Error(
+      `Path formula '${seg}' is not allowed in a filename (directories only) — in '${relPath}'`,
+    );
+  }
+  return '';
+}
+
+/**
+ * Render all segments of `relPath`. `${var}` is expanded; `$if{var}` /
+ * `$ifn{var}` directory segments collapse to empty (the walker already
+ * decided inclusion). Filename-position formulas and malformed segments
+ * throw.
+ *
  * @param {string} relPath
  * @param {Record<string, unknown>} view
  * @returns {string}
  */
 export function renderPath(relPath, view) {
   const segments = relPath.split(path.sep);
-
-  const rendered = segments.map((seg) =>
-    //NOSONAR -- ignore S5842: Regular expression is safe here
-    seg.replace(/\$\{([^}]+)\}/g, (_, expr) => {
-      const v = getNested(view, expr.trim());
-      return String(v ?? '');
-    }),
+  const lastIdx = segments.length - 1;
+  const rendered = segments.map((seg, idx) =>
+    renderSegment(seg, idx === lastIdx, view, relPath),
   );
-
   return path.join(...rendered);
 }

package/src/engine/pathSegment.js

@@ -0,0 +1,49 @@
+/**
+ * @typedef {'literal' | 'interpolation' | 'if-formula' | 'ifn-formula' | 'malformed'} SegmentKind
+ */
+
+/**
+ * @typedef {object} SegmentClassification
+ * @property {SegmentKind} kind
+ * @property {string} [var] - Trimmed variable expression (if-formula / ifn-formula only).
+ * @property {string} [reason] - Human-readable reason (malformed only).
+ */
+
+const FORMULA_WHOLE = /^\$(if|ifn)\{([^}]+)\}$/;
+const FORMULA_SUBSTR = /\$ifn?\{/;
+const INTERPOLATION = /\$\{[^}]+\}/;
+
+/**
+ * Classify a single path segment.
+ *
+ * Pure and total — never throws. Callers dispatch on the returned `kind`.
+ *
+ * Kinds:
+ * - `if-formula`   — whole segment matches `$if{var}`;  `.var` holds the trimmed expression.
+ * - `ifn-formula`  — whole segment matches `$ifn{var}`; `.var` holds the trimmed expression.
+ * - `malformed`    — contains `$if{` or `$ifn{` but is not a whole-segment formula; `.reason` describes the violation.
+ * - `interpolation` — contains one or more `${var}` placeholders.
+ * - `literal`      — none of the above.
+ *
+ * @param {string} segment
+ * @returns {SegmentClassification}
+ */
+export function classifySegment(segment) {
+  const m = FORMULA_WHOLE.exec(segment);
+  if (m) {
+    return {
+      kind: m[1] === 'if' ? 'if-formula' : 'ifn-formula',
+      var: m[2].trim(),
+    };
+  }
+  if (FORMULA_SUBSTR.test(segment)) {
+    return {
+      kind: 'malformed',
+      reason: `formulas must be whole segments in directory positions, one per segment: got '${segment}'`,
+    };
+  }
+  if (INTERPOLATION.test(segment)) {
+    return { kind: 'interpolation' };
+  }
+  return { kind: 'literal' };
+}