@ontrails/regrade 1.0.0-beta.29 → 1.0.0-beta.32

package/src/downstream/report.ts

@@ -1,4 +1,10 @@
-import { InternalError, Result } from '@ontrails/core';
+import {
+  InternalError,
+  Result,
+  escapeRegExp,
+  includedByPathScope,
+} from '@ontrails/core';
+import type { ScanTargets } from '@ontrails/core';
 import type {
   WardenDiagnostic,
   WardenFixEdit,
@@ -7,6 +13,7 @@ import type {
 import {
   getWardenRuleMetadata,
   isWardenSourceScanTarget,
+  loadProjectWardenRules,
   wardenRules,
 } from '@ontrails/warden';
 import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
@@ -18,6 +25,13 @@ import {
   collectDownstreamSources,
 } from './collect.js';
 import type { DownstreamCollectionOptions, SkippedSource } from './collect.js';
+import {
+  buildRegradeScanSummary,
+  regradeScanSummaryOutput,
+} from './scan-summary.js';
+import type { RegradeScanSummary } from './scan-summary.js';
+import type { VocabularyRegradeRun } from './vocabulary.js';
+import { vocabularyRegradeRunOutput } from './vocabulary.js';
 
 /**
  * Regrade-class selection and coverage reporting (TRL-845).
@@ -67,12 +81,14 @@ export interface RegradeClassContext {
 }
 
 /** Files a regrade class knows how to inspect. */
-export interface RegradeScanTargets {
-  /** Source extensions the class can inspect. */
-  readonly extensions?: readonly string[];
-  /** Directory names to skip during collection. */
+export type RegradeScanTargets = ScanTargets & {
+  /**
+   * @deprecated Use collection-level `exclude` globs. Preserved so existing
+   * Regrade classes can explicitly opt into directories the default collector
+   * prunes, such as `dist`, while migrating to PathScope.
+   */
   readonly ignoredDirectories?: readonly string[];
-}
+};
 
 /** One named, contract-aware transform. */
 export interface RegradeClass {
@@ -89,12 +105,22 @@ export interface RegradeClass {
   readonly scanTargets?: RegradeScanTargets;
 }
 
+export interface RegradeWardenClassSet {
+  /** Built-in and project-local Warden term-rewrite classes. */
+  readonly classes: readonly RegradeClass[];
+  /** Diagnostics raised while loading project-local rules. */
+  readonly diagnostics: readonly WardenDiagnostic[];
+}
+
 /** Which regrade classes a run should execute. */
 export interface RegradeSelection {
   /** Class ids to run. Omit to run every provided class. */
   readonly classIds?: readonly string[];
 }
 
+/** Which report entries should be returned. Counts always cover the full run. */
+export type RegradeReportEntrySelection = 'actionable' | 'all';
+
 /** Optional write summary for an apply-mode regrade run. */
 export interface RegradeApplySummary {
   /** Safe rewrite outcomes written to disk. */
@@ -137,9 +163,6 @@ export interface RegradeReviewDetail {
   readonly symbol?: string;
 }
 
-const escapeRegExp = (value: string): string =>
-  value.replaceAll(/[.*+?^${}()|[\]\\]/g, '\\$&');
-
 /**
  * Build a whole-word term-rewrite class.
  *
@@ -198,6 +221,27 @@ type WardenEditApplication =
   | { readonly ok: true; readonly nextSource: string }
   | { readonly ok: false; readonly reason: string };
 
+const regradeScanTargetsFromWardenFix = (
+  scanTargets: NonNullable<
+    NonNullable<ReturnType<typeof getWardenRuleMetadata>>['fix']
+  >['scanTargets']
+): RegradeScanTargets | undefined => {
+  if (scanTargets === undefined) {
+    return undefined;
+  }
+  return {
+    ...(scanTargets.exclude === undefined
+      ? {}
+      : { exclude: scanTargets.exclude }),
+    ...(scanTargets.extensions === undefined
+      ? {}
+      : { extensions: scanTargets.extensions }),
+    ...(scanTargets.ignoredDirectories === undefined
+      ? {}
+      : { ignoredDirectories: scanTargets.ignoredDirectories }),
+  };
+};
+
 const diagnosticNote = (diagnostic: WardenDiagnostic): string => {
   const reason = diagnostic.fix?.reason ?? diagnostic.message;
   return `${diagnostic.rule}:${diagnostic.line}: ${reason}`;
@@ -351,10 +395,11 @@ const applyWardenEdits = (
 export const createWardenTermRewriteClass = (
   rule: WardenRule
 ): RegradeClass | null => {
-  const metadata = getWardenRuleMetadata(rule.name);
+  const metadata = getWardenRuleMetadata(rule);
   if (metadata?.fix?.class !== TERM_REWRITE_FIX_CLASS) {
     return null;
   }
+  const scanTargets = regradeScanTargetsFromWardenFix(metadata.fix.scanTargets);
 
   return {
     apply: (
@@ -445,6 +490,7 @@ export const createWardenTermRewriteClass = (
     },
     describe: `${rule.description} (${metadata.fix.safety} ${metadata.fix.class})`,
     id: `${metadata.fix.class}:${rule.name}`,
+    ...(scanTargets === undefined ? {} : { scanTargets }),
   };
 };
 
@@ -479,29 +525,53 @@ export const selectRegradeClasses = (
 const uniqueSorted = (values: readonly string[]): readonly string[] =>
   [...new Set(values)].toSorted((a, b) => a.localeCompare(b));
 
+const intersectValues = (
+  left: readonly string[],
+  right: readonly string[]
+): readonly string[] => left.filter((value) => right.includes(value));
+
+const deriveClassIgnoredDirectories = (
+  classes: readonly RegradeClass[]
+): readonly string[] | undefined => {
+  const explicitTargets = classes
+    .map((cls) => cls.scanTargets?.ignoredDirectories)
+    .filter((value): value is readonly string[] => value !== undefined);
+  if (explicitTargets.length === 0) {
+    return undefined;
+  }
+
+  let common = explicitTargets[0] ?? [];
+  for (const target of explicitTargets.slice(1)) {
+    common = intersectValues(common, target);
+  }
+  return uniqueSorted(common);
+};
+
 const deriveCollectionOptions = (
   classes: readonly RegradeClass[],
   collection: DownstreamCollectionOptions | undefined
 ): DownstreamCollectionOptions => {
-  const targetExtensions = uniqueSorted(
-    classes.length === 0
-      ? DEFAULT_SOURCE_EXTENSIONS
-      : classes.flatMap(
-          (cls) => cls.scanTargets?.extensions ?? DEFAULT_SOURCE_EXTENSIONS
-        )
+  const allExtensions = classes.some(
+    (cls) => cls.scanTargets?.extensions?.length === 0
   );
-  const ignoredDirectories = uniqueSorted(
-    classes.length === 0
-      ? DEFAULT_IGNORED_DIRECTORIES
-      : classes.flatMap(
-          (cls) =>
-            cls.scanTargets?.ignoredDirectories ?? DEFAULT_IGNORED_DIRECTORIES
-        )
-  );
-
+  const targetExtensions = allExtensions
+    ? []
+    : uniqueSorted(
+        classes.length === 0
+          ? DEFAULT_SOURCE_EXTENSIONS
+          : classes.flatMap(
+              (cls) => cls.scanTargets?.extensions ?? DEFAULT_SOURCE_EXTENSIONS
+            )
+      );
   return {
+    ...(collection?.exclude === undefined
+      ? {}
+      : { exclude: collection.exclude }),
     extensions: collection?.extensions ?? targetExtensions,
-    ignoredDirectories: collection?.ignoredDirectories ?? ignoredDirectories,
+    ignoredDirectories:
+      collection?.ignoredDirectories ??
+      deriveClassIgnoredDirectories(classes) ??
+      DEFAULT_IGNORED_DIRECTORIES,
   };
 };
 
@@ -539,10 +609,16 @@ export interface RegradeReport {
   readonly review: number;
   /** Entries skipped (collection skips plus any run-level skips). */
   readonly skipped: number;
+  /** Skipped entries grouped by reason. */
+  readonly skipsByReason: Readonly<Record<string, number>>;
+  /** Agent-facing inventory summary for the scan. */
+  readonly scan: RegradeScanSummary;
   /** Per-entry detail, sorted by path. */
   readonly entries: readonly RegradeReportEntry[];
   /** Apply-mode summary; absent for dry-run report-only calls. */
   readonly apply?: RegradeApplySummary;
+  /** Vocabulary regrade run: plan, ledger, and completion report. */
+  readonly run?: VocabularyRegradeRun;
 }
 
 interface RegradeRewriteCandidate {
@@ -557,20 +633,76 @@ interface RegradeClassifiedFile {
   readonly rewrite?: RegradeRewriteCandidate;
 }
 
+const isIgnoredByClassDirectories = (
+  path: string,
+  ignoredDirectories: readonly string[] | undefined
+): boolean => {
+  if (ignoredDirectories === undefined || ignoredDirectories.length === 0) {
+    return false;
+  }
+  return path
+    .split('/')
+    .slice(0, -1)
+    .some((segment) => ignoredDirectories.includes(segment));
+};
+
+const classScanTargetSkip = (
+  cls: RegradeClass,
+  path: string,
+  collection: DownstreamCollectionOptions | undefined
+): RegradeClassResult | undefined => {
+  const ignoredDirectories =
+    collection?.ignoredDirectories ??
+    cls.scanTargets?.ignoredDirectories ??
+    DEFAULT_IGNORED_DIRECTORIES;
+  if (isIgnoredByClassDirectories(path, ignoredDirectories)) {
+    return {
+      kind: 'skipped',
+      notes: [`Skipped by ${cls.id} scan-target filtering.`],
+      reason: 'regrade-scan-target-filtered',
+    };
+  }
+  const effectiveScanTargets: ScanTargets | undefined =
+    cls.scanTargets?.extensions === undefined &&
+    collection?.extensions === undefined
+      ? {
+          ...cls.scanTargets,
+          extensions: DEFAULT_SOURCE_EXTENSIONS,
+        }
+      : cls.scanTargets;
+  if (
+    effectiveScanTargets === undefined ||
+    includedByPathScope(path, effectiveScanTargets)
+  ) {
+    return undefined;
+  }
+  return {
+    kind: 'skipped',
+    notes: [`Skipped by ${cls.id} scan-target filtering.`],
+    reason: 'regrade-scan-target-filtered',
+  };
+};
+
 const classifyFile = (
   path: string,
   source: string,
   context: RegradeClassContext,
-  selected: readonly RegradeClass[]
+  selected: readonly RegradeClass[],
+  collection?: DownstreamCollectionOptions
 ): RegradeClassifiedFile => {
   // First selected class that matches (rewrite or review) wins, mirroring the
-  // "run one class" emphasis. A scan-target skip is remembered so the file is
-  // accounted as skipped rather than a scanned/clean no-op. No-ops fall through.
+  // "run one class" emphasis. Scan-target skips only own the file when no
+  // selected class inspects it; a later no-op still counts as a clean scan.
   let skipped:
     | { readonly classId: string; readonly result: RegradeClassResult }
     | undefined;
+  let inspected = false;
   for (const cls of selected) {
-    const result = cls.apply(source, context);
+    const result =
+      classScanTargetSkip(cls, path, collection) ?? cls.apply(source, context);
+    if (result.kind !== 'skipped') {
+      inspected = true;
+    }
     if (result.kind === 'rewrite') {
       if (typeof result.nextSource !== 'string') {
         return {
@@ -623,7 +755,7 @@ const classifyFile = (
       skipped = { classId: cls.id, result };
     }
   }
-  if (skipped !== undefined) {
+  if (!inspected && skipped !== undefined) {
     return {
       entry: {
         classId: skipped.classId,
@@ -642,6 +774,32 @@ interface RegradeEvaluation {
   readonly rewrites: readonly RegradeRewriteCandidate[];
 }
 
+const includeEntryInReport = (
+  entry: RegradeReportEntry,
+  selection: RegradeReportEntrySelection
+): boolean =>
+  selection === 'all' ||
+  entry.outcome === 'rewrite' ||
+  entry.outcome === 'needs-review';
+
+const skipsByReason = (
+  entries: readonly RegradeReportEntry[]
+): Readonly<Record<string, number>> => {
+  const counts = new Map<string, number>();
+  for (const entry of entries) {
+    if (entry.outcome !== 'skip') {
+      continue;
+    }
+    const reason = entry.reason ?? 'skipped';
+    counts.set(reason, (counts.get(reason) ?? 0) + 1);
+  }
+  return Object.fromEntries(
+    [...counts.entries()].toSorted(([left], [right]) =>
+      left.localeCompare(right)
+    )
+  );
+};
+
 /**
  * Build a coverage report from already-read source files. Pure: no filesystem
  * access, so coverage semantics are testable directly.
@@ -656,7 +814,10 @@ const buildRegradeEvaluation = (params: {
   readonly skipped: readonly SkippedSource[];
   readonly classes: readonly RegradeClass[];
   readonly selection?: RegradeSelection;
+  readonly collection?: DownstreamCollectionOptions;
+  readonly includeEntries?: RegradeReportEntrySelection;
 }): RegradeEvaluation => {
+  const entrySelection = params.includeEntries ?? 'actionable';
   const { selected, unknownClassIds } = selectRegradeClasses(
     params.classes,
     params.selection
@@ -672,7 +833,8 @@ const buildRegradeEvaluation = (params: {
           : { absolutePath: file.absolutePath }),
         path: file.path,
       },
-      selected
+      selected,
+      params.collection
     )
   );
   const fileEntries = classifiedFiles.map((file) => file.entry);
@@ -685,9 +847,12 @@ const buildRegradeEvaluation = (params: {
     reason: entry.reason,
   }));
 
-  const entries = [...fileEntries, ...skipEntries].toSorted((a, b) =>
+  const allEntries = [...fileEntries, ...skipEntries].toSorted((a, b) =>
     a.path.localeCompare(b.path)
   );
+  const entries = allEntries.filter((entry) =>
+    includeEntryInReport(entry, entrySelection)
+  );
 
   // Class-level skips (e.g. scan-target filtering) are accounted as skipped, not
   // as scanned/clean files.
@@ -699,6 +864,11 @@ const buildRegradeEvaluation = (params: {
   const review = scannedEntries.filter(
     (e) => e.outcome === 'needs-review'
   ).length;
+  const matchedPaths = scannedEntries
+    .filter((e) => e.outcome === 'rewrite' || e.outcome === 'needs-review')
+    .map((entry) => entry.path);
+  const skipped = skipEntries.length + fileSkipCount;
+  const skippedReasons = skipsByReason(allEntries);
 
   return {
     report: {
@@ -707,9 +877,16 @@ const buildRegradeEvaluation = (params: {
       review,
       rewritten,
       root: params.root,
+      scan: buildRegradeScanSummary({
+        matchedPaths,
+        scanned: scannedEntries.length,
+        skipped,
+        skippedByReason: skippedReasons,
+      }),
       scanned: scannedEntries.length,
       selectedClassIds: selected.map((cls) => cls.id),
-      skipped: skipEntries.length + fileSkipCount,
+      skipped,
+      skipsByReason: skippedReasons,
       unknownClassIds,
     },
     rewrites,
@@ -726,6 +903,8 @@ export const buildRegradeReport = (params: {
   readonly skipped: readonly SkippedSource[];
   readonly classes: readonly RegradeClass[];
   readonly selection?: RegradeSelection;
+  readonly collection?: DownstreamCollectionOptions;
+  readonly includeEntries?: RegradeReportEntrySelection;
 }): RegradeReport => buildRegradeEvaluation(params).report;
 
 const applyRegradeEvaluation = (
@@ -797,6 +976,7 @@ const runRegradeEvaluation = (params: {
   readonly classes: readonly RegradeClass[];
   readonly selection?: RegradeSelection;
   readonly collection?: DownstreamCollectionOptions;
+  readonly includeEntries?: RegradeReportEntrySelection;
 }): RegradeEvaluation | null => {
   const { selected, unknownClassIds } = selectRegradeClasses(
     params.classes,
@@ -808,9 +988,15 @@ const runRegradeEvaluation = (params: {
     }
     return buildRegradeEvaluation({
       classes: params.classes,
+      ...(params.collection === undefined
+        ? {}
+        : { collection: params.collection }),
       files: [],
       root: params.root,
       skipped: [],
+      ...(params.includeEntries === undefined
+        ? {}
+        : { includeEntries: params.includeEntries }),
       ...(params.selection === undefined
         ? {}
         : { selection: params.selection }),
@@ -841,9 +1027,15 @@ const runRegradeEvaluation = (params: {
 
   return buildRegradeEvaluation({
     classes: params.classes,
+    ...(params.collection === undefined
+      ? {}
+      : { collection: params.collection }),
     files,
     root: params.root,
     skipped,
+    ...(params.includeEntries === undefined
+      ? {}
+      : { includeEntries: params.includeEntries }),
     ...(params.selection === undefined ? {} : { selection: params.selection }),
   });
 };
@@ -861,6 +1053,7 @@ export const runRegrade = (params: {
   readonly selection?: RegradeSelection;
   readonly collection?: DownstreamCollectionOptions;
   readonly apply?: boolean;
+  readonly includeEntries?: RegradeReportEntrySelection;
 }): Result<RegradeReport | null, InternalError> => {
   const evaluation = runRegradeEvaluation(params);
   if (evaluation === null) {
@@ -941,14 +1134,25 @@ export const regradeReportOutput = z.object({
     .describe('Apply-mode summary; absent for dry-run report-only calls'),
   entries: z
     .array(regradeReportEntrySchema)
-    .describe('Per-entry detail, sorted by path'),
+    .describe(
+      'Per-entry detail, sorted by path. Defaults to actionable rewrite/review entries.'
+    ),
   matched: z.number().describe('Files with a rewrite or review outcome'),
   review: z.number().describe('Files routed to review'),
   rewritten: z.number().describe('Files with a rewrite outcome'),
   root: z.string().describe('Root the run scanned'),
+  run: vocabularyRegradeRunOutput
+    .optional()
+    .describe('Vocabulary regrade run: plan, ledger, and completion report'),
+  scan: regradeScanSummaryOutput.describe(
+    'Agent-facing inventory summary for the scan'
+  ),
   scanned: z.number().describe('Source files inspected'),
   selectedClassIds: z.array(z.string()).describe('Class ids executed'),
   skipped: z.number().describe('Entries skipped'),
+  skipsByReason: z
+    .record(z.string(), z.number())
+    .describe('Skipped entries grouped by reason'),
   unknownClassIds: z
     .array(z.string())
     .describe('Selected ids that did not resolve to a class'),
@@ -967,3 +1171,55 @@ export const wardenTermRewriteClasses: readonly RegradeClass[] = Object.freeze(
     return cls === null ? [] : [cls];
   })
 );
+
+const duplicateClassDiagnostics = (
+  root: string,
+  classes: readonly RegradeClass[]
+): readonly WardenDiagnostic[] => {
+  const seen = new Set<string>();
+  const diagnostics: WardenDiagnostic[] = [];
+  for (const cls of classes) {
+    if (!seen.has(cls.id)) {
+      seen.add(cls.id);
+      continue;
+    }
+    diagnostics.push({
+      filePath: root,
+      line: 1,
+      message: `Duplicate Regrade class id "${cls.id}" from Warden term-rewrite rules.`,
+      rule: 'regrade-warden-term-rewrite-classes',
+      severity: 'error',
+    });
+  }
+  return diagnostics;
+};
+
+/**
+ * Load built-in and project-local Warden term-rewrite rules as Regrade classes.
+ *
+ * Built-ins are always available. When `root` is provided, committed
+ * project-local Warden rules under `.trails/rules.ts` or direct
+ * `.trails/rules/*.ts` modules are loaded and any term-rewrite-capable source
+ * rules join the class set.
+ */
+export const loadWardenTermRewriteClasses = async (
+  root?: string
+): Promise<RegradeWardenClassSet> => {
+  if (root === undefined) {
+    return { classes: wardenTermRewriteClasses, diagnostics: [] };
+  }
+
+  const projectRules = await loadProjectWardenRules(root);
+  const projectClasses = projectRules.sourceRules.flatMap((rule) => {
+    const cls = createWardenTermRewriteClass(rule);
+    return cls === null ? [] : [cls];
+  });
+  const classes = [...wardenTermRewriteClasses, ...projectClasses];
+  return {
+    classes,
+    diagnostics: [
+      ...projectRules.diagnostics,
+      ...duplicateClassDiagnostics(root, classes),
+    ],
+  };
+};