mandrel 1.57.0

package/.agents/scripts/lib/qa/resolve-selection.js

@@ -0,0 +1,373 @@
+/**
+ * resolve-selection.js — scenario-selection resolver for the agent-driven
+ * QA harness (Epic #3214, Story #3296).
+ *
+ * The harness is invoked with a single selector that scopes a sweep to a
+ * concrete set of `.feature` files (and, for tag selectors, the specific
+ * scenarios within them) under the contract's `featureRoot`. This module
+ * turns one of three selector shapes into that concrete set:
+ *
+ *   - **feature id** — `{ kind: 'feature', id: 'login' }` resolves to the
+ *     single `.feature` file whose path stem (basename without the
+ *     `.feature` extension) equals the id, or whose `featureRoot`-relative
+ *     POSIX path (with or without the extension) equals the id. Matching is
+ *     exact and case-insensitive; ambiguous ids (more than one match) throw.
+ *
+ *   - **tag expression** — `{ kind: 'tag', expression: '@smoke and not @wip' }`
+ *     resolves to the scenario set whose tag list satisfies the boolean
+ *     expression. The expression grammar is the cucumber-common subset:
+ *     `@tag` atoms, `and` / `or` / `not` operators (case-insensitive), and
+ *     parentheses. A scenario inherits no implicit tags; only the tags the
+ *     scanner attached to it (feature-level + scenario-level, as collected
+ *     by `parseFeatureBody`) participate.
+ *
+ *   - **domain** — `{ kind: 'domain', name: 'billing' }` resolves to every
+ *     scenario under the `featureRoot`-relative subdirectory `name`. A
+ *     domain is a first-level (or nested) directory grouping beneath the
+ *     feature root; the selector matches any scenario whose file lives at
+ *     or below `<featureRoot>/<name>/`.
+ *
+ * Determinism is load-bearing — the QA harness re-runs the same selector
+ * across sweeps and must scope the identical scenario set each time. All
+ * outputs are sorted by `(file, line)` so the order never depends on
+ * filesystem iteration order.
+ *
+ * This module is pure resolution: it does no browser work, reads no config
+ * beyond the `featureRoot` passed in, and never mutates state. The harness
+ * workflow (Story #3297) consumes the resolved set; this layer only answers
+ * "which scenarios does this selector name?".
+ */
+
+import path from 'node:path';
+
+import { listFeatureFiles, scanBddScenarios } from '../bdd-scenario-scanner.js';
+
+/**
+ * Normalise a path to POSIX separators so `featureRoot`-relative matching
+ * behaves identically on Windows and POSIX hosts.
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+function toPosix(p) {
+  return p.split(path.sep).join('/');
+}
+
+/**
+ * Compute a scenario's `featureRoot`-relative POSIX path. Used by the
+ * feature-id and domain matchers so selectors are written against the
+ * stable, repo-relative shape rather than absolute worktree paths.
+ *
+ * @param {string} featureRoot - Absolute path to the feature root.
+ * @param {string} file - Absolute path to a `.feature` file.
+ * @returns {string} POSIX-style path relative to `featureRoot`.
+ */
+function relFromRoot(featureRoot, file) {
+  return toPosix(path.relative(featureRoot, file));
+}
+
+/**
+ * Strip the trailing `.feature` extension (case-insensitive) from a
+ * relative path, leaving the path stem the feature-id selector matches on.
+ *
+ * @param {string} relPath
+ * @returns {string}
+ */
+function stripFeatureExt(relPath) {
+  return relPath.replace(/\.feature$/i, '');
+}
+
+// ---------------------------------------------------------------------------
+// Tag-expression evaluation
+// ---------------------------------------------------------------------------
+
+/**
+ * Classify a single matched lexeme into a token. `@tag` atoms keep their
+ * raw value; `(` / `)` / `and` / `or` / `not` produce structural tokens.
+ * Anything else is a malformed expression and throws.
+ *
+ * @param {string} raw
+ * @returns {{ type: string, value?: string }}
+ */
+function classifyToken(raw) {
+  if (raw === '(' || raw === ')') {
+    return { type: raw };
+  }
+  if (raw.startsWith('@')) {
+    return { type: 'tag', value: raw };
+  }
+  const lower = raw.toLowerCase();
+  if (lower === 'and' || lower === 'or' || lower === 'not') {
+    return { type: lower };
+  }
+  throw new Error(
+    `[resolve-selection] unknown operator "${raw}" in tag expression`,
+  );
+}
+
+/**
+ * Tokenise a cucumber-style tag expression into a flat token stream.
+ * Recognised tokens: `(`, `)`, `and`, `or`, `not`, and `@tag` atoms.
+ * Whitespace separates tokens; parentheses need no surrounding space.
+ *
+ * @param {string} expression
+ * @returns {Array<{ type: string, value?: string }>}
+ */
+function tokenizeTagExpression(expression) {
+  const tokens = [];
+  const re = /\s*(\(|\)|@[\w-]+|[A-Za-z]+)/g;
+  let lastIndex = 0;
+  for (
+    let match = re.exec(expression);
+    match !== null;
+    match = re.exec(expression)
+  ) {
+    // Guard against runs of unmatched garbage between tokens.
+    const between = expression.slice(lastIndex, match.index).trim();
+    if (between.length > 0) {
+      throw new Error(
+        `[resolve-selection] unexpected token "${between}" in tag expression`,
+      );
+    }
+    lastIndex = re.lastIndex;
+    tokens.push(classifyToken(match[1]));
+  }
+  const tail = expression.slice(lastIndex).trim();
+  if (tail.length > 0) {
+    throw new Error(
+      `[resolve-selection] unexpected token "${tail}" in tag expression`,
+    );
+  }
+  return tokens;
+}
+
+/**
+ * Recursive-descent parser for the tag-expression grammar:
+ *
+ *   expr   := term  ( 'or'  term  )*
+ *   term   := factor( 'and' factor)*
+ *   factor := 'not' factor | '(' expr ')' | tag
+ *
+ * Produces a predicate `(tagSet: Set<string>) => boolean`. Tag atoms match
+ * case-insensitively against the scenario's tag set (which carries the
+ * leading `@`).
+ *
+ * @param {string} expression
+ * @returns {(tags: Set<string>) => boolean}
+ */
+export function parseTagExpression(expression) {
+  if (typeof expression !== 'string' || expression.trim().length === 0) {
+    throw new Error(
+      '[resolve-selection] tag expression must be a non-empty string',
+    );
+  }
+  const tokens = tokenizeTagExpression(expression);
+  let pos = 0;
+
+  const peek = () => tokens[pos];
+  const next = () => tokens[pos++];
+
+  function parseExpr() {
+    let left = parseTerm();
+    while (peek() && peek().type === 'or') {
+      next();
+      const right = parseTerm();
+      const l = left;
+      left = (tags) => l(tags) || right(tags);
+    }
+    return left;
+  }
+
+  function parseTerm() {
+    let left = parseFactor();
+    while (peek() && peek().type === 'and') {
+      next();
+      const right = parseFactor();
+      const l = left;
+      left = (tags) => l(tags) && right(tags);
+    }
+    return left;
+  }
+
+  function parseFactor() {
+    const tok = peek();
+    if (!tok) {
+      throw new Error('[resolve-selection] unexpected end of tag expression');
+    }
+    if (tok.type === 'not') {
+      next();
+      const operand = parseFactor();
+      return (tags) => !operand(tags);
+    }
+    if (tok.type === '(') {
+      next();
+      const inner = parseExpr();
+      const close = next();
+      if (!close || close.type !== ')') {
+        throw new Error('[resolve-selection] missing closing parenthesis');
+      }
+      return inner;
+    }
+    if (tok.type === 'tag') {
+      next();
+      const wanted = tok.value.toLowerCase();
+      return (tags) => tags.has(wanted);
+    }
+    throw new Error(
+      `[resolve-selection] unexpected token "${tok.type}" in tag expression`,
+    );
+  }
+
+  const predicate = parseExpr();
+  if (pos !== tokens.length) {
+    throw new Error('[resolve-selection] trailing tokens in tag expression');
+  }
+  return predicate;
+}
+
+/**
+ * Build a lower-cased tag `Set` for a scanned scenario so the predicate can
+ * test membership case-insensitively.
+ *
+ * @param {{ tags?: string[] }} scenario
+ * @returns {Set<string>}
+ */
+function tagSetOf(scenario) {
+  return new Set((scenario.tags ?? []).map((t) => t.toLowerCase()));
+}
+
+// ---------------------------------------------------------------------------
+// Public resolver
+// ---------------------------------------------------------------------------
+
+/**
+ * Sort scanned scenarios deterministically by `(file, line)`.
+ *
+ * @param {Array<{ file: string, line: number }>} scenarios
+ * @returns {Array<object>}
+ */
+function sortScenarios(scenarios) {
+  return scenarios
+    .slice()
+    .sort((a, b) =>
+      a.file === b.file ? a.line - b.line : a.file < b.file ? -1 : 1,
+    );
+}
+
+/**
+ * Resolve a selector into a concrete scenario set under `featureRoot`.
+ *
+ * @param {object} args
+ * @param {string} args.featureRoot - Absolute path to the contract's
+ *   `.feature` root. The harness prefers the `qa.featureRoot` contract
+ *   value over auto-detection; this resolver takes it as given.
+ * @param {object} args.selector - One of the three selector shapes:
+ *   `{ kind: 'feature', id }`, `{ kind: 'tag', expression }`, or
+ *   `{ kind: 'domain', name }`.
+ * @param {{ logger?: object }} [opts]
+ * @returns {{ kind: string, featureRoot: string, files: string[], scenarios: Array<object> }}
+ *   `files` is the deduped, sorted set of absolute `.feature` paths the
+ *   selection touches; `scenarios` is the sorted scenario rows (for tag
+ *   selection it is the satisfying subset, for feature/domain it is every
+ *   scenario in the matched files).
+ */
+export function resolveSelection(args = {}, opts = {}) {
+  const { featureRoot, selector } = args;
+  if (typeof featureRoot !== 'string' || featureRoot.length === 0) {
+    throw new Error('[resolve-selection] featureRoot is required');
+  }
+  if (!selector || typeof selector !== 'object') {
+    throw new Error('[resolve-selection] selector is required');
+  }
+
+  switch (selector.kind) {
+    case 'feature':
+      return resolveFeature(featureRoot, selector, opts);
+    case 'tag':
+      return resolveTag(featureRoot, selector, opts);
+    case 'domain':
+      return resolveDomain(featureRoot, selector, opts);
+    default:
+      throw new Error(
+        `[resolve-selection] unknown selector kind "${selector.kind}"`,
+      );
+  }
+}
+
+function resolveFeature(featureRoot, selector, opts) {
+  const id = selector.id;
+  if (typeof id !== 'string' || id.trim().length === 0) {
+    throw new Error(
+      '[resolve-selection] feature selector requires a non-empty id',
+    );
+  }
+  const want = stripFeatureExt(toPosix(id.trim())).toLowerCase();
+  const files = listFeatureFiles([featureRoot], opts);
+  const matched = files.filter((file) => {
+    const rel = relFromRoot(featureRoot, file);
+    const relStem = stripFeatureExt(rel).toLowerCase();
+    const baseStem = stripFeatureExt(path.basename(rel)).toLowerCase();
+    return relStem === want || baseStem === want;
+  });
+  if (matched.length === 0) {
+    throw new Error(
+      `[resolve-selection] no .feature file matched feature id "${id}" under ${featureRoot}`,
+    );
+  }
+  if (matched.length > 1) {
+    throw new Error(
+      `[resolve-selection] feature id "${id}" is ambiguous; matched ${matched.length} files: ${matched
+        .map((f) => relFromRoot(featureRoot, f))
+        .join(', ')}. Qualify with a featureRoot-relative path.`,
+    );
+  }
+  const all = scanBddScenarios({ featureRoots: [featureRoot], ...opts });
+  const scenarios = sortScenarios(all.filter((s) => s.file === matched[0]));
+  return {
+    kind: 'feature',
+    featureRoot,
+    files: matched,
+    scenarios,
+  };
+}
+
+function resolveTag(featureRoot, selector, opts) {
+  const predicate = parseTagExpression(selector.expression);
+  const all = scanBddScenarios({ featureRoots: [featureRoot], ...opts });
+  const scenarios = sortScenarios(all.filter((s) => predicate(tagSetOf(s))));
+  const files = Array.from(new Set(scenarios.map((s) => s.file))).sort();
+  return {
+    kind: 'tag',
+    featureRoot,
+    files,
+    scenarios,
+  };
+}
+
+function resolveDomain(featureRoot, selector, opts) {
+  const name = selector.name;
+  if (typeof name !== 'string' || name.trim().length === 0) {
+    throw new Error(
+      '[resolve-selection] domain selector requires a non-empty name',
+    );
+  }
+  // Normalise to a trailing-slash POSIX prefix so "billing" matches
+  // "billing/checkout.feature" but not "billing-archive/x.feature".
+  const prefix = `${toPosix(name.trim()).replace(/\/+$/, '')}/`;
+  const all = scanBddScenarios({ featureRoots: [featureRoot], ...opts });
+  const scenarios = sortScenarios(
+    all.filter((s) => relFromRoot(featureRoot, s.file).startsWith(prefix)),
+  );
+  if (scenarios.length === 0) {
+    throw new Error(
+      `[resolve-selection] no scenarios found under domain "${name}" in ${featureRoot}`,
+    );
+  }
+  const files = Array.from(new Set(scenarios.map((s) => s.file))).sort();
+  return {
+    kind: 'domain',
+    featureRoot,
+    files,
+    scenarios,
+  };
+}

package/.agents/scripts/lib/runtime-deps/ensure-installed.js

@@ -0,0 +1,100 @@
+/**
+ * runtime-deps/ensure-installed — fail-fast guard for framework runtime deps.
+ *
+ * Importing this module runs the dependency-presence check as a side effect:
+ * if any package in `.agents/runtime-deps.json`'s `dependencies` block cannot
+ * be resolved from the framework's `node_modules` (i.e. the consumer's
+ * install is missing, empty, or stale), it prints an actionable remediation
+ * message and exits non-zero — *before* the entry point's heavier imports
+ * reach the first `import 'ajv'` and throw an opaque `ERR_MODULE_NOT_FOUND`
+ * (Story #3432).
+ *
+ * Why a side-effect-on-import (rather than a function the entry point calls):
+ * ESM evaluates a module's imports in source order, depth-first, *before* the
+ * module body runs. A function call in `main()` would therefore execute only
+ * after the third-party-importing sibling modules had already been evaluated
+ * (and already thrown). By making each target entry point's *first* import a
+ * side-effect import of this module, the check runs first and short-circuits a
+ * broken install with a clear message.
+ *
+ * The guard only ever exits when a *required* dependency is genuinely
+ * missing. With a healthy install (CI, tests, normal runs) it is a no-op, so
+ * it is safe for entry points imported by the test suite. `optionalDependencies`
+ * are intentionally not checked — they sit behind graceful-degradation paths.
+ *
+ * Set `MANDREL_SKIP_DEP_PREFLIGHT=1` to disable the side effect (escape hatch
+ * for tooling that imports an entry point in an environment that deliberately
+ * lacks the framework deps).
+ */
+
+import { createRequire } from 'node:module';
+import { loadRuntimeDepsManifest } from './manifest.js';
+import {
+  checkRuntimeDeps,
+  detectPackageManager,
+  formatMissingDepsMessage,
+} from './preflight.js';
+
+// `require.resolve` bound to this module's location walks `node_modules`
+// upward from `.agents/scripts/lib/runtime-deps/` to the consumer root —
+// exactly the resolution path the framework's third-party imports follow.
+const frameworkRequire = createRequire(import.meta.url);
+
+/**
+ * Run the dependency-presence check and, on failure, write the remediation
+ * message and exit. Seams (`requireResolve`, `cwd`, `stderr`, `exit`,
+ * `manifest`) make it fully testable without touching the real process.
+ *
+ * @param {{
+ *   requireResolve?: (specifier: string) => string,
+ *   cwd?: string,
+ *   stderr?: { write: (s: string) => void },
+ *   exit?: (code: number) => void,
+ *   manifest?: { required: string[] },
+ * }} [opts]
+ * @returns {{ ok: boolean, missing: string[] }}
+ */
+export function ensureRuntimeDepsInstalled(opts = {}) {
+  const {
+    requireResolve = (s) => frameworkRequire.resolve(s),
+    cwd = process.cwd(),
+    stderr = process.stderr,
+    exit = process.exit,
+    manifest = safeLoadManifest(),
+  } = opts;
+
+  // A manifest we cannot read is a packaging defect the drift test owns —
+  // never let the guard kill an otherwise-healthy process over it.
+  if (!manifest) return { ok: true, missing: [] };
+
+  const result = checkRuntimeDeps({
+    required: manifest.required,
+    resolve: requireResolve,
+  });
+  if (result.ok) return result;
+
+  const packageManager = detectPackageManager(cwd);
+  stderr.write(
+    `${formatMissingDepsMessage(result.missing, { root: cwd, packageManager })}\n`,
+  );
+  exit(1);
+  return result;
+}
+
+/**
+ * Load the manifest, swallowing a read/parse failure to `null` so the guard
+ * stays inert on a packaging defect (see `ensureRuntimeDepsInstalled`).
+ *
+ * @returns {{ required: string[] } | null}
+ */
+function safeLoadManifest() {
+  try {
+    return loadRuntimeDepsManifest();
+  } catch {
+    return null;
+  }
+}
+
+if (process.env.MANDREL_SKIP_DEP_PREFLIGHT !== '1') {
+  ensureRuntimeDepsInstalled();
+}

package/.agents/scripts/lib/runtime-deps/manifest.js

@@ -0,0 +1,96 @@
+/**
+ * runtime-deps/manifest — loader for the framework's vendored runtime-dep SSOT.
+ *
+ * `.agents/runtime-deps.json` is the single source of truth for the
+ * third-party npm packages the framework scripts import at runtime
+ * (Story #3432). It ships *inside* `.agents/` so it travels with the
+ * `mandrel` package into consumer projects. This module is the only reader of that
+ * file — the bootstrap seeder (`project-bootstrap.js`), the preflight guard
+ * (`ensure-installed.js`), and the import-vs-manifest drift test all derive
+ * their dependency lists from `loadRuntimeDepsManifest()` so there is exactly
+ * one place the list lives.
+ *
+ * The loader stays on Node builtins only (`node:fs`, `node:path`,
+ * `node:url`) so it can run inside the preflight guard *before* any
+ * third-party package is imported — that is the whole point of the guard.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Absolute path to the vendored manifest. `HERE` is
+ * `.agents/scripts/lib/runtime-deps/`; the manifest sits at the `.agents/`
+ * root, three directories up.
+ */
+export const MANIFEST_PATH = path.resolve(
+  HERE,
+  '..',
+  '..',
+  '..',
+  'runtime-deps.json',
+);
+
+/**
+ * @typedef {object} RuntimeDepsManifest
+ * @property {Record<string,string>} dependencies        — required runtime
+ *   packages (name → semver range). Fail-fast enforced by the preflight.
+ * @property {Record<string,string>} optionalDependencies — packages imported
+ *   behind graceful-degradation paths; declared but never preflight-blocked.
+ * @property {string[]} required — `Object.keys(dependencies)`.
+ * @property {string[]} optional — `Object.keys(optionalDependencies)`.
+ * @property {Set<string>} declared — union of required + optional names.
+ */
+
+/**
+ * Read, parse, and structurally validate the runtime-deps manifest.
+ *
+ * Throws a clear `Error` when the file is missing or malformed so the
+ * drift test and bootstrap seeder fail loudly on a packaging regression,
+ * rather than silently treating the dependency set as empty.
+ *
+ * @param {string} [manifestPath=MANIFEST_PATH]
+ * @returns {RuntimeDepsManifest}
+ */
+export function loadRuntimeDepsManifest(manifestPath = MANIFEST_PATH) {
+  let raw;
+  try {
+    raw = fs.readFileSync(manifestPath, 'utf8');
+  } catch (err) {
+    throw new Error(
+      `runtime-deps manifest not found at ${manifestPath}: ${err?.message ?? err}`,
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw new Error(
+      `runtime-deps manifest at ${manifestPath} is not valid JSON: ${err?.message ?? err}`,
+    );
+  }
+  const dependencies = parsed.dependencies;
+  if (!dependencies || typeof dependencies !== 'object') {
+    throw new Error(
+      `runtime-deps manifest at ${manifestPath} is missing a "dependencies" object`,
+    );
+  }
+  const optionalDependencies =
+    parsed.optionalDependencies &&
+    typeof parsed.optionalDependencies === 'object'
+      ? parsed.optionalDependencies
+      : {};
+  return {
+    dependencies,
+    optionalDependencies,
+    required: Object.keys(dependencies),
+    optional: Object.keys(optionalDependencies),
+    declared: new Set([
+      ...Object.keys(dependencies),
+      ...Object.keys(optionalDependencies),
+    ]),
+  };
+}

package/.agents/scripts/lib/runtime-deps/preflight.js

@@ -0,0 +1,78 @@
+/**
+ * runtime-deps/preflight — pure helpers for the dependency-presence check.
+ *
+ * These functions hold no side effects so they are unit-testable in
+ * isolation: `checkRuntimeDeps` takes an injected `resolve` seam,
+ * `detectPackageManager` takes an injected `exists` seam, and
+ * `formatMissingDepsMessage` is a pure string builder. The side-effecting
+ * guard that wires them to the real process lives in `ensure-installed.js`.
+ *
+ * Builtins only — this module runs *before* any third-party package is
+ * imported, so importing a third-party here would defeat its own purpose.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Resolve each required package via the injected `resolve` seam and collect
+ * the ones that fail. `resolve` is typically `require.resolve` bound to the
+ * framework module location; it throws `MODULE_NOT_FOUND` when a package is
+ * absent from the resolvable `node_modules`.
+ *
+ * @param {{ required: string[], resolve: (specifier: string) => string }} opts
+ * @returns {{ ok: boolean, missing: string[] }}
+ */
+export function checkRuntimeDeps({ required, resolve }) {
+  const missing = [];
+  for (const dep of required) {
+    try {
+      resolve(dep);
+    } catch {
+      missing.push(dep);
+    }
+  }
+  return { ok: missing.length === 0, missing };
+}
+
+/**
+ * Detect the consumer's package manager from lockfile presence so the
+ * remediation message names the right install command. Defaults to `npm`.
+ * Mirrors `bootstrap/project-bootstrap.js#detectPackageManager` but stays
+ * decoupled (and seam-injectable) so the preflight imports nothing heavy.
+ *
+ * @param {string} root
+ * @param {(p: string) => boolean} [exists=fs.existsSync]
+ * @returns {'pnpm'|'yarn'|'npm'}
+ */
+export function detectPackageManager(root, exists = fs.existsSync) {
+  if (exists(path.join(root, 'pnpm-lock.yaml'))) return 'pnpm';
+  if (exists(path.join(root, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+/** Map a detected package manager to its install command. */
+function installCommand(packageManager) {
+  if (packageManager === 'pnpm') return 'pnpm install';
+  if (packageManager === 'yarn') return 'yarn install';
+  return 'npm install';
+}
+
+/**
+ * Build the actionable remediation message naming the missing packages and
+ * the consumer's install command. This is what replaces the opaque raw
+ * `ERR_MODULE_NOT_FOUND` stack trace.
+ *
+ * @param {string[]} missing
+ * @param {{ root: string, packageManager: 'pnpm'|'yarn'|'npm' }} opts
+ * @returns {string}
+ */
+export function formatMissingDepsMessage(missing, { root, packageManager }) {
+  return [
+    'Framework runtime dependencies are not installed.',
+    `Missing from node_modules/: ${missing.join(', ')}.`,
+    `The .agents/ framework scripts require these packages (declared in ` +
+      `.agents/runtime-deps.json) to be installed in this repository.`,
+    `Run \`${installCommand(packageManager)}\` in ${root}, then re-run this command.`,
+  ].join('\n');
+}