mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/audit-suite/selector.js

@@ -6,16 +6,19 @@
  * without importing upward from a top-level CLI file.
  *
  * Pure (modulo `gitSpawn`) — exposed helpers are:
- *   - matchesFilePattern    — single file × single glob (picomatch with `dot`)
- *   - matchesAnyFilePattern — file list × pattern list, short-circuiting
- *   - selectAudits          — main entry; reads audit-rules.json, runs `git
- *                             diff --name-only`, applies keyword + glob rules.
+ *   - matchesFilePattern         — single file × single glob (picomatch, `dot`)
+ *   - matchesAnyFilePattern      — file list × pattern list, short-circuiting
+ *   - selectSensitivePathClasses — change set × the manifest's `sensitivePaths`
+ *                                  block; the review-depth derivation's matcher
+ *   - selectAudits               — main entry; reads audit-rules.json, runs `git
+ *                                  diff --name-only`, applies keyword + glob
+ *                                  rules.
  *
  * All rule-matching lives here; the former `select-audits.js` CLI wrapper
  * was retired in #4482 (consumers call `selectAudits` via the barrel).
  */
 
-import { readFileSync } from 'node:fs';
+import { readdirSync, readFileSync } from 'node:fs';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import picomatch from 'picomatch';
@@ -109,10 +112,10 @@ export const LENS_TIERS = Object.freeze(['local', 'cumulative', 'global']);
  * @throws {Error} When the manifest cannot be read or parsed.
  */
 function readAuditRulesSync() {
-  const { agentSettings } = resolveConfig();
+  const config = resolveConfig();
   const rulesPath = path.join(
     PROJECT_ROOT,
-    getPaths({ agentSettings }).schemasRoot,
+    getPaths(config).schemasRoot,
     'audit-rules.json',
   );
   try {
@@ -160,7 +163,7 @@ export function resolveLensTier(lens) {
  * every path) matches every change set here, so its concern is verified at
  * BOTH innermost tiers — the
  * write-time checklist threading and this Story-scope lens pass — and excluded
- * from Epic close (a local lens is dropped by {@link selectEpicCloseLenses}).
+ * from the retired Epic-close roster (local lenses stay Story-scope only).
  * A local lens with an empty `filePatterns` list matches nothing here, so a
  * diff matching no local lens's patterns yields an empty roster and adds no
  * lens work.
@@ -197,6 +200,50 @@ export function selectLocalLenses({
   return selected;
 }
 
+/**
+ * Select the sensitive-path classes a change set touches, from the
+ * `sensitivePaths` block of [`audit-rules.json`](../../../schemas/audit-rules.json).
+ *
+ * This is the matcher behind the close-time review-depth derivation
+ * (`review-depth.js#deriveChangeLevel`, Story #4542): a change set intersecting
+ * any registered class's globs is *observably* sensitive — auth, a migration, a
+ * billing path — and earns a deep pass however narrow the diff is. The classes
+ * and their globs live in the manifest next to the lens `triggers.filePatterns`
+ * precisely so an operator can extend them without a code change, and matching
+ * runs through the same {@link matchesAnyFilePattern} picomatch machinery rather
+ * than a second matcher with its own glob semantics.
+ *
+ * An empty change set, an absent `sensitivePaths` block, or a class whose globs
+ * match nothing all contribute no class — the caller then resolves depth from
+ * diff width alone.
+ *
+ * Pure over its injected seam: `injectedRules` skips the manifest disk read.
+ * Selection order follows the manifest's declaration order, which is
+ * deterministic.
+ *
+ * @param {{
+ *   changedFiles?: string[],
+ *   injectedRules?: { sensitivePaths?: Record<string, { filePatterns?: string[] }> },
+ * }} [params]
+ * @returns {string[]} The matched class names, in manifest order.
+ */
+export function selectSensitivePathClasses({
+  changedFiles,
+  injectedRules,
+} = {}) {
+  const files = Array.isArray(changedFiles) ? changedFiles : [];
+  if (files.length === 0) return [];
+
+  const rules = injectedRules ?? readAuditRulesSync();
+  const matched = [];
+  for (const [name, entry] of Object.entries(rules.sensitivePaths ?? {})) {
+    if (matchesAnyFilePattern(entry?.filePatterns ?? [], files)) {
+      matched.push(name);
+    }
+  }
+  return matched;
+}
+
 /**
  * Resolve the consumer's navigability route globs from the resolved config.
  * Reads `delivery.quality.navigability.routeGlobs` — the route-tree SSOT the
@@ -221,9 +268,9 @@ export function resolveNavigabilityRouteGlobs(config) {
  * `false` (the unconfigured no-op), so the existing change-set-scoped lens
  * selection is unchanged.
  *
- * This is a pure predicate over the SAME inputs the existing risk-routed-lens
- * union already consumes; the caller folds its result into `riskRoutedAudits`
- * via the existing `unionAudits` — no new routing machinery is added.
+ * A pure predicate over a change set — the same input {@link selectAudits} and
+ * {@link selectLocalLenses} already match against. The caller unions its result
+ * into the lens roster it is assembling; no new routing machinery is added.
  *
  * @param {{ changedFiles?: string[], config?: object|null }} params
  * @returns {boolean}
@@ -234,6 +281,206 @@ export function routesNavigabilityLens({ changedFiles, config } = {}) {
   return matchesAnyFilePattern(globs, changedFiles ?? []);
 }
 
+/**
+ * Package names (or scope/name segments of them) that declare a **web
+ * rendering surface**. Matched against the consumer's root `package.json`
+ * `dependencies` + `devDependencies` keys, segment-wise, so `@angular/core`
+ * matches via `angular` and `@remix-run/react` via `react`.
+ */
+const WEB_FRAMEWORK_PACKAGES = Object.freeze([
+  'react',
+  'next',
+  'vue',
+  'svelte',
+  'sveltekit',
+  'astro',
+  'nuxt',
+  'remix',
+  'remix-run',
+  'gatsby',
+  'angular',
+]);
+
+/** File extensions whose presence in the source tree implies a web surface. */
+const WEB_ASSET_EXTENSIONS = Object.freeze(['.html', '.css', '.jsx', '.tsx']);
+
+/**
+ * Directories the web-surface file scan never descends into. `node_modules` is
+ * the load-bearing one (a dependency's bundled `.css` says nothing about the
+ * consumer's own surface); the test directories are excluded because a fixture
+ * `.html` is a test artifact, not a shipped page.
+ */
+const WEB_SCAN_SKIP_DIRS = Object.freeze([
+  'node_modules',
+  '.git',
+  '.worktrees',
+  'dist',
+  'build',
+  'out',
+  'coverage',
+  'temp',
+  'tmp',
+  'tests',
+  'test',
+  '__tests__',
+  '__mocks__',
+  'spec',
+  'e2e',
+  'fixtures',
+]);
+
+/** Scan bounds — the probe is a cheap heuristic, not an exhaustive crawl. */
+const WEB_SCAN_MAX_DEPTH = 6;
+const WEB_SCAN_MAX_ENTRIES = 4000;
+
+/**
+ * Process-lifetime memo for the filesystem half of the web-surface probe,
+ * keyed by project root. The config half ({@link resolveNavigabilityRouteGlobs})
+ * is a free object read and is deliberately NOT memoized, so a caller passing a
+ * different config never reads a stale answer.
+ *
+ * @type {Map<string, boolean>}
+ */
+const _webSurfaceFsCache = new Map();
+
+/** Test-only: drop the memo so a fixture root can be re-probed after edits. */
+export function _resetWebSurfaceCache() {
+  _webSurfaceFsCache.clear();
+}
+
+/**
+ * True when the root `package.json` declares a web-framework dependency.
+ * Returns `null` — *indeterminate* — when the manifest exists but cannot be
+ * read or parsed; the caller fails open on that (see {@link hasWebSurface}).
+ * A genuinely absent manifest (`ENOENT`) is determinate: there is no
+ * declaration, so there is no signal, and the file scan gets its turn.
+ *
+ * @param {string} root
+ * @returns {boolean|null}
+ */
+function declaresWebFramework(root) {
+  let raw;
+  try {
+    raw = readFileSync(path.join(root, 'package.json'), 'utf8');
+  } catch (err) {
+    if (err?.code === 'ENOENT') return false;
+    return null;
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  const names = [
+    ...Object.keys(pkg?.dependencies ?? {}),
+    ...Object.keys(pkg?.devDependencies ?? {}),
+  ];
+  return names.some((name) =>
+    name
+      .replace(/^@/, '')
+      .split('/')
+      .some((segment) => WEB_FRAMEWORK_PACKAGES.includes(segment)),
+  );
+}
+
+/**
+ * True when a bounded scan of the source tree finds a web asset file
+ * (`.html` / `.css` / `.jsx` / `.tsx`) outside the skipped directories.
+ * Returns `null` — *indeterminate* — when the root itself is unreadable, or
+ * when the scan exhausted its entry budget without finding one: a truncated
+ * scan genuinely did not finish looking, and reporting "no web surface" from
+ * a half-walked tree would silently drop lens coverage.
+ *
+ * Uses `readdirSync(withFileTypes)` rather than `git ls-files` — a filesystem
+ * check suffices, and shelling out to git would make the probe cost a process
+ * spawn on every selection.
+ *
+ * @param {string} root
+ * @returns {boolean|null}
+ */
+function scanForWebAssets(root) {
+  let budget = WEB_SCAN_MAX_ENTRIES;
+  const queue = [{ dir: root, depth: 0 }];
+  let rootRead = false;
+
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      // A single unreadable subdirectory is skipped: a permissions oddity is
+      // far likelier than an entire web surface hiding behind it. An
+      // unreadable ROOT is a different story — see below.
+      if (dir === root) return null;
+      continue;
+    }
+    if (dir === root) rootRead = true;
+
+    for (const entry of entries) {
+      if (budget-- <= 0) return null; // truncated ⇒ indeterminate
+      if (entry.isDirectory()) {
+        if (WEB_SCAN_SKIP_DIRS.includes(entry.name)) continue;
+        if (depth + 1 <= WEB_SCAN_MAX_DEPTH) {
+          queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
+        }
+        continue;
+      }
+      if (WEB_ASSET_EXTENSIONS.includes(path.extname(entry.name))) return true;
+    }
+  }
+  return rootRead ? false : null;
+}
+
+/**
+ * Decide whether the project has a **web surface** — the applicability
+ * predicate behind the `target: "web"` gate in `audit-rules.json` (#4579).
+ *
+ * Mandrel is materialized into other projects, so this cannot be a property of
+ * *this* repository: a consumer with a real web surface MUST still get the web
+ * lenses. It is therefore derived from observables in the consumer's own
+ * checkout, and deliberately NOT from a new `.agentrc` key — a new key would
+ * have to be threaded through the runtime AJV (`lib/config-settings-schema*.js`)
+ * *and* the published mirror, and would make consumers hand-configure something
+ * already derivable.
+ *
+ * A project is web-capable when ANY of these hold:
+ *   1. `delivery.quality.navigability.routeGlobs` is configured — the existing
+ *      web signal the navigability lens already routes off.
+ *   2. The root `package.json` declares a web framework (react / next / vue /
+ *      svelte / astro / nuxt / remix / gatsby / angular).
+ *   3. A bounded source scan finds a `.html` / `.css` / `.jsx` / `.tsx` file
+ *      outside test directories.
+ *
+ * **Fail direction: OPEN.** When a signal is indeterminate — an unparseable
+ * `package.json`, an unreadable root, a scan that hit its entry budget — the
+ * project is treated as web-capable. A false positive costs one wasted lens
+ * run; a false negative silently drops audit coverage on a project that has a
+ * real web surface, and nothing downstream would ever report the omission.
+ * Wasted spend is recoverable; dropped coverage is not.
+ *
+ * @param {{ config?: object|null, projectRoot?: string }} [params]
+ * @returns {boolean}
+ */
+export function hasWebSurface({ config, projectRoot = PROJECT_ROOT } = {}) {
+  if (resolveNavigabilityRouteGlobs(config).length > 0) return true;
+
+  if (_webSurfaceFsCache.has(projectRoot)) {
+    return _webSurfaceFsCache.get(projectRoot);
+  }
+
+  const declared = declaresWebFramework(projectRoot);
+  // `null` is indeterminate, not false — fail open.
+  const result =
+    declared === null || declared === true
+      ? true
+      : scanForWebAssets(projectRoot) !== false;
+
+  _webSurfaceFsCache.set(projectRoot, result);
+  return result;
+}
+
 /**
  * Test a single filename against a single glob pattern using the project's
  * configured matcher semantics (`picomatch` with `dot: true`). Exported so
@@ -261,6 +508,16 @@ export function matchesAnyFilePattern(patterns, files) {
  * @param {number} params.ticketId
  * @param {string} params.gate
  * @param {import('../ITicketingProvider.js').ITicketingProvider} params.provider
+ * @param {string[]} [params.changedFiles]
+ *   The change set to select over, when the caller already knows it. Supplying
+ *   it skips the internal `git diff` entirely and `baseBranch` / `headRef` are
+ *   then unused. Callers whose change set is NOT the working tree's
+ *   `baseBranch...headRef` MUST pass this: the plan-run epilogue runs from the
+ *   main checkout *after* its Stories have merged, where any `main...HEAD`
+ *   range is empty by construction and selection would silently degrade to
+ *   keyword-only matching (Story #4571). An empty array is honoured as
+ *   "the set is known, and it is empty" — distinct from omitting the option,
+ *   which means "derive it from git".
  * @param {string} [params.baseBranch]
  * @param {string} [params.headRef]
  *   Git ref whose diff-against-`baseBranch` defines the change set. Defaults
@@ -284,6 +541,9 @@ export function matchesAnyFilePattern(patterns, files) {
  *   Test-only seam to drive the `--gate-mode` / `MANDREL_GATE_MODE=1`
  *   detection; production callers leave unset and `isGateMode` reads
  *   `process.argv` / `process.env`.
+ * @param {typeof hasWebSurface} [params.hasWebSurfaceFn]
+ *   Test-only seam overriding the web-surface probe behind the
+ *   `target: "web"` applicability gate. Production callers leave unset.
  *
  * Returns either the success envelope (`{ selectedAudits, ticketId, gate, context }`)
  * OR the degraded envelope (`{ ok: false, degraded: true, reason, detail }`)
@@ -294,18 +554,20 @@ export async function selectAudits({
   ticketId,
   gate,
   provider,
+  changedFiles: injectedChangedFiles,
   baseBranch = 'main',
   headRef = 'HEAD',
   injectedGitSpawn,
   gitTimeoutMsOverride,
   gateModeOpts,
+  hasWebSurfaceFn = hasWebSurface,
 }) {
-  const { agentSettings } = resolveConfig();
+  const config = resolveConfig();
   const timeoutMs = gitTimeoutMsOverride ?? DEFAULT_GIT_TIMEOUT_MS;
 
   const rulesPath = path.join(
     PROJECT_ROOT,
-    getPaths({ agentSettings }).schemasRoot,
+    getPaths(config).schemasRoot,
     'audit-rules.json',
   );
   let rulesData;
@@ -323,6 +585,14 @@ export async function selectAudits({
 
   const runGit = injectedGitSpawn ?? (async (...args) => gitSpawn(...args));
 
+  // A caller that already knows the change set supplies it, and no git ref is
+  // consulted at all — `baseBranch` / `headRef` describe a diff that is not
+  // being taken. The plan-run epilogue is the motivating caller (Story #4571):
+  // it resolves the run's landed diff from the Stories' squash-merges, and any
+  // `main...HEAD` range it could name from the main checkout post-land is
+  // empty by construction.
+  const hasInjectedChangedFiles = Array.isArray(injectedChangedFiles);
+
   // Resolve `headRef` to a commit before diffing. A non-default `headRef`
   // (Epic-mode callers pass `refs/heads/epic/<id>`) that the repo can't
   // resolve means the requested Epic's branch is not present in this
@@ -331,7 +601,7 @@ export async function selectAudits({
   // degraded signal instead of leaking the wrong scope. `HEAD` is always
   // resolvable in a valid repo, so the default-path callers skip the probe
   // cost on the common case.
-  if (headRef !== 'HEAD') {
+  if (!hasInjectedChangedFiles && headRef !== 'HEAD') {
     let resolved;
     try {
       resolved = await withTimeout(
@@ -358,18 +628,22 @@ export async function selectAudits({
     }
   }
 
-  let changedFiles = [];
+  let changedFiles = hasInjectedChangedFiles
+    ? injectedChangedFiles.map((f) => String(f).trim()).filter(Boolean)
+    : [];
   try {
-    const diff = await withTimeout(
-      runGit(
-        process.cwd(),
-        'diff',
-        '--name-only',
-        `${baseBranch}...${headRef}`,
-      ),
-      timeoutMs,
-      { label: 'select-audits git diff' },
-    );
+    const diff = hasInjectedChangedFiles
+      ? null
+      : await withTimeout(
+          runGit(
+            process.cwd(),
+            'diff',
+            '--name-only',
+            `${baseBranch}...${headRef}`,
+          ),
+          timeoutMs,
+          { label: 'select-audits git diff' },
+        );
     if (diff?.status === 0) {
       changedFiles = diff.stdout
         .split('\n')
@@ -393,16 +667,40 @@ export async function selectAudits({
 
   const selectedAudits = [];
 
+  // Resolved at most once per call, and only if a `target: "web"` lens
+  // actually clears its gate — a Node-only project must not pay a filesystem
+  // scan on a roster with no web lens in it.
+  let webSurfaceMemo = null;
+  const projectIsWebCapable = () => {
+    if (webSurfaceMemo === null) {
+      webSurfaceMemo = hasWebSurfaceFn({ config });
+    }
+    return webSurfaceMemo;
+  };
+
   for (const [auditName, ruleOpts] of Object.entries(rulesData.audits || {})) {
     const triggers = ruleOpts.triggers || {};
 
     const gateMatch = triggers.gates?.includes(gate);
     if (!gateMatch) continue;
 
+    // Target-applicability gate (#4579). A lens declaring `target: "web"`
+    // has nothing to read on a project with no web surface, yet still
+    // whole-word-matches ordinary prose — `audit-seo` fires on the `meta`
+    // inside every Story body's `<!-- meta: {...} -->` machine comment. The
+    // roster's own instruction is that the host MUST walk every listed lens,
+    // so an inapplicable entry is not just wasted spend: it teaches operators
+    // to ignore the MUST. An absent `target` means "always applicable", so no
+    // existing lens changes behaviour.
+    if (ruleOpts.target === 'web' && !projectIsWebCapable()) continue;
+
     const keywords = triggers.keywords || [];
     let keywordMatch = false;
     for (const kw of keywords) {
-      if (contentToSearch.includes(kw.toLowerCase())) {
+      // Whole-word match: a bare substring test selects lenses on accidental
+      // fragments ("ui" inside "requires", "auth" inside "author" — #4579).
+      const escaped = kw.toLowerCase().replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      if (new RegExp(`\\b${escaped}\\b`).test(contentToSearch)) {
         keywordMatch = true;
         break;
       }
@@ -430,8 +728,10 @@ export async function selectAudits({
       changedFilesCount: changedFiles.length,
       // The ref the change set was actually diffed against. Epic-mode callers
       // assert this matches the requested Epic branch (Story #3362) so a
-      // mis-pinned diff never reaches the audit-lens selector silently.
-      resolvedRef: headRef,
+      // mis-pinned diff never reaches the audit-lens selector silently. `null`
+      // on the injected path: no ref was diffed, and naming one would invite
+      // exactly that assertion to pass against a diff nobody took.
+      resolvedRef: hasInjectedChangedFiles ? null : headRef,
       ticketTitle: ticket.title,
     },
   };

package/.agents/scripts/lib/audit-to-stories/{seed-epic-from-findings.js → seed-from-findings.js}

@@ -1,17 +1,17 @@
 /**
- * lib/audit-to-stories/seed-epic-from-findings.js
+ * lib/audit-to-stories/seed-from-findings.js
  *
- * Build the `--idea`-shaped seed markdown that `/plan` Phase 1
- * consumes when the operator picks the Single-Epic grouping mode.
+ * Build the `/plan --seed`-shaped one-pager markdown that the audit-to-
+ * stories Single-plan grouping path emits for `/plan` to consume.
  *
- * The seed renders the canonical one-pager sections so the idea-refinement
- * skill can sharpen it without having to invent context:
+ * The seed renders the canonical one-pager sections so the authoring
+ * pass can sharpen it without having to invent context:
  *   - Problem Statement (aggregated severity profile)
  *   - Recommended Direction (rollup of recommendations by dimension)
  *   - Key Assumptions (carries the source-report links forward)
  *   - MVP Scope (the proposed Stories, one bullet per group)
- *   - Key Files (explicit file paths so /plan Phase 7 decompose
- *     has concrete anchors)
+ *   - Key Files (explicit file paths so `/plan` authoring has concrete
+ *     anchors)
  *   - Not Doing (out-of-scope items by convention)
  *
  * Pure: returns a string. The caller decides where to persist it.
@@ -112,14 +112,14 @@ function formatKeyAssumptions(sourceReports) {
  * @param {string[]} params.sourceReports — list of source report paths.
  * @returns {string}
  */
-export function buildEpicSeedMarkdown({ groups, findings, sourceReports }) {
+export function buildPlanSeedMarkdown({ groups, findings, sourceReports }) {
   if (
     !Array.isArray(groups) ||
     !Array.isArray(findings) ||
     !Array.isArray(sourceReports)
   ) {
     throw new Error(
-      'buildEpicSeedMarkdown: groups, findings, sourceReports must all be arrays',
+      'buildPlanSeedMarkdown: groups, findings, sourceReports must all be arrays',
     );
   }
   const problem = formatProblemStatement(findings);