mandrel 1.57.0

package/.agents/scripts/lib/maintainability-utils.js

@@ -0,0 +1,343 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { minimatch } from 'minimatch';
+import { canonicalise as canonicalisePath } from './baselines/path-canon.js';
+import {
+  write as writeBaselineEnvelope,
+  writeFile as writeBaselineFile,
+} from './baselines/writer.js';
+import { runOnPool } from './cpu-pool.js';
+import { Logger } from './Logger.js';
+import { calculateForFile } from './maintainability-engine.js';
+
+const require = createRequire(import.meta.url);
+
+const MAINTAINABILITY_WORKER_URL = new URL(
+  './workers/maintainability-worker.js',
+  import.meta.url,
+);
+
+// Below this batch size the pool's spawn overhead dominates — fall back
+// to in-process serial scoring for `--changed-since` runs that touch
+// only a handful of files. Tuned against the test suite's tmpdir
+// fixtures (n=2 stays serial; the full repo n≈470 takes the pool path).
+const SERIAL_THRESHOLD = 8;
+
+const JS_EXTS = new Set(['.js', '.mjs', '.cjs']);
+const TS_EXTS = new Set(['.ts', '.tsx', '.mts', '.cts']);
+const SUPPORTED_EXTS = new Set([...JS_EXTS, ...TS_EXTS]);
+
+let _ts = null;
+let _tsLoadFailed = false;
+
+function loadTypeScript() {
+  if (_ts) return _ts;
+  if (_tsLoadFailed) return null;
+  try {
+    _ts = require('typescript');
+    return _ts;
+  } catch {
+    _tsLoadFailed = true;
+    return null;
+  }
+}
+
+/**
+ * Resolve the `typescript` package version, used to stamp baselines so
+ * consumers can detect transpiler drift. Returns `'0.0.0'` when the
+ * dependency is unresolvable — callers treat that sentinel as "unknown
+ * environment" and may refuse to persist a baseline that includes TS rows.
+ *
+ * @returns {string}
+ */
+export function resolveTsTranspilerVersion() {
+  const ts = loadTypeScript();
+  if (ts && typeof ts.version === 'string') return ts.version;
+  return '0.0.0';
+}
+
+function isTypeScriptPath(filePath) {
+  return TS_EXTS.has(path.extname(String(filePath)).toLowerCase());
+}
+
+/**
+ * Pre-transpile TypeScript or TSX sources to JavaScript that the
+ * Esprima-based escomplex kernel can parse. Returns the input unchanged
+ * for `.js` / `.mjs` / `.cjs` paths.
+ *
+ * Type annotations introduce no control flow, so the transpiled output
+ * scores identically to the original TS for cyclomatic complexity,
+ * Halstead volume, and the maintainability index. `.tsx` uses the
+ * `react-jsx` emit so JSX expressions become function calls escomplex
+ * can read; `.preserve` would leave JSX in the output and Esprima would
+ * choke on it.
+ *
+ * On transpile failure the helper returns `null` — callers treat that
+ * as "skip this file" rather than crashing the scan.
+ *
+ * @param {string} filePath
+ * @param {string} source
+ * @returns {string|null}
+ */
+export function transpileIfNeeded(filePath, source) {
+  if (!isTypeScriptPath(filePath)) return source;
+  const ts = loadTypeScript();
+  if (!ts) {
+    Logger.warn(
+      `[Maintainability] ⚠ typescript package not resolvable; cannot score ${filePath}. ` +
+        "Install with 'npm install --save-dev typescript' (peer dep, >=5.0.0).",
+    );
+    return null;
+  }
+  try {
+    const result = ts.transpileModule(source, {
+      compilerOptions: {
+        target: ts.ScriptTarget.ESNext,
+        module: ts.ModuleKind.ESNext,
+        isolatedModules: true,
+        noEmitHelpers: true,
+        importHelpers: false,
+        removeComments: false,
+        jsx: ts.JsxEmit.ReactJSX,
+        sourceMap: false,
+      },
+      fileName: path.basename(filePath),
+      reportDiagnostics: false,
+    });
+    return result.outputText;
+  } catch (err) {
+    Logger.warn(
+      `[Maintainability] ⚠ TS transpile failed for ${filePath}: ${err?.message ?? err}; skipping.`,
+    );
+    return null;
+  }
+}
+
+/**
+ * @returns {boolean} True when the path's extension is one the engines score.
+ */
+function isSupportedSourceFile(filePath) {
+  return SUPPORTED_EXTS.has(path.extname(String(filePath)).toLowerCase());
+}
+
+/**
+ * Loads the current maintainability baseline from disk. The on-disk path is
+ * resolved by the caller via {@link getBaselines}; passing it explicitly
+ * removes the silent-default behaviour the framework dropped in Epic #730
+ * Story 5.5.
+ *
+ * @param {string} baselinePath  Repo-relative or absolute path to the baseline
+ *   JSON. Required.
+ * @returns {Record<string, number>}
+ */
+/**
+ * Story #1895: project the canonical maintainability envelope back to the
+ * legacy flat `{ path: mi }` map so existing gate consumers keep working
+ * without churn — Story #1912 will replace this shim with the shared
+ * reader. Returns the parsed input unchanged when it doesn't look like an
+ * envelope (legacy flat shape stays flat).
+ */
+function projectMaintainabilityEnvelopeToFlat(parsed) {
+  if (
+    !parsed ||
+    typeof parsed !== 'object' ||
+    Array.isArray(parsed) ||
+    !Array.isArray(parsed.rows) ||
+    typeof parsed.$schema !== 'string'
+  ) {
+    return parsed;
+  }
+  const flat = {};
+  for (const row of parsed.rows) {
+    if (row && typeof row.path === 'string' && typeof row.mi === 'number') {
+      flat[row.path] = row.mi;
+    }
+  }
+  return flat;
+}
+
+export function getBaseline(baselinePath) {
+  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
+    throw new TypeError(
+      'maintainability-utils.getBaseline: baselinePath is required (Epic #730 ' +
+        'Story 5.5 — callers resolve the path via getBaselines(config).maintainability.path).',
+    );
+  }
+  const abs = path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.resolve(process.cwd(), baselinePath);
+  if (!fs.existsSync(abs)) return {};
+  try {
+    const parsed = JSON.parse(fs.readFileSync(abs, 'utf-8'));
+    return projectMaintainabilityEnvelopeToFlat(parsed);
+  } catch (err) {
+    Logger.warn(`[Maintainability] Failed to parse baseline: ${err.message}`);
+    return {};
+  }
+}
+
+/**
+ * Saves a new maintainability baseline to disk at `baselinePath`.
+ *
+ * Accepts the legacy flat `{ path: mi }` shape for backwards compatibility
+ * with existing callers (`regenerateMainFromTree`, refresh helpers). The
+ * map is transformed into the canonical envelope shape (`$schema`,
+ * `kernelVersion`, `generatedAt`, `rollup`, `rows`) via the shared
+ * `lib/baselines/writer.js` pipeline before being persisted, so every
+ * write produces a file that round-trips through `lib/baselines/reader.js`
+ * without schema errors.
+ *
+ * @param {Record<string, number>} baseline  path→MI flat map.
+ * @param {string} baselinePath  Required — caller supplies via getBaselines().
+ */
+export function saveBaseline(baseline, baselinePath) {
+  if (typeof baselinePath !== 'string' || baselinePath.length === 0) {
+    throw new TypeError(
+      'maintainability-utils.saveBaseline: baselinePath is required.',
+    );
+  }
+  const abs = path.isAbsolute(baselinePath)
+    ? baselinePath
+    : path.resolve(process.cwd(), baselinePath);
+
+  const rows = Object.entries(baseline ?? {}).map(([p, mi]) => ({
+    path: p,
+    mi,
+  }));
+  const envelope = writeBaselineEnvelope({ kind: 'maintainability', rows });
+  writeBaselineFile(abs, envelope);
+}
+
+const IGNORED_DIRS = new Set([
+  'node_modules',
+  '.git',
+  'dist',
+  'temp',
+  '.worktrees',
+  'coverage',
+  '.next',
+]);
+
+/**
+ * Recursively scans a directory for JS/TS source files. Accepts `.js`,
+ * `.mjs`, `.cjs`, `.ts`, `.tsx`, `.mts`, and `.cts`. Directories listed
+ * in `IGNORED_DIRS` (including `coverage` and `.next`, added in 5.29.0
+ * to skip vitest's istanbul HTML scaffolding and Next.js build output)
+ * are skipped.
+ *
+ * @param {string} dir
+ * @param {string[]} fileList
+ * @param {{ ignoreGlobs?: string[], cwd?: string }} [opts]
+ *   `ignoreGlobs` — minimatch patterns matched against the canonicalised
+ *   repo-relative path of each discovered file. Files whose path matches
+ *   any pattern are excluded before scoring. Absent/empty is a no-op.
+ *   `cwd` — root used to compute repo-relative paths for glob matching;
+ *   defaults to `process.cwd()` when omitted.
+ * @returns {string[]}
+ */
+export function scanDirectory(dir, fileList = [], opts = {}) {
+  const { ignoreGlobs = [], cwd: optsCwd } = opts;
+  const matchCwd = optsCwd ?? process.cwd();
+  let entries;
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch (err) {
+    if (err.code === 'ENOENT') return fileList;
+    throw err;
+  }
+
+  for (const entry of entries) {
+    const filePath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!IGNORED_DIRS.has(entry.name)) {
+        scanDirectory(filePath, fileList, opts);
+      }
+    } else if (entry.isFile() && isSupportedSourceFile(entry.name)) {
+      if (ignoreGlobs.length > 0) {
+        const absFilePath = path.isAbsolute(filePath)
+          ? filePath
+          : path.resolve(filePath);
+        const rawRel = path.relative(matchCwd, absFilePath).replace(/\\/g, '/');
+        const relPath = canonicalisePath(rawRel);
+        if (ignoreGlobs.some((g) => minimatch(relPath, g, { dot: true }))) {
+          continue;
+        }
+      }
+      fileList.push(filePath);
+    }
+  }
+  return fileList;
+}
+
+/**
+ * Calculates maintainability scores for a list of file paths.
+ *
+ * Each file's transpile-then-analyze unit is dispatched to a
+ * worker_threads pool sized to `os.availableParallelism()`. Workers
+ * are recycled across files so TypeScript loads at most once per
+ * worker. The pool is bypassed for batches of fewer than
+ * `SERIAL_THRESHOLD` files because spawn overhead dominates at small
+ * sizes — the in-process path matches the pre-pool serial behaviour
+ * byte-for-byte.
+ *
+ * Output is sorted by relative file path so the returned object is
+ * insertion-order-stable regardless of which worker happened to
+ * finish first. Files that fail to read/transpile/parse are dropped
+ * from the result (matching the pre-pool log-and-continue contract);
+ * worker-side per-item failures surface as a `null` score that is
+ * filtered out before assembly.
+ *
+ * @param {string[]} paths
+ * @returns {Promise<Record<string, number>>}
+ */
+export async function calculateAll(paths) {
+  const cwd = process.cwd();
+  const indexed = paths.map((p) => ({
+    abs: p,
+    relPath: path.relative(cwd, p).replace(/\\/g, '/'),
+  }));
+
+  let perFile;
+  if (indexed.length < SERIAL_THRESHOLD) {
+    perFile = indexed.map(({ abs, relPath }) => {
+      try {
+        return { relPath, score: calculateForFile(abs) };
+      } catch (err) {
+        Logger.error(
+          `[Maintainability] Failed to process ${abs}: ${err.message}`,
+        );
+        return { relPath, score: null };
+      }
+    });
+  } else {
+    const results = await runOnPool(
+      MAINTAINABILITY_WORKER_URL,
+      indexed.map((e) => e.abs),
+    );
+    perFile = results.map((r, i) => {
+      const { abs, relPath } = indexed[i];
+      if (!r || r.__cpuPoolError) {
+        Logger.error(
+          `[Maintainability] Worker pool error for ${abs}: ${r?.message ?? 'unknown'}`,
+        );
+        return { relPath, score: null };
+      }
+      if (r.score === null && r.error) {
+        Logger.error(`[Maintainability] Failed to process ${abs}: ${r.error}`);
+      }
+      return { relPath, score: r.score };
+    });
+  }
+
+  perFile.sort((a, b) =>
+    a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0,
+  );
+
+  const scores = {};
+  for (const { relPath, score } of perFile) {
+    if (score === null) continue;
+    scores[relPath] = score;
+  }
+  return scores;
+}

package/.agents/scripts/lib/mandrel-catalog.js

@@ -0,0 +1,170 @@
+/**
+ * mandrel-catalog.js
+ *
+ * Walks `.agents/workflows/*.md` (top-level only — `helpers/` are
+ * path-included modules, not slash commands) and produces the
+ * Mandrel-owned slash-command catalog.
+ *
+ * This is the canonical catalog backend. The consumer-shipped
+ * `.agents/docs/workflows.md` is generated from it by
+ * `generate-workflows-doc.js`, and `npm run docs:check` gates that doc
+ * against drift — same source-of-truth contract as
+ * `sync-claude-commands.js`, just one layer up (catalog of what's
+ * synced, not the sync itself). The retired `mandrel` discoverability
+ * command used to render this catalog live; Story #3708 replaced it
+ * with the gated, generated `workflows.md` so the catalog is shipped
+ * and drift-checked rather than ephemeral.
+ *
+ * Pure functions only: no GitHub I/O, no file writes, no provider
+ * factory. Callers (the doc generator, the unit test) pass an
+ * absolute path to a workflows directory in; the function returns a
+ * sorted array of `{ name, description }` entries plus a
+ * `renderCatalog()` helper that produces a human-readable markdown
+ * bullet list.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+/**
+ * Parse a workflow markdown file's YAML frontmatter and return its
+ * `description:` field, normalized to a single-line string.
+ *
+ * Handles both the inline form (`description: foo bar`) and the
+ * YAML folded-block form (`description: >-` followed by indented
+ * continuation lines). Both forms appear in the live workflow set —
+ * see `.agents/workflows/signals.md` (folded) vs.
+ * `.agents/workflows/agents-bootstrap-github.md` (inline).
+ *
+ * Returns `null` if the file has no frontmatter or no `description:`
+ * key. Returns the trimmed, whitespace-collapsed string otherwise.
+ *
+ * @param {string} source — full file contents.
+ * @returns {string | null}
+ */
+export function extractDescription(source) {
+  if (typeof source !== 'string') return null;
+  // Frontmatter must be the first block. Match `---\n...\n---` at
+  // the start of the file; tolerate a leading BOM.
+  const trimmed = source.replace(/^/, '');
+  if (!trimmed.startsWith('---')) return null;
+  const end = trimmed.indexOf('\n---', 3);
+  if (end < 0) return null;
+  const block = trimmed.slice(4, end);
+  const lines = block.split('\n');
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const match = /^description:\s*(.*)$/i.exec(line);
+    if (!match) {
+      i += 1;
+      continue;
+    }
+    const rest = match[1].trim();
+    // Folded / literal block forms: `>-`, `>`, `|`, `|-`. The actual
+    // value follows on subsequent indented lines.
+    if (/^[>|][-+]?\s*$/.test(rest) || rest === '') {
+      const collected = [];
+      let j = i + 1;
+      while (j < lines.length) {
+        const next = lines[j];
+        // Stop on the next top-level key (column-0 alphanumeric +
+        // colon) — that's the next frontmatter entry.
+        if (/^[A-Za-z][\w-]*\s*:/.test(next)) break;
+        // Blank line inside a folded block is permissible; keep
+        // collecting until the next top-level key.
+        collected.push(next.trim());
+        j += 1;
+      }
+      const joined = collected.join(' ').replace(/\s+/g, ' ').trim();
+      return joined.length > 0 ? joined : null;
+    }
+    // Inline form.
+    return rest.replace(/\s+/g, ' ').trim();
+  }
+  return null;
+}
+
+/**
+ * Heuristic: treat a description as "vague" when it carries no
+ * information beyond the workflow's own name. Callers can use this to
+ * nudge the maintainer when a description needs tightening — it does
+ * **not** block the catalog from rendering. The
+ * description-frontmatter audit pass (Task #1619 acceptance) is a
+ * one-time sweep; this helper exists so the audit doesn't silently
+ * regress later.
+ *
+ * @param {string | null} description
+ * @returns {boolean}
+ */
+export function isVagueDescription(description) {
+  if (!description) return true;
+  // Fewer than 30 characters of substance is suspicious for a
+  // discoverability menu entry.
+  if (description.trim().length < 30) return true;
+  return false;
+}
+
+/**
+ * Build the Mandrel-owned catalog from an on-disk workflows directory.
+ *
+ * @param {string} workflowsDir — absolute path to `.agents/workflows/`.
+ * @returns {Array<{ name: string, description: string | null, vague: boolean }>}
+ */
+export function buildCatalog(workflowsDir) {
+  if (!fs.existsSync(workflowsDir)) {
+    throw new Error(
+      `mandrel-catalog: workflows directory not found: ${workflowsDir}`,
+    );
+  }
+  const entries = fs.readdirSync(workflowsDir, { withFileTypes: true });
+  const catalog = [];
+  for (const entry of entries) {
+    // Only top-level .md files — `helpers/` is intentionally not in
+    // the runnable catalog (mirrors `sync-claude-commands.js`'s
+    // `isTopLevelWorkflow` filter).
+    if (!entry.isFile()) continue;
+    if (!entry.name.endsWith('.md')) continue;
+    if (entry.name === 'README.md') continue;
+    const filePath = path.join(workflowsDir, entry.name);
+    const source = fs.readFileSync(filePath, 'utf8');
+    const description = extractDescription(source);
+    catalog.push({
+      name: entry.name.replace(/\.md$/, ''),
+      description,
+      vague: isVagueDescription(description),
+    });
+  }
+  catalog.sort((a, b) => a.name.localeCompare(b.name));
+  return catalog;
+}
+
+/**
+ * Render the catalog as a plain-markdown bullet list. Kept as a
+ * lightweight alternative rendering of the same catalog backend that
+ * `generate-workflows-doc.js` renders into the shipped
+ * `.agents/docs/workflows.md` table.
+ *
+ * @param {Array<{ name: string, description: string | null, vague: boolean }>} catalog
+ * @returns {string}
+ */
+export function renderCatalog(catalog) {
+  if (catalog.length === 0) {
+    return '# Mandrel command catalog\n\n_(no workflows found)_\n';
+  }
+  const rows = catalog.map((entry) => {
+    const desc = entry.description ?? '_(no description)_';
+    const flag = entry.vague ? ' ⚠️ vague' : '';
+    return `- **/${entry.name}** — ${desc}${flag}`;
+  });
+  return [
+    '# Mandrel command catalog',
+    '',
+    `Source of truth: \`.agents/workflows/\` (${catalog.length} commands).`,
+    'Auto-generated by `.agents/scripts/lib/mandrel-catalog.js`.',
+    '',
+    ...rows,
+    '',
+  ].join('\n');
+}