mandrel 2.3.0 → 2.5.0

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

@@ -481,6 +481,194 @@ export function hasWebSurface({ config, projectRoot = PROJECT_ROOT } = {}) {
   return result;
 }
 
+/**
+ * Package names (or scope/name segments of them) that declare a **persistence
+ * layer** — ORMs and query builders that own a database schema. Matched
+ * segment-wise against the consumer's root `package.json` dependency keys, so
+ * `@prisma/client` matches via `prisma` and `@mikro-orm/core` via `mikro-orm`.
+ */
+const ORM_PACKAGES = Object.freeze([
+  'prisma',
+  'drizzle-orm',
+  'typeorm',
+  'sequelize',
+  'mongoose',
+  'knex',
+  'objection',
+  'kysely',
+  'mikro-orm',
+  'bookshelf',
+  'waterline',
+]);
+
+/** File extensions whose tracked presence implies a persistence schema. */
+const PERSISTENCE_SCHEMA_EXTENSIONS = Object.freeze(['.sql', '.prisma']);
+
+/** Directory basenames that name a schema-migrations directory. */
+const MIGRATION_DIR_NAMES = Object.freeze(['migrations', 'migrate']);
+
+/**
+ * Parent directory basenames that qualify a `migrations`/`migrate` directory as
+ * a **database** migrations directory rather than an unrelated one (e.g.
+ * Mandrel's own `lib/migrations/` of framework-version upgrade steps). A
+ * migrations directory only counts as a persistence marker when it sits under
+ * one of these conventional ORM/database parents.
+ */
+const DB_MIGRATION_PARENTS = Object.freeze([
+  'db',
+  'database',
+  'prisma',
+  'drizzle',
+  'supabase',
+  'sql',
+]);
+
+/**
+ * Process-lifetime memo for the filesystem half of the persistence probe,
+ * keyed by project root — the persistence-layer analogue of
+ * {@link _webSurfaceFsCache}.
+ *
+ * @type {Map<string, boolean>}
+ */
+const _persistenceFsCache = new Map();
+
+/** Test-only: drop the memo so a fixture root can be re-probed after edits. */
+export function _resetPersistenceLayerCache() {
+  _persistenceFsCache.clear();
+}
+
+/**
+ * True when the root `package.json` declares an ORM / query-builder dependency.
+ * Returns `null` — *indeterminate* — when the manifest exists but cannot be
+ * read or parsed (the caller fails open on that). A genuinely absent manifest
+ * (`ENOENT`) is determinate: there is no declaration, so the file scan gets its
+ * turn. Mirrors {@link declaresWebFramework}.
+ *
+ * @param {string} root
+ * @returns {boolean|null}
+ */
+function declaresOrmDependency(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) => ORM_PACKAGES.includes(segment)),
+  );
+}
+
+/**
+ * True when a bounded scan of the source tree finds a persistence-schema
+ * artifact: a tracked `.sql` / `.prisma` file, or a `migrations` / `migrate`
+ * directory sitting under a conventional database parent (`db/`, `prisma/`, …).
+ *
+ * Unlike the web-asset scan, a truncated or completed no-find scan resolves to
+ * **false** (not `null`): persistence artifacts live near the repo root by
+ * convention, so a bounded near-root scan that does not find one is strong
+ * evidence of absence — and it keeps a large ORM-less repo (Mandrel itself)
+ * determinately not-applicable regardless of tree size. Only an unreadable
+ * ROOT is indeterminate (`null`), which the caller fails open on.
+ *
+ * @param {string} root
+ * @returns {boolean|null}
+ */
+function scanForPersistenceArtifacts(root) {
+  let budget = WEB_SCAN_MAX_ENTRIES;
+  const queue = [{ dir: root, depth: 0 }];
+
+  while (queue.length > 0) {
+    const { dir, depth } = queue.shift();
+    let entries;
+    try {
+      entries = readdirSync(dir, { withFileTypes: true });
+    } catch {
+      if (dir === root) return null;
+      continue;
+    }
+
+    for (const entry of entries) {
+      if (budget-- <= 0) return false; // bounded near-root scan exhausted
+      if (entry.isDirectory()) {
+        if (WEB_SCAN_SKIP_DIRS.includes(entry.name)) continue;
+        if (
+          MIGRATION_DIR_NAMES.includes(entry.name) &&
+          DB_MIGRATION_PARENTS.includes(path.basename(dir))
+        ) {
+          return true;
+        }
+        if (depth + 1 <= WEB_SCAN_MAX_DEPTH) {
+          queue.push({ dir: path.join(dir, entry.name), depth: depth + 1 });
+        }
+        continue;
+      }
+      if (PERSISTENCE_SCHEMA_EXTENSIONS.includes(path.extname(entry.name))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+/**
+ * Decide whether the project has a **persistence layer** — the applicability
+ * predicate behind the `target: "data-model"` gate in `audit-rules.json`
+ * (Story #4633). The data-model lens reads ORM models, schema migrations, and
+ * seed data; a project with none of those has nothing for it to inspect, so the
+ * lens self-skips with an explicit not-applicable report rather than running to
+ * empty findings.
+ *
+ * Like {@link hasWebSurface}, this is derived from observables in the
+ * consumer's own checkout — Mandrel is materialized into other projects, so a
+ * consumer with a real database MUST still get the lens. A project has a
+ * persistence layer when ANY of these hold:
+ *   1. The root `package.json` declares an ORM / query-builder dependency
+ *      (prisma / drizzle / typeorm / sequelize / mongoose / knex / …).
+ *   2. A bounded source scan finds a tracked `.prisma` / `.sql` schema file.
+ *   3. A bounded source scan finds a `migrations` / `migrate` directory under a
+ *      conventional database parent (`db/`, `prisma/`, `drizzle/`, …).
+ *
+ * **Fail direction: OPEN.** When the ORM-dependency signal is indeterminate —
+ * an unparseable `package.json`, an unreadable root — the project is treated as
+ * having a persistence layer, for the same reason as the web probe: a wasted
+ * lens run is recoverable, silently dropped coverage is not. A determinate
+ * "no ORM dependency + no schema artifact found" (Mandrel's own shape) is a
+ * clean not-applicable.
+ *
+ * @param {{ config?: object|null, projectRoot?: string }} [params]
+ * @returns {boolean}
+ */
+export function hasPersistenceLayer({ projectRoot = PROJECT_ROOT } = {}) {
+  if (_persistenceFsCache.has(projectRoot)) {
+    return _persistenceFsCache.get(projectRoot);
+  }
+
+  const declared = declaresOrmDependency(projectRoot);
+  // `null` is indeterminate, not false — fail open.
+  const result =
+    declared === null || declared === true
+      ? true
+      : scanForPersistenceArtifacts(projectRoot) !== false;
+
+  _persistenceFsCache.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
@@ -500,6 +688,80 @@ export function matchesAnyFilePattern(patterns, files) {
   return files.some((file) => matchers.some((m) => m(file)));
 }
 
+/** Extensions the sibling-test predicate treats as production source code. */
+const SOURCE_CODE_EXTENSIONS = Object.freeze([
+  '.js',
+  '.mjs',
+  '.cjs',
+  '.jsx',
+  '.ts',
+  '.tsx',
+]);
+
+// biome-ignore lint/complexity/useRegexLiterals: constructor form keeps the MI walker able to score this module.
+const TEST_FILE_RE = new RegExp(String.raw`\.(test|spec)\.[cm]?[jt]sx?$`);
+// biome-ignore lint/complexity/useRegexLiterals: constructor form keeps the MI walker able to score this module.
+const TEST_DIR_RE = new RegExp(
+  String.raw`(^|/)(tests?|__tests__|spec|e2e|__mocks__)(/|$)`,
+);
+// biome-ignore lint/complexity/useRegexLiterals: constructor form keeps the MI walker able to score this module.
+const CODE_EXT_RE = new RegExp(String.raw`\.[cm]?[jt]sx?$`);
+
+/**
+ * True when `file` is a test/spec file — either by the `.test.` / `.spec.`
+ * infix or by living under a conventional test directory.
+ *
+ * @param {string} file
+ * @returns {boolean}
+ */
+function isTestFile(file) {
+  return TEST_FILE_RE.test(file) || TEST_DIR_RE.test(file);
+}
+
+/**
+ * The sibling stem of a path: its basename with any `.test` / `.spec` infix and
+ * the code extension stripped (`src/foo.test.js` and `src/foo.js` both → `foo`).
+ *
+ * @param {string} file
+ * @returns {string}
+ */
+function stemOf(file) {
+  const base = file.split('/').pop() ?? file;
+  return base.replace(TEST_FILE_RE, '').replace(CODE_EXT_RE, '');
+}
+
+/**
+ * The coverage-gap routing predicate behind the `sourceWithoutSiblingTest`
+ * trigger (Story #4628): a change set warrants the `audit-quality` lens when it
+ * touches at least one **production source** file whose **sibling test is not
+ * also in the change set**. This flips the historical (backwards) trigger that
+ * fired the coverage-gap detector on test-file changes — a diff that only edits
+ * tests has, if anything, *more* coverage, not less; the risk lives in source
+ * that shipped without a matching test.
+ *
+ * A source file's sibling is matched by stem (`src/foo.js` ↔ any changed
+ * `foo.test.js` / `foo.spec.js`, regardless of directory). Test-only diffs,
+ * doc/config-only diffs, and source diffs whose every file has a sibling test
+ * in the same change set all return `false` and route no quality lens.
+ *
+ * Pure over its input; no git, no disk.
+ *
+ * @param {string[]|null|undefined} changedFiles
+ * @returns {boolean}
+ */
+export function changeSetLacksSiblingTest(changedFiles) {
+  const files = (Array.isArray(changedFiles) ? changedFiles : []).filter(
+    (f) => typeof f === 'string' && f.length > 0,
+  );
+  const testStems = new Set(
+    files.filter((f) => isTestFile(f)).map((f) => stemOf(f)),
+  );
+  const sources = files.filter(
+    (f) => !isTestFile(f) && SOURCE_CODE_EXTENSIONS.includes(path.extname(f)),
+  );
+  return sources.some((src) => !testStems.has(stemOf(src)));
+}
+
 /**
  * Filter audits based on logic in audit-rules.json (validated against
  * audit-rules.schema.json).
@@ -561,6 +823,7 @@ export async function selectAudits({
   gitTimeoutMsOverride,
   gateModeOpts,
   hasWebSurfaceFn = hasWebSurface,
+  hasPersistenceLayerFn = hasPersistenceLayer,
 }) {
   const config = resolveConfig();
   const timeoutMs = gitTimeoutMsOverride ?? DEFAULT_GIT_TIMEOUT_MS;
@@ -667,15 +930,21 @@ 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 });
+  // Applicability probes, resolved at most once per target per call, and only
+  // if a lens declaring that target actually clears its gate — a Node-only
+  // project must not pay a filesystem scan on a roster with no `web` lens in
+  // it, nor a DB-less project pay one for `data-model`.
+  const targetProbes = {
+    web: hasWebSurfaceFn,
+    'data-model': hasPersistenceLayerFn,
+  };
+  const targetApplicabilityMemo = new Map();
+  const projectSupportsTarget = (target) => {
+    if (!targetApplicabilityMemo.has(target)) {
+      const probe = targetProbes[target];
+      targetApplicabilityMemo.set(target, probe ? probe({ config }) : true);
     }
-    return webSurfaceMemo;
+    return targetApplicabilityMemo.get(target);
   };
 
   for (const [auditName, ruleOpts] of Object.entries(rulesData.audits || {})) {
@@ -684,15 +953,16 @@ export async function selectAudits({
     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
+    // Target-applicability gate (#4579, #4633). A lens declaring a `target`
+    // has nothing to read on a project lacking that 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;
+    // to ignore the MUST. An absent `target` (or `any`) means "always
+    // applicable", so no existing lens changes behaviour.
+    const { target } = ruleOpts;
+    if (target && target !== 'any' && !projectSupportsTarget(target)) continue;
 
     const keywords = triggers.keywords || [];
     let keywordMatch = false;
@@ -711,7 +981,13 @@ export async function selectAudits({
       changedFiles,
     );
 
-    if (keywordMatch || fileMatch) {
+    // Coverage-gap routing (#4628): a lens declaring `sourceWithoutSiblingTest`
+    // fires when the change set touches source lacking a sibling test.
+    const siblingMatch =
+      triggers.sourceWithoutSiblingTest === true &&
+      changeSetLacksSiblingTest(changedFiles);
+
+    if (keywordMatch || fileMatch || siblingMatch) {
       selectedAudits.push(auditName);
     }
   }

package/.agents/scripts/lib/audit-to-stories/audit-lenses.js

@@ -25,12 +25,13 @@
  * @type {ReadonlyArray<string>}
  */
 export const AUDIT_LENSES = Object.freeze([
+  'accessibility',
   'architecture',
   'clean-code',
+  'data-model',
   'dependencies',
   'devops',
   'documentation',
-  'lighthouse',
   'navigability',
   'performance',
   'privacy',

package/.agents/scripts/lib/audit-to-stories/build-story-body.js

@@ -24,7 +24,10 @@
 
 import { serialize } from '../story-body/story-body.js';
 import { auditLabelsForFindings } from './audit-lenses.js';
-import { renderFingerprintFooter } from './finding-adapter.js';
+import {
+  renderFingerprintFooter,
+  renderSemanticKeyFooter,
+} from './finding-adapter.js';
 
 const STATIC_LABELS = Object.freeze(['type::story', 'agent::ready']);
 
@@ -239,6 +242,7 @@ export function buildStoryBody({ group, edges = [] }) {
     contextLinksFromGroup(group),
     '',
     renderFingerprintFooter(group.findings),
+    renderSemanticKeyFooter(group.findings),
   ].join('\n');
 
   return { title, body, labels: labelsForGroup(group) };

package/.agents/scripts/lib/audit-to-stories/dedupe-against-github.js

@@ -16,6 +16,11 @@
  * The GitHub lookup is delegated to a `provider` port the caller injects,
  * exposing `findIssuesByFingerprint(sha)` → `{ number, state, body }[]`. The
  * port is adapted into the `searchIssues` shape the shared helper expects.
+ * When the caller ALSO injects a `searchCandidates(finding)` port (production
+ * wires it to `semantic-issue-search.js`), routing runs the meaning-first
+ * Stage-1 pass and opts into location-based semantic-key confirmation so a
+ * reworded finding at an unchanged location still dedupes against its Issue
+ * (Story #4626).
  *
  * Pure orchestration: this module performs no network I/O itself.
  */
@@ -35,9 +40,17 @@ import { toCanonicalFinding } from './finding-adapter.js';
  * @param {object} params
  * @param {Array<object>} params.groups — output of `groupFindings`.
  * @param {{ findIssuesByFingerprint: (sha: string) => Promise<Array<{ number: number, state: string, body?: string }>> }} params.provider
+ * @param {(finding: object) => Promise<Array<{ number: number, state: string, title?: string, body?: string }>>} [params.searchCandidates]
+ *   Optional meaning-first candidate search (production: `semantic-issue-search.js`).
+ *   When supplied, routing runs the Stage-1 semantic pass and opts into
+ *   location-based semantic-key confirmation.
  * @returns {Promise<{ classifications: GroupClassification[], summary: { create: number, skipOpen: number, skipReoccurring: number } }>}
  */
-export async function classifyGroupsAgainstGitHub({ groups, provider }) {
+export async function classifyGroupsAgainstGitHub({
+  groups,
+  provider,
+  searchCandidates,
+}) {
   if (!Array.isArray(groups)) {
     throw new Error('classifyGroupsAgainstGitHub: groups must be an array');
   }
@@ -52,6 +65,9 @@ export async function classifyGroupsAgainstGitHub({ groups, provider }) {
   // projection, which equals the sha the group already carries (both come
   // from the same `toCanonicalFinding` projection).
   const searchIssues = (sha) => provider.findIssuesByFingerprint(sha);
+  const semanticPort =
+    typeof searchCandidates === 'function' ? searchCandidates : undefined;
+  const routeOptions = { semanticKeyConfirm: Boolean(semanticPort) };
 
   const classifications = [];
   const summary = { create: 0, skipOpen: 0, skipReoccurring: 0 };
@@ -68,9 +84,13 @@ export async function classifyGroupsAgainstGitHub({ groups, provider }) {
       const sha = finding?.fingerprint?.full;
       if (typeof sha !== 'string' || sha.length !== 40) continue;
 
+      const canonical = toCanonicalFinding(finding);
       const { decision, matchedIssue, fingerprint } = await routeFinding(
-        toCanonicalFinding(finding),
-        { searchIssues },
+        canonical,
+        semanticPort
+          ? { searchIssues, searchCandidates: () => semanticPort(canonical) }
+          : { searchIssues },
+        routeOptions,
       );
 
       if (decision === 'new') continue;

package/.agents/scripts/lib/audit-to-stories/finding-adapter.js

@@ -16,6 +16,8 @@
 import {
   fingerprintFinding,
   fingerprintFooter,
+  semanticKeyFooter,
+  semanticKeyFor,
 } from '../findings/route-finding.js';
 
 /**
@@ -55,6 +57,18 @@ export function fingerprintAuditFinding(finding) {
   return fingerprintFinding(toCanonicalFinding(finding));
 }
 
+/**
+ * Compute the location-based semantic key for a single audit finding via the
+ * shared helper. Stable across a reworded title; used to confirm a dedup
+ * match when the fingerprint has drifted (Story #4626).
+ *
+ * @param {object} finding
+ * @returns {string}
+ */
+export function semanticKeyForAuditFinding(finding) {
+  return semanticKeyFor(toCanonicalFinding(finding));
+}
+
 /**
  * Stamp every audit finding with its shared-helper fingerprint and return a
  * new array. Mirrors the legacy `withFingerprints` contract so downstream
@@ -91,3 +105,27 @@ export function renderFingerprintFooter(findings) {
     .filter((sha) => typeof sha === 'string' && sha.length > 0);
   return fingerprintFooter(shas);
 }
+
+/**
+ * Render the location-based semantic-key footer for a group of findings, via
+ * the shared helper's single footer renderer. Stamped alongside the
+ * fingerprint footer so a later reworded finding at the same location still
+ * confirms a dedup match (Story #4626). Findings do not need a precomputed
+ * key — it is derived from each finding's canonical projection here.
+ *
+ * @param {Array<object>} findings
+ * @returns {string}
+ */
+export function renderSemanticKeyFooter(findings) {
+  if (!Array.isArray(findings)) {
+    throw new Error('renderSemanticKeyFooter: findings must be an array');
+  }
+  const keys = [
+    ...new Set(
+      findings
+        .map((f) => semanticKeyForAuditFinding(f))
+        .filter((k) => typeof k === 'string' && k.length > 0),
+    ),
+  ];
+  return semanticKeyFooter(keys);
+}