@nci-gis/js-tmpl 0.0.1-beta.2 → 0.1.0

package/src/config/resolver.js

@@ -1,78 +1,84 @@
-import path from "node:path";
-import process from "node:process";
+import path from 'node:path';
+import process from 'node:process';
 
-import { DEFAULTS } from "./defaults.js";
-import { loadProjectConfig,loadYamlOrJson } from "./loader.js";
-import { buildView } from "./view.js";
+import { DEFAULTS } from './defaults.js';
+import { loadProjectConfig, loadYamlOrJson } from './loader.js';
+import { scanValuePartials } from './valuePartials.js';
+import { buildView, pickEnv } from './view.js';
 
 /**
- * Resolve valuesFile path based on valuesDir
- * @param {string} valuesFile - The values file name or path
- * @param {string} valuesDir - Values directory (may be empty string)
- * @param {string} cwd - Current working directory
- * @returns {string} Absolute path to values file
+ * C-1 — throw if the resolved `valuesFile` sits inside the resolved
+ * `valuesDir`. A file loaded both as root and as a value partial would
+ * produce ambiguous collisions.
+ *
+ * @param {string} valuesFileAbs
+ * @param {string} valuesDirAbs
  */
-function resolveValuesFilePath(valuesFile, valuesDir, cwd) {
-  // If absolute, use as-is
-  if (path.isAbsolute(valuesFile)) {
-    return valuesFile;
-  }
-
-  // If valuesDir is set (truthy), use it as base
-  if (valuesDir) {
-    const absoluteValuesDir = path.isAbsolute(valuesDir)
-      ? valuesDir
-      : path.join(cwd, valuesDir);
-    return path.join(absoluteValuesDir, valuesFile);
+function assertValuesFileNotInside(valuesFileAbs, valuesDirAbs) {
+  const rel = path.relative(valuesDirAbs, valuesFileAbs);
+  const inside = rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+  if (inside) {
+    throw new Error(
+      `valuesFile '${valuesFileAbs}' is inside valuesDir '${valuesDirAbs}'.\n` +
+        `Move the file out, or drop valuesDir.`,
+    );
   }
-
-  // Otherwise, resolve from cwd
-  return path.join(cwd, valuesFile);
 }
 
 /**
- * Resolve final config using:
- * defaults < projectConfig < cliArgs
+ * Resolve final config using: defaults < projectConfig < cliArgs.
+ *
+ * Value sources (all optional per VP-5, VP-6, VP-8):
+ * - `valuesFile` loaded into top-level view keys.
+ * - `valuesDir` scanned via `scanValuePartials` into a namespaced tree.
+ * - Allowlisted env vars under `view.env.*`.
  *
- * @param {object} cli - CLI arguments
- * @param {string} cwd - Current working directory
- * @returns {object} - Resolved configuration
+ * Collision rules C-1, C-2, C-3 apply and surface as hard errors.
+ *
+ * @param {import('../types.js').CliArgs} cli
+ * @param {string} [cwd]
+ * @returns {import('../types.js').TemplateConfig}
  */
 export function resolveConfig(cli, cwd = process.cwd()) {
   const projectConfig = loadProjectConfig(cwd, cli.configFile);
+  const mergedConfig = { ...DEFAULTS, ...projectConfig, ...cli };
 
-  const mergedConfig = {
-    ...DEFAULTS,
-    ...projectConfig,
-    ...cli,
-  };
-
+  /** @param {string} p */
   const abs = (p) => (path.isAbsolute(p) ? p : path.join(cwd, p));
 
-  // Validate valuesFile is provided
-  if (!mergedConfig.valuesFile) {
-    throw new Error(
-      'Missing required configuration: valuesFile\n' +
-      'Provide via:\n' +
-      '  - CLI: --values path/to/values.yaml\n' +
-      '  - Config: valuesFile: "path/to/values.yaml" in js-tmpl.config.yaml'
-    );
+  const valuesFileAbs = mergedConfig.valuesFile
+    ? abs(mergedConfig.valuesFile)
+    : '';
+  const valuesDirAbs = mergedConfig.valuesDir
+    ? abs(mergedConfig.valuesDir)
+    : '';
+
+  if (valuesFileAbs && valuesDirAbs) {
+    assertValuesFileNotInside(valuesFileAbs, valuesDirAbs);
   }
 
-  // Resolve path - simple logic based on valuesDir presence
-  const valuesFilePath = resolveValuesFilePath(
-    mergedConfig.valuesFile,
-    mergedConfig.valuesDir,
-    cwd
-  );
+  const rootValues = valuesFileAbs ? loadYamlOrJson(valuesFileAbs) : {};
+  const partials = valuesDirAbs ? scanValuePartials(valuesDirAbs) : {};
 
-  const values = loadYamlOrJson(valuesFilePath);
+  const hasEnvConfig = mergedConfig.envKeys?.length || mergedConfig.envPrefix;
+  const env = hasEnvConfig
+    ? pickEnv({
+        keys: mergedConfig.envKeys || [],
+        prefix: mergedConfig.envPrefix || '',
+      })
+    : {};
 
   return {
     templateDir: abs(mergedConfig.templateDir),
-    partialsDir: abs(mergedConfig.partialsDir),
+    partialsDir: mergedConfig.partialsDir ? abs(mergedConfig.partialsDir) : '',
     outDir: abs(mergedConfig.outDir),
     extname: mergedConfig.extname,
-    view: buildView(values),
+    view: buildView({
+      rootValues,
+      partials,
+      env,
+      valuesFile: valuesFileAbs || '<unset>',
+      valuesDir: valuesDirAbs || '<unset>',
+    }),
   };
 }

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,6 +1,126 @@
-export function buildView(values, env = process.env) {
+/**
+ * @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.
+ *
+ * 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).
+ *
+ * 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(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 {
-    ...values,
-    env,
+    ...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.',
+    );
+  }
+}
+
+/**
+ * Pick environment variables by explicit keys and/or prefix.
+ *
+ * @param {object} options
+ * @param {string[]} options.keys - Explicit key names to include.
+ * @param {string} options.prefix - Include all vars starting with this prefix.
+ * @param {Record<string, string | undefined>} [source] - Env source (default: process.env).
+ * @returns {Record<string, string>}
+ */
+export function pickEnv({ keys = [], prefix = '' }, source = process.env) {
+  /** @type {Record<string, string>} */
+  const result = {};
+
+  for (const k of keys) {
+    if (k in source) {
+      result[k] = /** @type {string} */ (source[k]);
+    }
+  }
+
+  if (prefix) {
+    for (const k of Object.keys(source)) {
+      if (k.startsWith(prefix)) {
+        result[k] = /** @type {string} */ (source[k]);
+      }
+    }
+  }
+
+  return result;
+}

package/src/engine/contentRenderer.js

@@ -1,12 +1,29 @@
-import fs from "node:fs/promises";
+import fs from 'node:fs/promises';
+import path from 'node:path';
 
-import Handlebars from "handlebars";
+import Handlebars from 'handlebars';
 
 /**
- * Render template file with Handlebars & view object.
+ * 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 {string} [relPath] - Relative path (from templateDir), used in error messages.
+ * @returns {Promise<string>}
  */
-export async function renderContent(filePath, view) {
-  const raw = await fs.readFile(filePath, "utf8");
-  const compile = Handlebars.compile(raw);
-  return compile(view);
+export async function renderContent(filePath, view, hbs, relPath) {
+  const raw = await fs.readFile(filePath, 'utf8');
+  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/partials.js

@@ -1,41 +1,89 @@
-import fs from "node:fs/promises";
-import path from "node:path";
+import fs from 'node:fs/promises';
 
-import Handlebars from "handlebars";
+import {
+  assertNoDuplicate,
+  assertValidSegments,
+  deriveNamespace,
+} from '../utils/namespacing.js';
 
 /**
- * Register partials from a directory.
- * - root partials use prefix "_"
- * - group partials under "@group"
+ * 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
+ * @returns {{ name: string, source: string }}
  */
-export async function registerPartials(partialsDir, ext = ".hbs") {
-  const entries = await fs.readdir(partialsDir, { withFileTypes: true });
+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 }>>}
+ */
+async function scanPartialFiles(partialsDir, ext) {
+  const allFiles = await fs.readdir(partialsDir, { recursive: true });
+
+  return allFiles
+    .filter((f) => f.endsWith(ext))
+    .map((f) => processPartialFile(partialsDir, ext, f));
+}
+
+/**
+ * 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 abs = path.join(partialsDir, entry.name);
-
-    if (entry.isDirectory()) {
-      // handle namespacing
-      if (entry.name.startsWith("@")) {
-        const group = entry.name.slice(1);
-        const groupFiles = await fs.readdir(abs);
-
-        for (const f of groupFiles) {
-          if (!f.endsWith(ext)) {continue;}
-          const key = path.basename(f, ext);
-          const name = `${group}.${key}`;
-          const content = await fs.readFile(path.join(abs, f), "utf8");
-          Handlebars.registerPartial(name, content);
-        }
-      }
-      continue;
-    }
-
-    // root partial
-    if (entry.name.startsWith("_") && entry.name.endsWith(ext)) {
-      const content = await fs.readFile(abs, "utf8");
-      const key = entry.name.slice(1, -ext.length);
-      Handlebars.registerPartial(key, content);
-    }
+    assertNoDuplicate(
+      seen,
+      entry.name,
+      entry.source,
+      partialsDir,
+      'partial name',
+    );
+  }
+}
+
+/**
+ * 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)
+ * - `@<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.
+ *
+ * @param {string} partialsDir - Path to partials directory
+ * @param {string} ext - Template file extension (e.g. ".hbs")
+ * @param {import('handlebars')} hbs - Handlebars instance to register partials on
+ */
+export async function registerPartials(partialsDir, ext, hbs) {
+  if (!partialsDir) {
+    return;
+  }
+
+  const allPartials = await scanPartialFiles(partialsDir, ext);
+
+  checkDuplicates(allPartials, partialsDir);
+
+  for (const p of allPartials) {
+    const content = await fs.readFile(p.source, 'utf8');
+    hbs.registerPartial(p.name, content);
   }
 }

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';
+}