@chemx/starter-kit 26.10.8-344 → 26.10.10-75

package/cli/audit/feed.js

@@ -0,0 +1,146 @@
+// Audit feed: flat, dashboard-ready rows built from .chemx/history.json and .chemx/status.json.
+// The builders are pure (they take parsed data); readAuditFeed reads the files. Nothing here
+// runs an audit. Every row carries ruleset/scoreModel so consumers can flag scores that a
+// rules change makes incomparable.
+import { getAuditHistory } from './history.js';
+import { readAuditStatus } from './status-file.js';
+
+export const FEED_VIEWS = ['history', 'pillars', 'scopes'];
+
+const orNull = (value) => value ?? null;
+
+const isInScope = (rowScope, scope) => {
+  const hasScopeFilter = typeof scope === 'string' && scope.length > 0;
+  if (!hasScopeFilter) return true;
+  const isExact = rowScope === scope;
+  const isNested = typeof rowScope === 'string' && rowScope.startsWith(`${scope}/`);
+  return isExact || isNested;
+};
+
+const isSince = (timestamp, since) => {
+  const hasSince = Boolean(since);
+  if (!hasSince) return true;
+  return new Date(timestamp).getTime() >= new Date(since).getTime();
+};
+
+const matchesFilters = (snapshot, { scope, since, fullOnly = false } = {}) => {
+  const isPartialExcluded = fullOnly && Boolean(snapshot.isPartial);
+  if (isPartialExcluded) return false;
+  return isInScope(orNull(snapshot.scope), scope) && isSince(snapshot.timestamp, since);
+};
+
+const runIdentity = (snapshot) => ({
+  runId: orNull(snapshot.id),
+  timestamp: orNull(snapshot.timestamp),
+  scope: orNull(snapshot.scope),
+  isPartial: Boolean(snapshot.isPartial),
+  ruleset: orNull(snapshot.ruleset)
+});
+
+const toHistoryRow = (snapshot) => {
+  const { health = {}, aiSlop = {}, metrics = {}, violations = {}, monoliths = {} } = snapshot;
+  return {
+    ...runIdentity(snapshot),
+    scoreModel: orNull(snapshot.scoreModel),
+    healthScore: orNull(health.score),
+    grade: orNull(health.grade),
+    aiSlopScore: orNull(aiSlop.score),
+    aiSlopGrade: orNull(aiSlop.grade),
+    files: orNull(metrics.scannedFiles),
+    loc: orNull(metrics.totalLoc),
+    violations: orNull(violations.total),
+    critical: orNull(violations.critical),
+    high: orNull(violations.high),
+    medium: orNull(violations.medium),
+    low: orNull(violations.low),
+    monoliths: orNull(monoliths.total)
+  };
+};
+
+export const historyRows = (history = [], filters = {}) =>
+  history.filter((snapshot) => matchesFilters(snapshot, filters)).map(toHistoryRow);
+
+export const pillarRows = (history = [], filters = {}) =>
+  history
+    .filter((snapshot) => matchesFilters(snapshot, filters))
+    .flatMap((snapshot) => Object.entries(snapshot.pillars ?? {}).map(([pillar, data]) => ({
+      ...runIdentity(snapshot),
+      pillar,
+      status: orNull(data.status),
+      violations: orNull(data.violations),
+      critical: orNull(data.critical)
+    })));
+
+const newestFullRunByScope = (history) => {
+  const byScope = new Map();
+  for (const snapshot of history) {
+    const hasScope = typeof snapshot.scope === 'string';
+    const isFullRun = hasScope && !snapshot.isPartial;
+    if (isFullRun) byScope.set(snapshot.scope, snapshot);
+  }
+  return byScope;
+};
+
+const countRunsByScope = (history) => {
+  const counts = new Map();
+  for (const snapshot of history) counts.set(snapshot.scope, (counts.get(snapshot.scope) ?? 0) + 1);
+  return counts;
+};
+
+const toScopeRow = (scope, run, entry, runCount) => {
+  const runRow = run ? toHistoryRow(run) : null;
+  const gate = entry?.gate ?? {};
+  return {
+    scope,
+    runs: runCount,
+    runId: orNull(runRow?.runId),
+    lastFullRunAt: orNull(runRow?.timestamp),
+    ruleset: orNull(runRow?.ruleset ?? entry?.ruleset),
+    scoreModel: orNull(runRow?.scoreModel ?? entry?.scoreModel),
+    healthScore: orNull(runRow?.healthScore ?? entry?.health?.score),
+    grade: orNull(runRow?.grade ?? entry?.health?.grade),
+    aiSlopScore: orNull(runRow?.aiSlopScore),
+    files: orNull(runRow?.files),
+    loc: orNull(runRow?.loc),
+    violations: orNull(runRow?.violations),
+    critical: orNull(runRow?.critical ?? entry?.hazards?.critical),
+    high: orNull(runRow?.high ?? entry?.hazards?.high),
+    medium: orNull(runRow?.medium ?? entry?.hazards?.medium),
+    low: orNull(runRow?.low ?? entry?.hazards?.low),
+    monoliths: orNull(runRow?.monoliths),
+    gatePassing: orNull(gate.isPassing),
+    gateBasis: orNull(gate.basis),
+    gateRegressions: orNull(gate.regressions),
+    coverageAstPct: orNull(entry?.coverage?.astPct),
+    statusUpdatedAt: orNull(entry?.updatedAt),
+    statusIsPartial: Boolean(entry?.isPartialScan)
+  };
+};
+
+export const scopeRows = (history = [], status = null, filters = {}) => {
+  const statusScopes = status?.scopes ?? {};
+  const fullRuns = newestFullRunByScope(history);
+  const runCounts = countRunsByScope(history);
+  const scopes = new Set([...fullRuns.keys(), ...Object.keys(statusScopes)]);
+  for (const snapshot of history) {
+    const hasScope = typeof snapshot.scope === 'string';
+    if (hasScope) scopes.add(snapshot.scope);
+  }
+  return [...scopes]
+    .filter((scope) => isInScope(scope, filters.scope))
+    .sort()
+    .map((scope) => toScopeRow(scope, fullRuns.get(scope), statusScopes[scope], runCounts.get(scope) ?? 0));
+};
+
+const VIEW_BUILDERS = {
+  history: (history, _status, filters) => historyRows(history, filters),
+  pillars: (history, _status, filters) => pillarRows(history, filters),
+  scopes: (history, status, filters) => scopeRows(history, status, filters)
+};
+
+export const readAuditFeed = (view, { cwd = process.cwd(), ...filters } = {}) => {
+  const build = VIEW_BUILDERS[view];
+  const isKnownView = typeof build === 'function';
+  if (!isKnownView) throw new Error(`Unknown audit feed view "${view}". Use one of: ${FEED_VIEWS.join(', ')}.`);
+  return build(getAuditHistory(cwd), readAuditStatus(cwd), filters);
+};

package/cli/audit/gate-delta.js

@@ -0,0 +1,91 @@
+/**
+ * The one definition of "does this change add hazards beyond the baseline?" (#2546).
+ *
+ * The ratchet (chemx-ratchet.json) counts violations per rule at every severity and
+ * fails a rule whose count rises. This module applies the same rule to a change: for
+ * each file, a rule whose violation count is higher after the change than before it
+ * is an increase, at any severity. The staged-delta pre-commit gate, task done and
+ * the patch/write introducedViolations report all call it, and
+ * gate-parity.spec.js proves the verdicts match a ratchet verdict on the same change.
+ *
+ * Guarantee: a change that adds no violations of any rule passes. A legacy file with
+ * existing hazards is not blocked by them, only by new ones. Not covered: a hazard
+ * that moves between rules in the same count, which is neutral per rule.
+ */
+
+const SEVERITY_ORDER = ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'];
+
+const severityRank = (severity) => SEVERITY_ORDER.indexOf(severity);
+
+export const countByRule = (violations = []) => {
+  const counts = new Map();
+  for (const v of violations) counts.set(v.rule, (counts.get(v.rule) ?? 0) + 1);
+  return counts;
+};
+
+const highestSeverity = (violations) => {
+  const ranked = violations.map((v) => v.severity);
+  return ranked.reduce((top, s) => (severityRank(s) > severityRank(top) ? s : top), 'LOW');
+};
+
+/** Violations of one rule in `after` that have no same-hazard counterpart in `before`, capped at the count rise. */
+const newSitesForRule = (rule, before, after, rise) => {
+  const unmatched = new Map();
+  for (const v of before.filter((b) => b.rule === rule)) unmatched.set(v.hazard, (unmatched.get(v.hazard) ?? 0) + 1);
+  const fresh = [];
+  for (const v of after.filter((a) => a.rule === rule)) {
+    const remaining = unmatched.get(v.hazard) ?? 0;
+    const isMatched = remaining > 0;
+    unmatched.set(v.hazard, isMatched ? remaining - 1 : 0);
+    if (!isMatched) fresh.push(v);
+  }
+  const isExact = fresh.length === rise;
+  return isExact ? fresh : fresh.slice(-rise);
+};
+
+/**
+ * Per-rule increases between two violation lists of the same file.
+ *
+ * @returns {{ rule: string, severity: string, before: number, after: number, sites: object[] }[]} sites are the new violation objects themselves
+ */
+export const diffViolations = (beforeViolations = [], afterViolations = []) => {
+  const before = countByRule(beforeViolations);
+  const after = countByRule(afterViolations);
+  const increases = [];
+  for (const [rule, count] of after.entries()) {
+    const was = before.get(rule) ?? 0;
+    const rise = count - was;
+    const isIncrease = rise > 0;
+    if (!isIncrease) continue;
+    const sites = newSitesForRule(rule, beforeViolations, afterViolations, rise);
+    const severity = highestSeverity(afterViolations.filter((v) => v.rule === rule));
+    increases.push({ rule, severity, before: was, after: count, sites });
+  }
+  return increases;
+};
+
+/** The individual violations a change introduced, for the patch/write report. */
+export const introducedViolationsOf = (beforeViolations, afterViolations) =>
+  diffViolations(beforeViolations, afterViolations).flatMap((increase) => increase.sites);
+
+/**
+ * @param {{ file: string, renamedFrom?: string, before: object[], after: object[] }[]} changes
+ * @returns {{ isPassing: boolean, files: { file: string, increases: object[] }[] }}
+ */
+export const evaluateChanges = (changes) => {
+  const files = [];
+  for (const change of changes) {
+    const increases = diffViolations(change.before, change.after);
+    const hasIncreases = increases.length > 0;
+    if (!hasIncreases) continue;
+    const renamed = change.renamedFrom ? { renamedFrom: change.renamedFrom } : {};
+    files.push({ file: change.file, ...renamed, increases });
+  }
+  return { isPassing: files.length === 0, files };
+};
+
+/** One `RULE@file:line [SEVERITY]` entry per new site, the exact list the hook prints. */
+export const formatSites = (fileEntry) =>
+  fileEntry.increases.flatMap((increase) =>
+    increase.sites.map((site) => `${increase.rule}@${fileEntry.file}:${site.line} [${site.severity}]`)
+  );

package/cli/audit/gate-verdict.js

@@ -1,30 +1,52 @@
-import { readRatchet, evaluateRatchet } from './ratchet.js';
+import { readRatchet, evaluateRatchet, recordAdoptedRules } from './ratchet.js';
 
 const RATCHET_STATUSES = new Set(['pass', 'fail', 'invalid']);
 
 const isSevereViolation = (v) => v.severity === 'CRITICAL' || v.severity === 'HIGH';
 
+const describeAdoption = (adopted) => {
+  const hasAdopted = adopted.length > 0;
+  if (!hasAdopted) return null;
+  const names = adopted.map((a) => `${a.rule}=${a.current}`).join(', ');
+  return `New or revised rules recorded as baseline (not gated this run): ${names}`;
+};
+
 export const evaluateGateVerdict = ({ violations, ratchetEval }) => {
+  const adopted = ratchetEval.adopted ?? [];
   const isRatchetBasis = RATCHET_STATUSES.has(ratchetEval.status);
   if (isRatchetBasis) {
     return {
       isPassing: ratchetEval.status === 'pass',
       basis: 'ratchet',
       regressions: ratchetEval.regressions,
-      note: ratchetEval.message ?? null
+      adopted,
+      note: ratchetEval.message ?? describeAdoption(adopted)
     };
   }
   const hasSevereViolation = violations.some(isSevereViolation);
-  return { isPassing: !hasSevereViolation, basis: 'severity', regressions: [], note: ratchetEval.message ?? null };
+  return { isPassing: !hasSevereViolation, basis: 'severity', regressions: [], adopted: [], note: ratchetEval.message ?? null };
 };
 
 const PARTIAL_SCAN_EVAL = {
   status: 'partial',
   regressions: [],
+  adopted: [],
   message: 'Partial scan (--git, --changed, or --fast): the ratchet applies to full scans only; using severity gate.'
 };
 
+const persistAdoption = (projectRoot, scope, ratchetEval) => {
+  const hasAdopted = ratchetEval.adopted?.length > 0;
+  const shouldPersist = hasAdopted || ratchetEval.isStale === true;
+  if (!shouldPersist) return;
+  try {
+    recordAdoptedRules(projectRoot, { scope, adopted: ratchetEval.adopted });
+  } catch (err) {
+    ratchetEval.message = `Could not record new-rule baselines: ${err.message}`;
+  }
+};
+
 export const computeGateVerdict = ({ projectRoot, scope, violations, isPartialScan = false }) => {
   const ratchetEval = isPartialScan ? PARTIAL_SCAN_EVAL : evaluateRatchet(readRatchet(projectRoot), { scope, violations });
+  if (!isPartialScan) persistAdoption(projectRoot, scope, ratchetEval);
   return evaluateGateVerdict({ violations, ratchetEval });
 };

package/cli/audit/history.d.ts

@@ -3,6 +3,10 @@ import type { MolecularHealthScore, CodebaseMetrics, PillarStatus, ContextTokenA
 export interface AuditSnapshot {
   readonly id: string;
   readonly timestamp: string;
+  /** Audited directory relative to the project root ('.' for the root); null or absent on older entries. */
+  readonly scope?: string | null;
+  /** True for --fast and --git audits, which check only part of the scope. */
+  readonly isPartial?: boolean;
   readonly health: MolecularHealthScore;
   readonly metrics: CodebaseMetrics;
   readonly violations: {
@@ -59,11 +63,19 @@ export interface SaveSnapshotResult {
 }
 
 export declare function ensureChemxDir(cwd?: string): string;
-export declare function createSnapshotFromReport(report: AuditReport): AuditSnapshot;
+export interface SnapshotScope {
+  readonly scope?: string | null;
+  readonly isPartial?: boolean;
+}
+
+export declare const HISTORY_PER_SCOPE: number;
+export declare const HISTORY_TOTAL: number;
+export declare function trimAuditHistory<T extends { readonly scope?: string | null }>(history: readonly T[], limits?: { perScope?: number; total?: number }): T[];
+export declare function createSnapshotFromReport(report: AuditReport, scopeInfo?: SnapshotScope): AuditSnapshot;
 export declare function getAuditHistory(cwd?: string): AuditSnapshot[];
 export declare function getAuditBaseline(cwd?: string): AuditSnapshot | null;
 export declare function setAuditBaseline(snapshot: AuditSnapshot, cwd?: string): AuditSnapshot;
-export declare function saveAuditSnapshot(report: AuditReport, cwd?: string): SaveSnapshotResult;
+export declare function saveAuditSnapshot(report: AuditReport, cwd?: string, scopeInfo?: SnapshotScope): SaveSnapshotResult;
 export declare function calculateTransformationDelta(beforeSnapshot: AuditSnapshot, afterSnapshot: AuditSnapshot): TransformationDelta;
 export declare function formatTransformationTerminal(beforeSnapshot: AuditSnapshot, afterSnapshot: AuditSnapshot): string;
 export declare function formatHistoryTimelineTerminal(history: readonly AuditSnapshot[]): string;