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

package/src/engine/pathRenderer.js

@@ -1,20 +1,71 @@
-import path from "node:path";
+import path from 'node:path';
 
-import { getNested } from "../utils/object.js";
+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' };
+}

package/src/engine/renderDirectory.js

@@ -1,29 +1,35 @@
-import path from "node:path";
+import path from 'node:path';
 
-import { ensureDir, writeFileSafe } from "../utils/fs.js";
-import { renderContent } from "./contentRenderer.js";
-import { registerPartials } from "./partials.js";
-import { renderPath } from "./pathRenderer.js";
-import { walkTemplateTree } from "./treeWalker.js";
+import Handlebars from 'handlebars';
+
+import { ensureDir, writeFileSafe } from '../utils/fs.js';
+import { renderContent } from './contentRenderer.js';
+import { registerPartials } from './partials.js';
+import { renderPath } from './pathRenderer.js';
+import { walkTemplateTree } from './treeWalker.js';
 
 /**
  * Main rendering orchestrator.
+ * @param {import('../types.js').TemplateConfig} cfg
+ * @param {typeof import('handlebars')} [hbs] - Optional Handlebars instance (creates an isolated one if omitted)
+ * @returns {Promise<void>}
  */
-export async function renderDirectory(cfg) {
+export async function renderDirectory(cfg, hbs) {
   const { templateDir, partialsDir, outDir, view, extname } = cfg;
 
-  await registerPartials(partialsDir, extname);
+  hbs = hbs || Handlebars.create();
+  await registerPartials(partialsDir, extname, hbs);
 
-  const files = await walkTemplateTree(templateDir, extname);
+  const files = await walkTemplateTree(templateDir, { ext: extname, view });
 
   for (const file of files) {
     const relRendered = renderPath(file.relPath, view);
     const target = path.join(
       outDir,
-      relRendered.replace(new RegExp(`${extname}$`), "")
+      relRendered.replace(new RegExp(`${extname}$`), ''),
     );
 
-    const content = await renderContent(file.absPath, view);
+    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,22 +1,58 @@
-import fs from "node:fs/promises";
-import path from "node:path";
+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?: 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 = [""];
+  const queue = [''];
 
   while (queue.length) {
-    const rel = queue.shift();
+    const rel = /** @type {string} */ (queue.shift());
     const abs = path.join(rootDir, rel);
     const stat = await fs.stat(abs);
 
     if (stat.isDirectory()) {
-      const items = await fs.readdir(abs);
+      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) {
@@ -26,7 +62,3 @@ export async function walkTemplateTree(rootDir, ext = ".hbs", ignore = []) {
 
   return results;
 }
-
-function matchIgnore(name, rule) {
-  return rule instanceof RegExp ? rule.test(name) : rule === name;
-}

package/src/index.js

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

package/src/types.js

@@ -0,0 +1,30 @@
+/**
+ * @typedef {object} CliArgs
+ * @property {string} [command]
+ * @property {string} [templateDir]
+ * @property {string} [valuesFile]
+ * @property {string} [outDir]
+ * @property {string} [partialsDir]
+ * @property {string} [configFile]
+ * @property {string} [extname]
+ * @property {string} [valuesDir]
+ * @property {string[]} [envKeys]
+ * @property {string} [envPrefix]
+ */
+
+/**
+ * @typedef {object} TemplateConfig
+ * @property {string} templateDir
+ * @property {string} partialsDir
+ * @property {string} outDir
+ * @property {string} extname
+ * @property {Record<string, unknown>} view
+ */
+
+/**
+ * @typedef {object} TemplateFile
+ * @property {string} absPath
+ * @property {string} relPath
+ */
+
+export {}; //NOSONAR

package/src/utils/fs.js

@@ -1,5 +1,5 @@
-import fs from "node:fs/promises";
-import path from "node:path";
+import fs from 'node:fs/promises';
+import path from 'node:path';
 
 /** Safe mkdir -p
  * @param {string} dir Directory path to create
@@ -13,7 +13,7 @@ export async function ensureDir(dir) {
  * @param {string} content Content to write
  */
 export async function writeFileSafe(file, content) {
-  await fs.writeFile(file, content, "utf8");
+  await fs.writeFile(file, content, 'utf8');
 }
 
 /** Resolve path relative to cwd
@@ -35,7 +35,8 @@ export function resolvePath(p, cwd = process.cwd()) {
  * @returns {string} Absolute path.
  */
 export function safeResolvePath(...segments) {
-  const isAbsolute = segments ? segments[0] && path.isAbsolute(segments[0]) : false;
+  const isAbsolute =
+    segments.length > 0 && segments[0] && path.isAbsolute(segments[0]);
   if (isAbsolute) {
     return path.resolve(...segments);
   }

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/src/utils/object.js

@@ -1,10 +1,15 @@
 /**
  * Retrieve nested value: getNested(obj, "a.b.c")
+ * @param {Record<string, unknown>} obj
+ * @param {string} key
+ * @returns {unknown}
  */
 export function getNested(obj, key) {
-  console.log("getNested", obj, key);
-  
   return key
-    .split(".")
-    .reduce((acc, k) => (acc?.[k] ?? undefined), obj);
+    .split('.')
+    .reduce(
+      (/** @type {unknown} */ acc, /** @type {string} */ k) =>
+        /** @type {Record<string, unknown>} */ (acc)?.[k] ?? undefined,
+      obj,
+    );
 }