mandrel 2.59.0 → 2.61.0

package/.agents/scripts/lib/dynamic-workflow/quality-report-contract.js

@@ -1,90 +0,0 @@
-// .agents/scripts/lib/dynamic-workflow/quality-report-contract.js
-import { assertSectionsContract } from './report-contract-core.js';
-
-/**
- * The `audit-quality` report contract (Epic #3597, Story #3614).
- *
- * This is the **single source of truth** for the report shape that BOTH the
- * sequential lens (`.agents/workflows/audit-quality.md` Step 3) and the
- * orchestrated dynamic-workflow path
- * (`.claude/workflows/audit-quality.workflow.js`) MUST emit to
- * `{{auditOutputDir}}/audit-quality-results.md`. Keeping it here lets the
- * contract-tier test assert report conformance against one definition rather
- * than re-deriving headings from prose in two places.
- *
- * Generalising the orchestrated dual path to the quality lens is explicitly
- * **report-contract-preserving** — this module documents the existing shape the
- * sequential lens already emits, it does not introduce a new one.
- *
- * @module dynamic-workflow/quality-report-contract
- */
-
-/** The artifact filename the lens writes under `auditOutputDir`. */
-export const REPORT_ARTIFACT_BASENAME = 'audit-quality-results.md';
-
-/**
- * The required top-level (`##`) section headings, in document order, that the
- * lens markdown's Step 3 template defines. A conformant report MUST contain
- * each of these headings; the orchestrated path assembles its cross-checked
- * findings into exactly this skeleton.
- */
-export const REQUIRED_SECTIONS = Object.freeze([
-  'Executive Summary',
-  'Test Strategy Assessment',
-  'Detailed Findings',
-]);
-
-/** The H1 title the report opens with. */
-export const REPORT_TITLE = 'Testing & Quality Assurance Audit';
-
-/**
- * The required field labels inside each `### <finding>` block under
- * `## Detailed Findings`. Mirrors the strict per-finding structure in the
- * lens template.
- */
-export const FINDING_FIELDS = Object.freeze([
-  'Category',
-  'Impact',
-  'Current State',
-  'Recommendation & Rationale',
-  'Agent Prompt',
-]);
-
-/**
- * The finding categories the per-finding `Category` field draws from. These
- * mirror the lens's Step 3 template enumeration and the Step 2 analysis
- * dimensions the quality audit decomposes into.
- */
-export const FINDING_CATEGORIES = Object.freeze([
-  'Flakiness',
-  'Coverage',
-  'Performance',
-  'Mocking',
-  'Test Plans',
-]);
-
-/**
- * The impact buckets the Executive Summary and per-finding `Impact` field draw
- * from. The lens speaks in High/Medium/Low; this list is the canonical
- * taxonomy the downstream `audit-to-stories` consumer maps onto Story
- * priority.
- */
-export const IMPACT_LEVELS = Object.freeze(['High', 'Medium', 'Low']);
-
-/**
- * Assert that a rendered markdown report conforms to the contract: it has the
- * H1 title and every required `##` section heading. Returns a structured
- * result rather than throwing, so callers (tests, the orchestrated path's
- * self-check) can report precisely which sections are missing.
- *
- * Pure function — string analysis only.
- *
- * @param {string} markdown - The rendered report body.
- * @returns {{ conformant: boolean, missingSections: string[], hasTitle: boolean }}
- */
-export function assertReportContract(markdown) {
-  return assertSectionsContract(markdown, {
-    title: REPORT_TITLE,
-    requiredSections: REQUIRED_SECTIONS,
-  });
-}

package/.agents/scripts/lib/dynamic-workflow/report-contract-core.js

@@ -1,43 +0,0 @@
-// .agents/scripts/lib/dynamic-workflow/report-contract-core.js
-/**
- * Shared markdown section contract assertions for audit report lenses.
- *
- * Individual lens modules own their report title and required section list;
- * this helper owns the invariant string-analysis mechanics.
- *
- * @module dynamic-workflow/report-contract-core
- */
-
-/**
- * Assert that a rendered markdown report has the expected H1 title and every
- * required `##` section heading. Returns a structured result rather than
- * throwing, so callers can report precisely which sections are missing.
- *
- * Pure function — string analysis only.
- *
- * @param {string} markdown - The rendered report body.
- * @param {{ title: string, requiredSections: readonly string[] }} contract
- *   - The per-lens report contract constants.
- * @returns {{ conformant: boolean, missingSections: string[], hasTitle: boolean }}
- */
-export function assertSectionsContract(markdown, { title, requiredSections }) {
-  const text = typeof markdown === 'string' ? markdown : '';
-  const hasTitle = new RegExp(`^#\\s+${escapeRegExp(title)}\\s*$`, 'm').test(
-    text,
-  );
-
-  const missingSections = requiredSections.filter(
-    (heading) =>
-      !new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`, 'm').test(text),
-  );
-
-  return {
-    conformant: hasTitle && missingSections.length === 0,
-    missingSections,
-    hasTitle,
-  };
-}
-
-export function escapeRegExp(str) {
-  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

package/.agents/scripts/lib/dynamic-workflow/security-report-contract.js

@@ -1,83 +0,0 @@
-// .agents/scripts/lib/dynamic-workflow/security-report-contract.js
-import { assertSectionsContract } from './report-contract-core.js';
-
-/**
- * The `audit-security` report contract (Epic #3597, Story #3613).
- *
- * This is the **single source of truth** for the report shape that BOTH the
- * sequential lens (`.agents/workflows/audit-security.md` Step 3) and the
- * orchestrated dynamic-workflow path
- * (`.claude/workflows/audit-security.workflow.js`) MUST emit to
- * `{{auditOutputDir}}/audit-security-results.md`. Keeping it here lets the
- * contract-tier test assert report conformance against one definition rather
- * than re-deriving headings from prose in two places.
- *
- * Generalising the orchestrated dual path to the security lens is explicitly
- * **report-contract-preserving** — this module documents the existing shape the
- * sequential lens already emits, it does not introduce a new one.
- *
- * @module dynamic-workflow/security-report-contract
- */
-
-/** The artifact filename the lens writes under `auditOutputDir`. */
-export const REPORT_ARTIFACT_BASENAME = 'audit-security-results.md';
-
-/**
- * The required top-level (`##`) section headings, in document order, that the
- * lens markdown's Step 3 template defines. A conformant report MUST contain
- * each of these headings; the orchestrated path assembles its cross-checked
- * findings into exactly this skeleton.
- */
-export const REQUIRED_SECTIONS = Object.freeze([
-  'Executive Summary',
-  'Detailed Findings',
-  'Defensive Recommendations',
-]);
-
-/** The H1 title the report opens with. */
-export const REPORT_TITLE = 'Security Audit Report';
-
-/**
- * The required field labels inside each `### <finding>` block under
- * `## Detailed Findings`. Mirrors the strict per-finding structure in the
- * lens template.
- */
-export const FINDING_FIELDS = Object.freeze([
-  'Dimension',
-  'Severity',
-  'CWE ID',
-  'Current State',
-  'Recommendation & Rationale',
-  'Agent Prompt',
-]);
-
-/**
- * The severity buckets the Executive Summary risk profile and per-finding
- * `Severity` field draw from. The lens speaks in High/Medium/Low (with
- * Critical as the top High band); this list is the canonical taxonomy the
- * downstream `audit-to-stories` consumer maps onto Story priority.
- */
-export const SEVERITY_LEVELS = Object.freeze([
-  'Critical',
-  'High',
-  'Medium',
-  'Low',
-]);
-
-/**
- * Assert that a rendered markdown report conforms to the contract: it has the
- * H1 title and every required `##` section heading. Returns a structured
- * result rather than throwing, so callers (tests, the orchestrated path's
- * self-check) can report precisely which sections are missing.
- *
- * Pure function — string analysis only.
- *
- * @param {string} markdown - The rendered report body.
- * @returns {{ conformant: boolean, missingSections: string[], hasTitle: boolean }}
- */
-export function assertReportContract(markdown) {
-  return assertSectionsContract(markdown, {
-    title: REPORT_TITLE,
-    requiredSections: REQUIRED_SECTIONS,
-  });
-}

package/.agents/scripts/lib/fs-walk.js

@@ -1,52 +0,0 @@
-/**
- * fs-walk.js — the one recursive file walker the lint scripts share.
- *
- * `check-lifecycle-lint.js` and `lint-label-vocabulary.js` each carried a
- * private copy of this generator, differing only in the extension they
- * matched — the second one's comment said so outright ("mirrors the walker
- * shape in check-lifecycle-lint.js"). Story #5024 extracted it: shrinking
- * check-lifecycle-lint.js pushed its duplication percentage up on an unchanged
- * clone count, which is the ratchet correctly pointing at boilerplate that
- * should not have been copied twice.
- *
- * A missing directory yields nothing rather than throwing. That is
- * load-bearing, not lenient: the lint surfaces are directories a deletion can
- * legitimately remove (Story #5024 deleted `lifecycle/listeners/`), and a scan
- * of an absent path is vacuously clean, not an error. Every other `readdir`
- * failure — a permission error, a file where a directory was expected —
- * propagates, so a genuinely broken scan cannot read as clean.
- */
-
-import { readdirSync } from 'node:fs';
-import path from 'node:path';
-
-/**
- * Walk a directory tree synchronously, yielding absolute paths of every file
- * whose name ends with `extension`.
- *
- * @param {string} dir Absolute directory to walk.
- * @param {string} extension Extension to match, leading dot included (`.js`).
- * @param {{ readDir?: typeof readdirSync }} [ports] Injectable for tests.
- * @returns {Generator<string, void, void>}
- */
-export function* walkFilesByExtension(
-  dir,
-  extension,
-  { readDir = readdirSync } = {},
-) {
-  let entries;
-  try {
-    entries = readDir(dir, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === 'ENOENT') return;
-    throw err;
-  }
-  for (const entry of entries) {
-    const p = path.join(dir, entry.name);
-    if (entry.isDirectory()) {
-      yield* walkFilesByExtension(p, extension, { readDir });
-    } else if (entry.isFile() && entry.name.endsWith(extension)) {
-      yield p;
-    }
-  }
-}

package/.agents/scripts/lib/knip-config-resolver.js

@@ -1,181 +0,0 @@
-/**
- * knip-config-resolver.js — resolve a repository's knip configuration the way
- * knip itself would, and hand back its declared entry patterns.
- *
- * Split out of `knip-entry-sync.js` (Story #5039) because these are two
- * concerns that change for different reasons: *what knip's config says* tracks
- * knip's own releases, while *which CLIs something invokes* tracks this
- * repository's callers. Keeping them in one file also pushed that module's
- * maintainability index below its floor.
- *
- * Why not read the file ourselves: #5026 hardcoded
- * `JSON.parse(<root>/knip.json)`, so all seven of knip's other config
- * locations plus `package.json#knip` resolved to ENOENT and failed the gate
- * closed. That made it unusable in exactly the repositories that adopt the
- * shared `knip.base.json` — knip 6 has no root-level `extends`, so inheriting
- * the base means spreading it inside a TypeScript module, which a static
- * `knip.json` structurally cannot express.
- *
- * Going through `createOptions` also drops the assumption that `entry` is
- * *statically declared*. A config may build the array programmatically, so
- * even a purpose-built `knip.config.ts` parser would read the wrong thing;
- * knip evaluates the module and returns the computed value.
- */
-
-/**
- * Load knip's own config resolver.
- *
- * Deliberately a dynamic import behind an injectable seam. `knip` is declared
- * in `runtime-deps.json` as an **optional** dependency, mirroring `typescript`:
- * the `.agents/` payload is materialized into consumers that may not run knip
- * at all, so an unresolvable `knip` must degrade to the skip path rather than
- * crash the gate at module load — and must never be preflight-blocked.
- *
- * @returns {Promise<{ createOptions?: Function }>}
- */
-function importKnipSession() {
-  return import('knip/session');
-}
-
-/**
- * Collect every declared entry pattern from a resolved knip configuration.
- *
- * Entries live in two places and #5026 read only the first. A pnpm-workspace
- * config — the shape that made this gate unusable in `Beestera/swarm-os` —
- * declares them per workspace, so a config with no top-level `entry` at all is
- * still fully enumerated. A named workspace's patterns are workspace-relative
- * and are joined to the workspace name; the root workspace (`.`) is already
- * repo-relative. A leading `!` is knip's *negation* marker (as opposed to the
- * trailing production marker) and stays at the front of the pattern rather
- * than getting buried behind the workspace prefix.
- *
- * `sawEntryArray` separates "declared nothing under `.agents/scripts/`" — a
- * legitimate result, reported as `missing` divergences — from "this config
- * enumerates no entry points anywhere", which leaves the gate nothing to
- * compare against.
- *
- * @param {object} parsedConfig knip's schema-parsed configuration
- * @returns {{ patterns: string[], sawEntryArray: boolean }}
- */
-function collectEntryPatterns(parsedConfig) {
-  const patterns = [];
-  let sawEntryArray = false;
-
-  const push = (value, prefix) => {
-    if (typeof value !== 'string') return;
-    if (!prefix) patterns.push(value);
-    else if (value.startsWith('!'))
-      patterns.push(`!${prefix}${value.slice(1)}`);
-    else patterns.push(`${prefix}${value}`);
-  };
-
-  const addAll = (entry, prefix) => {
-    if (!Array.isArray(entry)) return;
-    sawEntryArray = true;
-    for (const value of entry) push(value, prefix);
-  };
-
-  addAll(parsedConfig?.entry, '');
-
-  const workspaces = parsedConfig?.workspaces;
-  if (workspaces && typeof workspaces === 'object') {
-    for (const [name, workspace] of Object.entries(workspaces)) {
-      const trimmed = name.replace(/^\.\/+/, '').replace(/\/+$/, '');
-      const prefix = trimmed === '' || trimmed === '.' ? '' : `${trimmed}/`;
-      addAll(workspace?.entry, prefix);
-    }
-  }
-
-  return { patterns, sawEntryArray };
-}
-
-/**
- * Resolve the entry patterns knip would see for `repoRoot`.
- *
- * Three outcomes, deliberately distinct — collapsing the first two is how a
- * broken configuration would come to look like an absent one:
- *
- *   skipped — nothing to check (no config file, no `package.json#knip`, or no
- *     resolvable `knip`). The gate exits 0. This is what makes it safe to wire
- *     into every consumer, matching `qa.gherkinLint`'s opt-in posture.
- *   error — a configuration exists but could not be resolved, or enumerates no
- *     entry points at all. The gate exits 2.
- *   resolved — `patterns` carries every declared entry, top-level and
- *     per-workspace, with knip's trailing `!` production markers intact.
- *
- * @param {{ repoRoot: string, loadKnipSession?: () => Promise<object> }} opts
- * @returns {Promise<{
- *   patterns: string[],
- *   configFilePath: string | null,
- *   skipped: string | null,
- *   error: string | null,
- * }>}
- */
-export async function resolveKnipEntryPatterns({
-  repoRoot,
-  loadKnipSession = importKnipSession,
-}) {
-  const nothing = { patterns: [], configFilePath: null };
-
-  let createOptions;
-  try {
-    ({ createOptions } = await loadKnipSession());
-  } catch (error) {
-    return {
-      ...nothing,
-      skipped: `the "knip" package is not resolvable from ${repoRoot} (${error.message})`,
-      error: null,
-    };
-  }
-  if (typeof createOptions !== 'function') {
-    return {
-      ...nothing,
-      skipped: null,
-      error:
-        'the installed "knip" does not export createOptions from "knip/session" — this gate needs knip 6 or newer',
-    };
-  }
-
-  let options;
-  try {
-    options = await createOptions({ cwd: repoRoot, args: {} });
-  } catch (error) {
-    return {
-      ...nothing,
-      skipped: null,
-      error: `cannot resolve the knip configuration: ${error.message}`,
-    };
-  }
-
-  const configFilePath = options?.configFilePath ?? null;
-  if (!configFilePath) {
-    return {
-      ...nothing,
-      skipped: `no knip configuration found under ${repoRoot} (no config file, no package.json#knip)`,
-      error: null,
-    };
-  }
-
-  const { patterns, sawEntryArray } = collectEntryPatterns(
-    options?.parsedConfig,
-  );
-  if (!sawEntryArray) {
-    return {
-      patterns: [],
-      configFilePath,
-      skipped: null,
-      error: `${configFilePath} declares no "entry" array, at the top level or in any workspace`,
-    };
-  }
-
-  return { patterns, configFilePath, skipped: null, error: null };
-}
-
-/**
- * Test-only seam. Not API — `collectEntryPatterns` is exercised directly so the
- * workspace-prefix and negation rules can be pinned without a fixture tree.
- */
-export const __testing = Object.freeze({
-  collectEntryPatterns,
-  importKnipSession,
-});