@nci-gis/js-tmpl 0.0.1 → 0.1.1

package/src/engine/renderDirectory.js

@@ -8,6 +8,63 @@ import { registerPartials } from './partials.js';
 import { renderPath } from './pathRenderer.js';
 import { walkTemplateTree } from './treeWalker.js';
 
+/**
+ * Throw if `target` is not strictly inside `outDir` — a `${var}` value such
+ * as `../x` must never write outside the output directory.
+ *
+ * @param {string} target
+ * @param {string} outDir
+ * @param {string} relPath - Template path, for the error message
+ * @param {string} rendered - Rendered path, for the error message
+ */
+function assertInsideOutDir(target, outDir, relPath, rendered) {
+  const rel = path.relative(path.resolve(outDir), path.resolve(target));
+  const escapes =
+    rel === '' || rel.split(path.sep)[0] === '..' || path.isAbsolute(rel);
+  if (escapes) {
+    const vars = [...relPath.matchAll(/\$\{([^}]+)\}/g)].map((m) => m[1]);
+    throw new Error(
+      `Template '${relPath}' renders to '${rendered}', which is outside outDir '${outDir}'.\n` +
+        (vars.length ? `Check the values of: ${vars.join(', ')}. ` : '') +
+        "Path values must not contain '..' segments.",
+    );
+  }
+}
+
+/**
+ * Map every template to its output path before anything is rendered or
+ * written, so an escaping path or two templates sharing a target fail
+ * before the first file is touched.
+ *
+ * @param {Array<{ relPath: string, absPath: string }>} files
+ * @param {import('../types.js').TemplateConfig} cfg
+ * @returns {Array<{ file: { relPath: string, absPath: string }, target: string }>}
+ */
+function planTargets(files, cfg) {
+  const { outDir, view, extname } = cfg;
+  /** @type {Map<string, string>} */
+  const owners = new Map();
+
+  return files.map((file) => {
+    const rendered = renderPath(file.relPath, view).replace(
+      new RegExp(`${extname}$`),
+      '',
+    );
+    const target = path.join(outDir, rendered);
+    assertInsideOutDir(target, outDir, file.relPath, rendered);
+
+    const owner = owners.get(target);
+    if (owner) {
+      throw new Error(
+        `Templates '${owner}' and '${file.relPath}' both render to '${rendered}'.\n` +
+          'Each output file must come from exactly one template; check the path values.',
+      );
+    }
+    owners.set(target, file.relPath);
+    return { file, target };
+  });
+}
+
 /**
  * Main rendering orchestrator.
  * @param {import('../types.js').TemplateConfig} cfg
@@ -15,21 +72,15 @@ import { walkTemplateTree } from './treeWalker.js';
  * @returns {Promise<void>}
  */
 export async function renderDirectory(cfg, hbs) {
-  const { templateDir, partialsDir, outDir, view, extname } = cfg;
+  const { templateDir, partialsDir, view, extname } = cfg;
 
   hbs = hbs || Handlebars.create();
   await registerPartials(partialsDir, extname, hbs);
 
-  const files = await walkTemplateTree(templateDir, extname);
-
-  for (const file of files) {
-    const relRendered = renderPath(file.relPath, view);
-    const target = path.join(
-      outDir,
-      relRendered.replace(new RegExp(`${extname}$`), ''),
-    );
+  const files = await walkTemplateTree(templateDir, { ext: extname, view });
 
-    const content = await renderContent(file.absPath, view, hbs);
+  for (const { file, target } of planTargets(files, cfg)) {
+    const content = await renderContent(file.absPath, view, hbs, file.relPath);
 
     await ensureDir(path.dirname(target));
     await writeFileSafe(target, content);

package/src/engine/treeWalker.js

@@ -1,14 +1,44 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
 
+import { evalFormula } from './pathFormula.js';
+
+/**
+ * True when a directory's basename is a path formula that evaluates to skip
+ * against `view`. Subtree pruning happens here — the walker short-circuits
+ * before any `readdir`.
+ *
+ * @param {string} rel - Relative path from the walk root (empty = root itself)
+ * @param {Record<string, unknown> | undefined} view
+ * @returns {boolean}
+ */
+function shouldSkipSubtree(rel, view) {
+  if (!rel || view === undefined) {
+    return false;
+  }
+  return evalFormula(path.basename(rel), view, rel) === 'skip';
+}
+
 /**
  * BFS async folder walker.
+ *
+ * When `view` is provided, directory segments that match path-formula syntax
+ * (`$if{var}` / `$ifn{var}`) are evaluated against the view; failing formulas
+ * prune the subtree before any filesystem descent (early-exit — no
+ * `stat`/`readdir` on skipped paths).
+ *
  * @param {string} rootDir
- * @param {string} [ext]
- * @param {Array<string | RegExp>} [ignore]
+ * @param {(string | { ext?: string, view?: Record<string, unknown> })} [optsOrExt]
+ *   Options object, or a bare `ext` string for back-compat.
  * @returns {Promise<import('../types.js').TemplateFile[]>}
  */
-export async function walkTemplateTree(rootDir, ext = '.hbs', ignore = []) {
+export async function walkTemplateTree(rootDir, optsOrExt) {
+  const opts =
+    typeof optsOrExt === 'string' ? { ext: optsOrExt } : optsOrExt || {};
+  const ext = opts.ext ?? '.hbs';
+  const view = opts.view;
+
+  /** @type {import('../types.js').TemplateFile[]} */
   const results = [];
   const queue = [''];
 
@@ -18,11 +48,11 @@ export async function walkTemplateTree(rootDir, ext = '.hbs', ignore = []) {
     const stat = await fs.stat(abs);
 
     if (stat.isDirectory()) {
+      if (shouldSkipSubtree(rel, view)) {
+        continue;
+      }
       const items = (await fs.readdir(abs)).sort();
       for (const name of items) {
-        if (ignore.some((i) => matchIgnore(name, i))) {
-          continue;
-        }
         queue.push(rel ? path.join(rel, name) : name);
       }
     } else if (path.extname(abs) === ext) {
@@ -32,12 +62,3 @@ export async function walkTemplateTree(rootDir, ext = '.hbs', ignore = []) {
 
   return results;
 }
-
-/**
- * @param {string} name
- * @param {string | RegExp} rule
- * @returns {boolean}
- */
-function matchIgnore(name, rule) {
-  return rule instanceof RegExp ? rule.test(name) : rule === name;
-}

package/src/index.js

@@ -1,2 +1,3 @@
 export * from './config/resolver.js';
+export * from './engine/helpers.js';
 export * from './engine/renderDirectory.js';

package/src/types.js

@@ -10,6 +10,7 @@
  * @property {string} [valuesDir]
  * @property {string[]} [envKeys]
  * @property {string} [envPrefix]
+ * @property {boolean} [verbose] - CLI only: print stack traces on error
  */
 
 /**

package/src/utils/namespacing.js

@@ -0,0 +1,92 @@
+import path from 'node:path';
+
+/**
+ * Valid namespace segment: letters, digits, underscore (matches Handlebars
+ * bare-identifier convention and the partials system's historical rule).
+ */
+export const SEGMENT_RE = /^\w+$/;
+
+/**
+ * Match a "@name" flatten marker at any position in the relative path.
+ * Root-independent: scan-root choice does not change the outcome, because
+ * the marker is detected wherever it appears in the chain.
+ */
+const FLATTEN_SEGMENT_RE = /^@\w+$/;
+
+/**
+ * Throw a clear error when a namespace segment contains invalid characters.
+ *
+ * @param {string[]} segments - Chain as produced by `deriveNamespace`.
+ * @param {string} filePath - Absolute or repo-relative path, for the error message.
+ * @param {string} [label='namespace'] - Noun used in the error message (e.g. "partial name").
+ */
+export function assertValidSegments(segments, filePath, label = 'namespace') {
+  if (!SEGMENT_RE.test(segments.join(''))) {
+    throw new Error(
+      `Invalid ${label} segment '${segments.join('>')}' in ${filePath} — only alphanumeric and underscore allowed`,
+    );
+  }
+}
+
+/**
+ * Throw a clear error when two files resolve to the same namespace key.
+ *
+ * @param {Map<string, string>} seen - Key → absolute path of the first file that claimed it.
+ * @param {string} key - The colliding namespace (dot-joined chain or single name).
+ * @param {string} filePath - Absolute path of the second file.
+ * @param {string} rootDir - The scan root, used to produce relative paths in the error.
+ * @param {string} [label='namespace'] - Noun used in the error message (e.g. "partial name").
+ */
+export function assertNoDuplicate(
+  seen,
+  key,
+  filePath,
+  rootDir,
+  label = 'namespace',
+) {
+  const existing = seen.get(key);
+  if (existing) {
+    const rel1 = path.relative(rootDir, existing);
+    const rel2 = path.relative(rootDir, filePath);
+    throw new Error(
+      `Duplicate ${label} '${key}' — registered by both:\n` +
+        `  - ${rel1}\n` +
+        `  - ${rel2}\n` +
+        `Use namespaced directories to avoid collisions.`,
+    );
+  }
+  seen.set(key, filePath);
+}
+
+/**
+ * Derive a namespace chain from a relative file path.
+ *
+ * Rules:
+ * - Extension is stripped from the final segment.
+ * - If any segment in the chain matches `^@\w+$` (a flatten marker), the chain
+ *   collapses to `[basename]` — the file contributes at top level of view /
+ *   partial registry, regardless of where the `@name` appears. This is the
+ *   **root-independent** flatten rule: scanning `values/` vs `values/env/`
+ *   yields the same namespace for `values/env/@overrides/app.yaml`.
+ * - Otherwise, the chain is the directory path split by `path.sep`, with the
+ *   final file's extension trimmed.
+ *
+ * The function does not validate segments — that's `assertValidSegments`'
+ * job, called by the scan helpers that consume this chain.
+ *
+ * @param {object} args
+ * @param {string} args.relPath - Relative path from the scan root.
+ * @param {string} args.ext - Extension to strip from the basename (include the dot, e.g. `.yaml`).
+ * @returns {string[]} The derived namespace chain.
+ */
+export function deriveNamespace({ relPath, ext }) {
+  const trimmed = relPath.endsWith(ext)
+    ? relPath.slice(0, -ext.length)
+    : relPath;
+  const segments = trimmed.split(path.sep);
+
+  if (segments.some((s) => FLATTEN_SEGMENT_RE.test(s))) {
+    return [/** @type {string} */ (segments.at(-1))];
+  }
+  return segments;
+}

package/bin/js-tmpl

@@ -1,3 +0,0 @@
-#!/usr/bin/env bash
-# CLI entry point for js-tmpl
-node "$(dirname "$0")/../src/cli/main.js" "$@"