@nci-gis/js-tmpl 0.0.1 → 0.1.0

package/README.md

@@ -78,10 +78,11 @@ js-tmpl will search for a project config file in **exactly these locations**, in
 
 Everything else must be **explicitly specified**:
 
-- ✅ **Values file** - Required via `--values` flag or `valuesFile` config
-- ✅ **Template directory** - Must be in config or defaults to `templates/`
-- ✅ **Output directory** - Must be in config or defaults to `dist/`
-- ✅ **Partials directory** - Must be in config; not loaded if omitted
+- ✅ **Values file** — Optional via `--values` flag or `valuesFile` config (VP-8)
+- ✅ **Values directory** — Optional via `--values-dir` flag or `valuesDir` config (VP-6)
+- ✅ **Template directory** — Must be in config or defaults to `templates/`
+- ✅ **Output directory** — Must be in config or defaults to `dist/`
+- ✅ **Partials directory** — Must be in config; not loaded if omitted
 
 ### Override Auto-Discovery
 
@@ -212,6 +213,22 @@ templates/
 → dist/production/config-my-app.yaml
 ```
 
+Use `$if{var}` / `$ifn{var}` as whole directory segments to conditionally
+include or skip files based on view data:
+
+```text
+templates/
+├── common.yaml.hbs
+├── $if{prod}/
+│   └── alerts.yaml.hbs          → written only when view.prod is truthy
+└── $ifn{prod}/
+    └── debug-panel.yaml.hbs     → written only when view.prod is falsy
+```
+
+Guards are directory-only, whole-segment, and throw loudly on missing
+variables. See [API docs](docs/API.md#path-guards--conditional-files) for
+the full semantics and rejected variants.
+
 ### Partial System
 
 Each render pass uses an isolated Handlebars instance. Directory structure maps to partial names:
@@ -242,7 +259,7 @@ Duplicate partial names throw an error. Names must be alphanumeric + underscore
 Think of js-tmpl as a function:
 
 ```text
-(input templates, data, config) → output files
+f(config, values/view, input templates) → files (output)
 ```
 
 There is no hidden state, no lifecycle, and no side effects.
@@ -256,16 +273,22 @@ js-tmpl render [options]
 
 ### Options
 
-| Option                   | Description                             | Default         |
-| ------------------------ | --------------------------------------- | --------------- |
-| `-c, --values FILE`      | Values file (YAML/JSON)                 | **Required**    |
-| `-t, --template-dir DIR` | Template directory                      | `templates`     |
-| `-o, --out DIR`          | Output directory                        | `dist`          |
-| `-p, --partials-dir DIR` | Partials directory                      | None (skipped)  |
-| `-x, --ext EXT`          | Template extension                      | `.hbs`          |
-| `--config-file FILE`     | Explicit config file                    | Auto-discovered |
-| `--env-keys KEYS`        | Comma-separated env var names to expose | None            |
-| `--env-prefix PREFIX`    | Auto-include env vars with this prefix  | None            |
+| Option                   | Description                              | Default         |
+| ------------------------ | ---------------------------------------- | --------------- |
+| `-c, --values FILE`      | Values file (`.yaml` / `.yml` / `.json`) | Optional        |
+| `--values-dir DIR`       | Value-partials root (namespaced by path) | Optional        |
+| `-t, --template-dir DIR` | Template directory                       | `templates`     |
+| `-o, --out DIR`          | Output directory                         | `dist`          |
+| `-p, --partials-dir DIR` | Partials directory                       | None (skipped)  |
+| `-x, --ext EXT`          | Template extension                       | `.hbs`          |
+| `--config-file FILE`     | Explicit config file                     | Auto-discovered |
+| `--env-keys KEYS`        | Comma-separated env var names to expose  | None            |
+| `--env-prefix PREFIX`    | Auto-include env vars with this prefix   | None            |
+
+Both `--values` and `--values-dir` are optional (VP-8, VP-6). If neither is
+supplied, `view` is `{ env: {...} }` only. Missing `{{var}}` in a template
+throws with the template's relative path and variable name (VP-9, strict
+mode).
 
 ### Examples of Usage
 
@@ -289,12 +312,14 @@ See [docs/API.md](docs/API.md) for the complete API reference — parameters, re
 
 ## Examples
 
-See [examples/yaml-templates/](examples/yaml-templates/) for a complete working example demonstrating:
-
-- Dynamic file paths with `${env.NODE_ENV}`
-- Handlebars features (loops, conditionals)
-- Root and namespaced partials
-- Multi-format output (YAML, Markdown)
+- [examples/yaml-templates/](examples/yaml-templates/) — complete walkthrough:
+  dynamic paths with `${env.NODE_ENV}`, Handlebars features (loops,
+  conditionals), root and namespaced partials, multi-format output.
+- [examples/path-guards/](examples/path-guards/) — conditional files via
+  `$if{var}` / `$ifn{var}` whole-segment path guards.
+- [examples/value-partials/](examples/value-partials/) — composing `view`
+  from multiple structured files via `--values-dir` (directory-as-namespace,
+  no merge, `@`-flatten escape).
 
 ## Testing
 
@@ -337,7 +362,7 @@ For security concerns, see [SECURITY.md](SECURITY.md).
 
 ## License
 
-MIT © pasxd245
+See [LICENSE](LICENSE).
 
 ## Learn More
 
@@ -354,3 +379,7 @@ MIT © pasxd245
 - [Examples](examples/) - Working examples and templates
 - [Issue Tracker](https://github.com/nci-gis/js-tmpl/issues) - Report bugs or request features
 - [NPM Package](https://www.npmjs.com/package/@nci-gis/js-tmpl) - Package registry
+
+## Transparency
+
+AI-assisted development (e.g., Claude Code, Copilot) was used for scaffolding and iteration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nci-gis/js-tmpl",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "The pure JavaScript templating engine that uses handlebars.",
   "type": "module",
   "bin": {
@@ -16,8 +16,12 @@
     "test": "node --test $(find tests -name '*.test.js')",
     "test:watch": "node --test --watch $(find tests -name '*.test.js')",
     "test:coverage": "node --experimental-test-coverage --test $(find tests -name '*.test.js')",
-    "format": "prettier --write src/ tests/",
-    "format:check": "prettier --check src/ tests/",
+    "format": "pnpm format:code && pnpm format:md",
+    "format:check": "pnpm format:code:check && pnpm format:md:check",
+    "format:code": "prettier --write src/ tests/",
+    "format:code:check": "prettier --check src/ tests/",
+    "format:md": "prettier --write \"*.md\" \"docs/**/*.md\" \"tests/**/*.md\" \"examples/**/*.md\"",
+    "format:md:check": "prettier --check \"*.md\" \"docs/**/*.md\" \"tests/**/*.md\" \"examples/**/*.md\"",
     "lint": "eslint src/ tests/",
     "lint:fix": "eslint src/ tests/ --fix",
     "build": "echo 'No build step required for pure JS library'",
@@ -62,6 +66,8 @@
     "js-yaml": "^4.1.1"
   },
   "devDependencies": {
+    "@commitlint/cli": "^20.5.0",
+    "@commitlint/config-conventional": "^20.5.0",
     "@eslint/js": "^9.39.2",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^25.5.2",

package/src/cli/args.js

@@ -32,6 +32,10 @@ export function parseArgs(args) {
         opts.valuesFile = args[++i];
         break;
 
+      case '--values-dir':
+        opts.valuesDir = args[++i];
+        break;
+
       case '-o':
       case '--out':
         opts.outDir = args[++i];

package/src/cli/usage.js

@@ -6,7 +6,8 @@ Commands:
 
 Options:
   -t, --template-dir <dir>   Template directory (default: templates)
-  -c, --values <file>        Values file (YAML or JSON) [required]
+  -c, --values <file>        Values file (.yaml / .yml / .json) — optional
+      --values-dir <dir>     Value-partials root, namespaced into view by path
   -o, --out <dir>            Output directory (default: dist)
   -p, --partials-dir <dir>   Partials directory
   -x, --ext <ext>            Template extension (default: .hbs)

package/src/config/resolver.js

@@ -3,71 +3,62 @@ import process from 'node:process';
 
 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 {import('../types.js').CliArgs} cli - CLI arguments
- * @param {string} [cwd] - Current working directory
- * @returns {import('../types.js').TemplateConfig} - 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)
+    : '';
 
-  // Resolve path - simple logic based on valuesDir presence
-  const valuesFilePath = resolveValuesFilePath(
-    mergedConfig.valuesFile,
-    mergedConfig.valuesDir,
-    cwd,
-  );
+  if (valuesFileAbs && valuesDirAbs) {
+    assertValuesFileNotInside(valuesFileAbs, valuesDirAbs);
+  }
 
-  const values = loadYamlOrJson(valuesFilePath);
+  const rootValues = valuesFileAbs ? loadYamlOrJson(valuesFileAbs) : {};
+  const partials = valuesDirAbs ? scanValuePartials(valuesDirAbs) : {};
 
   const hasEnvConfig = mergedConfig.envKeys?.length || mergedConfig.envPrefix;
   const env = hasEnvConfig
@@ -82,6 +73,12 @@ export function resolveConfig(cli, cwd = process.cwd()) {
     partialsDir: mergedConfig.partialsDir ? abs(mergedConfig.partialsDir) : '',
     outDir: abs(mergedConfig.outDir),
     extname: mergedConfig.extname,
-    view: buildView(values, env),
+    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,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/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' };
+}

package/src/engine/renderDirectory.js

@@ -20,7 +20,7 @@ export async function renderDirectory(cfg, hbs) {
   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);
@@ -29,7 +29,7 @@ export async function renderDirectory(cfg, hbs) {
       relRendered.replace(new RegExp(`${extname}$`), ''),
     );
 
-    const content = await renderContent(file.absPath, view, hbs);
+    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/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;
+}