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

package/src/downstream/report.ts

@@ -8,6 +8,7 @@ import type { ScanTargets } from '@ontrails/core';
 import type {
   WardenDiagnostic,
   WardenFixEdit,
+  WardenGuidance,
   WardenRule,
 } from '@ontrails/warden';
 import {
@@ -16,7 +17,8 @@ import {
   loadProjectWardenRules,
   wardenRules,
 } from '@ontrails/warden';
-import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
 import { z } from 'zod';
 
 import {
@@ -78,6 +80,16 @@ export interface RegradeClassContext {
   readonly path: string;
   /** Absolute path on disk, when the caller has one. */
   readonly absolutePath?: string;
+  /** Nearest owning package facts, when filesystem collection found a manifest. */
+  readonly package?: {
+    readonly dependencies: readonly string[];
+    /** Runtime-visible dependency declarations (dependencies, optional, peer). */
+    readonly runtimeDependencies?: readonly string[];
+    readonly manifestState?: 'invalid' | 'valid';
+    readonly name?: string;
+    /** Root-relative POSIX manifest path. */
+    readonly path: string;
+  };
 }
 
 /** Files a regrade class knows how to inspect. */
@@ -143,18 +155,39 @@ export interface RegradeReviewSpan {
   readonly start: number;
 }
 
+/**
+ * Verdict state for a review detail.
+ *
+ * - `unresolved`: the class could not complete occurrence judgment; a human or
+ *   agent decision is still needed.
+ * - `preserve`: a completed verdict to keep the occurrence as-is.
+ * - `rewrite`: a completed verdict that a rewrite is intended but this run
+ *   could not apply it (for example invalid or missing edits).
+ */
+export type RegradeReviewJudgment = 'preserve' | 'rewrite' | 'unresolved';
+
 /** Structured detail explaining why a source match needs review. */
 export interface RegradeReviewDetail {
+  /** Concrete replacement the class would apply if the occurrence were judged safe. */
+  readonly candidateReplacement?: string;
   /** Class that produced the review detail, injected by report building. */
   readonly classId?: string;
   /** Expected target shape when the class can describe one. */
   readonly expectedTarget?: string;
   /** Fixture or example reference that illustrates the expected migration. */
   readonly fixture?: string;
+  /** Whether occurrence judgment is unresolved or a preserve/rewrite verdict completed. */
+  readonly judgment?: RegradeReviewJudgment;
+  /** Exact matched source text for the occurrence under review. */
+  readonly matchedForm?: string;
   /** AST node kind or source construct kind. */
   readonly nodeKind?: string;
+  /** Cautions explaining why a blind rewrite of this occurrence is unsafe. */
+  readonly preserveCautions?: readonly string[];
   /** Machine-readable reason for review. */
   readonly reason: string;
+  /** Machine-readable provenance tags for the producing rule or class. */
+  readonly signals?: readonly string[];
   /** Source span and line/column for the review-required match. */
   readonly span?: RegradeReviewSpan;
   /** Suggested validation command after the review is resolved. */
@@ -317,7 +350,9 @@ const diagnosticSpan = (
   return spanForSymbolOnDiagnosticLine(source, diagnostic.line, symbol);
 };
 
-const expectedTarget = (diagnostic: WardenDiagnostic): string | undefined => {
+const diagnosticCandidateReplacement = (
+  diagnostic: WardenDiagnostic
+): string | undefined => {
   const replacements = new Set(
     (diagnostic.fix?.edits ?? []).map((edit) => edit.replacement)
   );
@@ -325,32 +360,98 @@ const expectedTarget = (diagnostic: WardenDiagnostic): string | undefined => {
     return undefined;
   }
   const [replacement] = replacements;
+  return replacement;
+};
+
+const expectedTarget = (diagnostic: WardenDiagnostic): string | undefined => {
+  const replacement = diagnosticCandidateReplacement(diagnostic);
   return replacement === undefined
     ? undefined
     : `Replace with "${replacement}".`;
 };
 
+const isValidEditSpan = (
+  source: string,
+  edit: WardenFixEdit | undefined
+): edit is WardenFixEdit =>
+  edit !== undefined &&
+  Number.isInteger(edit.start) &&
+  Number.isInteger(edit.end) &&
+  edit.start >= 0 &&
+  edit.end >= edit.start &&
+  edit.end <= source.length;
+
+const diagnosticMatchedForm = (
+  source: string,
+  diagnostic: WardenDiagnostic,
+  symbol: string | undefined
+): string | undefined => {
+  const [edit] = diagnostic.fix?.edits ?? [];
+  if (isValidEditSpan(source, edit)) {
+    return source.slice(edit.start, edit.end);
+  }
+  return symbol;
+};
+
+const diagnosticSignals = (diagnostic: WardenDiagnostic): readonly string[] => [
+  `warden:${diagnostic.rule}`,
+  ...(diagnostic.code === undefined
+    ? []
+    : [`${diagnostic.rule}:${diagnostic.code}`]),
+];
+
+interface WardenReviewMappingOptions {
+  /** Verdict state for this review path. */
+  readonly judgment: RegradeReviewJudgment;
+  /** Machine-readable review reason. */
+  readonly reason: string;
+  /** Rule-level guidance used when a finding carries none of its own. */
+  readonly ruleGuidance?: WardenGuidance;
+}
+
+const reviewDetailFromDiagnostic = (
+  source: string,
+  diagnostic: WardenDiagnostic,
+  options: WardenReviewMappingOptions
+): RegradeReviewDetail => {
+  const symbol =
+    firstQuotedValue(diagnostic.fix?.reason) ??
+    firstQuotedValue(diagnostic.message);
+  const span = diagnosticSpan(source, diagnostic, symbol);
+  const target = expectedTarget(diagnostic);
+  const replacement = diagnosticCandidateReplacement(diagnostic);
+  const matchedForm = diagnosticMatchedForm(source, diagnostic, symbol);
+  const guidance = diagnostic.guidance ?? options.ruleGuidance;
+  const preserveCautions =
+    guidance === undefined
+      ? undefined
+      : [guidance.summary, ...(guidance.steps ?? [])];
+  const suggestedValidation = guidance?.commands?.[0];
+  return {
+    ...(replacement === undefined ? {} : { candidateReplacement: replacement }),
+    ...(target === undefined ? {} : { expectedTarget: target }),
+    ...(diagnostic.fix?.fixture === undefined
+      ? {}
+      : { fixture: diagnostic.fix.fixture }),
+    judgment: options.judgment,
+    ...(matchedForm === undefined ? {} : { matchedForm }),
+    ...(preserveCautions === undefined ? {} : { preserveCautions }),
+    reason: options.reason,
+    signals: diagnosticSignals(diagnostic),
+    ...(span === undefined ? {} : { span }),
+    ...(suggestedValidation === undefined ? {} : { suggestedValidation }),
+    ...(symbol === undefined ? {} : { symbol }),
+  } satisfies RegradeReviewDetail;
+};
+
 const reviewDetailsFromDiagnostics = (
   source: string,
   diagnostics: readonly WardenDiagnostic[],
-  reason: string
+  options: WardenReviewMappingOptions
 ): readonly RegradeReviewDetail[] | undefined => {
-  const details = diagnostics.map((diagnostic) => {
-    const symbol =
-      firstQuotedValue(diagnostic.fix?.reason) ??
-      firstQuotedValue(diagnostic.message);
-    const span = diagnosticSpan(source, diagnostic, symbol);
-    const target = expectedTarget(diagnostic);
-    return {
-      ...(target === undefined ? {} : { expectedTarget: target }),
-      ...(diagnostic.fix?.fixture === undefined
-        ? {}
-        : { fixture: diagnostic.fix.fixture }),
-      reason,
-      ...(span === undefined ? {} : { span }),
-      ...(symbol === undefined ? {} : { symbol }),
-    } satisfies RegradeReviewDetail;
-  });
+  const details = diagnostics.map((diagnostic) =>
+    reviewDetailFromDiagnostic(source, diagnostic, options)
+  );
   return details.length === 0 ? undefined : details;
 };
 
@@ -431,10 +532,18 @@ export const createWardenTermRewriteClass = (
         (diagnostic) => diagnostic.fix?.safety !== 'safe'
       );
       if (reviewDiagnostics.length > 0) {
+        // The rule flagged the occurrence but marked it review: occurrence
+        // judgment is unresolved and needs a human or agent decision.
         const reviewDetails = reviewDetailsFromDiagnostics(
           source,
           reviewDiagnostics,
-          'warden-review-required'
+          {
+            judgment: 'unresolved',
+            reason: 'warden-review-required',
+            ...(metadata.guidance === undefined
+              ? {}
+              : { ruleGuidance: metadata.guidance }),
+          }
         );
         return {
           kind: 'needs-review',
@@ -448,10 +557,18 @@ export const createWardenTermRewriteClass = (
         (diagnostic) => (diagnostic.fix?.edits?.length ?? 0) === 0
       );
       if (diagnosticsMissingEdits.length > 0) {
+        // A safe fix without concrete edits cannot complete occurrence
+        // judgment on its own, so the verdict stays unresolved.
         const reviewDetails = reviewDetailsFromDiagnostics(
           source,
           diagnosticsMissingEdits,
-          'warden-fix-missing-edits'
+          {
+            judgment: 'unresolved',
+            reason: 'warden-fix-missing-edits',
+            ...(metadata.guidance === undefined
+              ? {}
+              : { ruleGuidance: metadata.guidance }),
+          }
         );
         return {
           kind: 'needs-review',
@@ -466,10 +583,18 @@ export const createWardenTermRewriteClass = (
       );
       const application = applyWardenEdits(source, edits);
       if (!application.ok) {
+        // The rule completed judgment — it authored concrete edits — but this
+        // run could not apply them, so the verdict is a rewrite left undone.
         const reviewDetails = reviewDetailsFromDiagnostics(
           source,
           diagnostics,
-          'warden-fix-invalid'
+          {
+            judgment: 'rewrite',
+            reason: 'warden-fix-invalid',
+            ...(metadata.guidance === undefined
+              ? {}
+              : { ruleGuidance: metadata.guidance }),
+          }
         );
         return {
           kind: 'needs-review',
@@ -567,6 +692,9 @@ const deriveCollectionOptions = (
     ...(collection?.exclude === undefined
       ? {}
       : { exclude: collection.exclude }),
+    ...(collection?.include === undefined
+      ? {}
+      : { include: collection.include }),
     extensions: collection?.extensions ?? targetExtensions,
     ignoredDirectories:
       collection?.ignoredDirectories ??
@@ -619,6 +747,28 @@ export interface RegradeReport {
   readonly apply?: RegradeApplySummary;
   /** Vocabulary regrade run: plan, ledger, and completion report. */
   readonly run?: VocabularyRegradeRun;
+  /** Saved active Regrade plan evidence for vocabulary regrades. */
+  readonly plan?: {
+    readonly expansionPending?: number;
+    readonly path: string;
+    readonly schemaVersion: number;
+    readonly status: 'active' | 'stale';
+  };
+  /** Saved applied Regrade history evidence for vocabulary regrades. */
+  readonly history?: {
+    readonly path: string;
+    readonly schemaVersion: number;
+    readonly status: 'applied' | 'checked' | 'replay';
+  };
+  /**
+   * @deprecated Persisted transition record evidence for vocabulary regrades.
+   *   Use `plan` and `history` summaries in public surfaces.
+   */
+  readonly record?: {
+    readonly path: string;
+    readonly schemaVersion: number;
+    readonly status: 'candidate' | 'applied' | 'checked';
+  };
 }
 
 interface RegradeRewriteCandidate {
@@ -690,16 +840,20 @@ const classifyFile = (
   selected: readonly RegradeClass[],
   collection?: DownstreamCollectionOptions
 ): RegradeClassifiedFile => {
-  // First selected class that matches (rewrite or review) wins, mirroring the
-  // "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.
+  // Compose safe rewrites across selected classes in memory so one governed
+  // transition can move every compatible symbol in a file. Review still wins:
+  // if any class needs judgment, no partial rewrite is returned for that file.
   let skipped:
     | { readonly classId: string; readonly result: RegradeClassResult }
     | undefined;
   let inspected = false;
+  let currentSource = source;
+  const rewriteClassIds: string[] = [];
+  const rewriteNotes: string[] = [];
   for (const cls of selected) {
     const result =
-      classScanTargetSkip(cls, path, collection) ?? cls.apply(source, context);
+      classScanTargetSkip(cls, path, collection) ??
+      cls.apply(currentSource, context);
     if (result.kind !== 'skipped') {
       inspected = true;
     }
@@ -715,38 +869,29 @@ const classifyFile = (
           },
         };
       }
-      const entry = {
-        classId: cls.id,
-        notes: result.notes,
-        outcome: 'rewrite',
-        path,
-      } satisfies RegradeReportEntry;
-      return {
-        entry,
-        ...(context.absolutePath === undefined
-          ? {}
-          : {
-              rewrite: {
-                absolutePath: context.absolutePath,
-                classId: cls.id,
-                nextSource: result.nextSource,
-                path,
-              },
-            }),
-      };
+      currentSource = result.nextSource;
+      rewriteClassIds.push(cls.id);
+      rewriteNotes.push(...(result.notes ?? []));
+      continue;
     }
     if (result.kind === 'needs-review') {
-      const reviewDetails = result.reviewDetails?.map((detail) => ({
+      const originalSourceResult =
+        currentSource === source ? result : cls.apply(source, context);
+      const reviewResult =
+        originalSourceResult.kind === 'needs-review'
+          ? originalSourceResult
+          : result;
+      const reviewDetails = reviewResult.reviewDetails?.map((detail) => ({
         ...detail,
         classId: detail.classId ?? cls.id,
       }));
       return {
         entry: {
           classId: cls.id,
-          notes: result.notes,
+          notes: reviewResult.notes,
           outcome: 'needs-review',
           path,
-          reason: result.reason ?? 'needs-review',
+          reason: reviewResult.reason ?? 'needs-review',
           ...(reviewDetails === undefined ? {} : { reviewDetails }),
         },
       };
@@ -755,6 +900,28 @@ const classifyFile = (
       skipped = { classId: cls.id, result };
     }
   }
+  if (rewriteClassIds.length > 0) {
+    const classId = rewriteClassIds.join(',');
+    const entry = {
+      classId,
+      notes: rewriteNotes,
+      outcome: 'rewrite',
+      path,
+    } satisfies RegradeReportEntry;
+    return {
+      entry,
+      ...(context.absolutePath === undefined
+        ? {}
+        : {
+            rewrite: {
+              absolutePath: context.absolutePath,
+              classId,
+              nextSource: currentSource,
+              path,
+            },
+          }),
+    };
+  }
   if (!inspected && skipped !== undefined) {
     return {
       entry: {
@@ -810,6 +977,7 @@ const buildRegradeEvaluation = (params: {
     readonly path: string;
     readonly source: string;
     readonly absolutePath?: string;
+    readonly package?: RegradeClassContext['package'];
   }[];
   readonly skipped: readonly SkippedSource[];
   readonly classes: readonly RegradeClass[];
@@ -831,6 +999,7 @@ const buildRegradeEvaluation = (params: {
         ...(file.absolutePath === undefined
           ? {}
           : { absolutePath: file.absolutePath }),
+        ...(file.package === undefined ? {} : { package: file.package }),
         path: file.path,
       },
       selected,
@@ -899,6 +1068,7 @@ export const buildRegradeReport = (params: {
     readonly path: string;
     readonly source: string;
     readonly absolutePath?: string;
+    readonly package?: RegradeClassContext['package'];
   }[];
   readonly skipped: readonly SkippedSource[];
   readonly classes: readonly RegradeClass[];
@@ -971,6 +1141,121 @@ const canReadDownstreamRoot = (root: string): boolean => {
   }
 };
 
+const PACKAGE_DEPENDENCY_FIELDS = [
+  'dependencies',
+  'devDependencies',
+  'optionalDependencies',
+  'peerDependencies',
+] as const;
+
+const RUNTIME_PACKAGE_DEPENDENCY_FIELDS = [
+  'dependencies',
+  'optionalDependencies',
+  'peerDependencies',
+] as const;
+
+const dependencyNames = (
+  manifest: Readonly<Record<string, unknown>>,
+  fields: readonly (typeof PACKAGE_DEPENDENCY_FIELDS)[number][]
+): readonly string[] =>
+  fields.flatMap((field) => {
+    const value = manifest[field];
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+      ? Object.keys(value)
+      : [];
+  });
+
+const packageContextFor = (
+  root: string,
+  absolutePath: string,
+  cache: Map<string, RegradeClassContext['package'] | undefined>
+): RegradeClassContext['package'] | undefined => {
+  const absoluteRoot = resolve(root);
+  let current = dirname(absolutePath);
+  const visited: string[] = [];
+  while (true) {
+    if (cache.has(current)) {
+      const cached = cache.get(current);
+      for (const directory of visited) {
+        cache.set(directory, cached);
+      }
+      return cached;
+    }
+    visited.push(current);
+    const fromRoot = relative(absoluteRoot, current);
+    if (fromRoot.startsWith('..') || resolve(current) !== current) {
+      break;
+    }
+    const manifestPath = join(current, 'package.json');
+    if (existsSync(manifestPath)) {
+      const manifestRelativePath = relative(
+        absoluteRoot,
+        manifestPath
+      ).replaceAll('\\', '/');
+      try {
+        const parsed = JSON.parse(
+          readFileSync(manifestPath, 'utf8')
+        ) as unknown;
+        if (
+          typeof parsed !== 'object' ||
+          parsed === null ||
+          Array.isArray(parsed)
+        ) {
+          const invalidContext = {
+            dependencies: [],
+            manifestState: 'invalid' as const,
+            path: manifestRelativePath,
+          };
+          for (const directory of visited) {
+            cache.set(directory, invalidContext);
+          }
+          return invalidContext;
+        }
+        const manifest = parsed as Record<string, unknown>;
+        const dependencies = dependencyNames(
+          manifest,
+          PACKAGE_DEPENDENCY_FIELDS
+        );
+        const runtimeDependencies = dependencyNames(
+          manifest,
+          RUNTIME_PACKAGE_DEPENDENCY_FIELDS
+        );
+        const packageContext = {
+          dependencies: [...new Set(dependencies)].toSorted(),
+          manifestState: 'valid' as const,
+          ...(typeof manifest['name'] === 'string'
+            ? { name: manifest['name'] }
+            : {}),
+          path: manifestRelativePath,
+          runtimeDependencies: [...new Set(runtimeDependencies)].toSorted(),
+        };
+        for (const directory of visited) {
+          cache.set(directory, packageContext);
+        }
+        return packageContext;
+      } catch {
+        const invalidContext = {
+          dependencies: [],
+          manifestState: 'invalid' as const,
+          path: manifestRelativePath,
+        };
+        for (const directory of visited) {
+          cache.set(directory, invalidContext);
+        }
+        return invalidContext;
+      }
+    }
+    if (current === absoluteRoot) {
+      break;
+    }
+    current = dirname(current);
+  }
+  for (const directory of visited) {
+    cache.set(directory, undefined);
+  }
+  return undefined;
+};
+
 const runRegradeEvaluation = (params: {
   readonly root: string;
   readonly classes: readonly RegradeClass[];
@@ -1013,10 +1298,20 @@ const runRegradeEvaluation = (params: {
 
   const files: { absolutePath: string; path: string; source: string }[] = [];
   const skipped: SkippedSource[] = [...collected.skipped];
+  const packageContextCache = new Map<
+    string,
+    RegradeClassContext['package'] | undefined
+  >();
   for (const file of collected.files) {
     try {
+      const packageContext = packageContextFor(
+        params.root,
+        file.absolutePath,
+        packageContextCache
+      );
       files.push({
         absolutePath: file.absolutePath,
+        ...(packageContext === undefined ? {} : { package: packageContext }),
         path: file.path,
         source: readFileSync(file.absolutePath, 'utf8'),
       });
@@ -1083,6 +1378,12 @@ const regradeReportEntrySchema = z.object({
   reviewDetails: z
     .array(
       z.object({
+        candidateReplacement: z
+          .string()
+          .optional()
+          .describe(
+            'Concrete replacement the class would apply if the occurrence were judged safe'
+          ),
         classId: z
           .string()
           .optional()
@@ -1095,11 +1396,35 @@ const regradeReportEntrySchema = z.object({
           .string()
           .optional()
           .describe('Fixture or example reference for the migration'),
+        judgment: z
+          .enum(['preserve', 'rewrite', 'unresolved'])
+          .optional()
+          .describe(
+            'Verdict state: unresolved = occurrence judgment is incomplete and needs a human or agent decision; preserve = completed verdict to keep the occurrence; rewrite = completed verdict that a rewrite is intended but this run could not apply it'
+          ),
+        matchedForm: z
+          .string()
+          .optional()
+          .describe(
+            'Exact matched source text for the occurrence under review'
+          ),
         nodeKind: z
           .string()
           .optional()
           .describe('AST node kind or source construct kind'),
+        preserveCautions: z
+          .array(z.string())
+          .optional()
+          .describe(
+            'Cautions explaining why a blind rewrite of this occurrence is unsafe'
+          ),
         reason: z.string().describe('Machine-readable review reason'),
+        signals: z
+          .array(z.string())
+          .optional()
+          .describe(
+            'Machine-readable provenance tags for the producing rule or class'
+          ),
         span: z
           .object({
             column: z.number().describe('One-based source column'),
@@ -1137,7 +1462,43 @@ export const regradeReportOutput = z.object({
     .describe(
       'Per-entry detail, sorted by path. Defaults to actionable rewrite/review entries.'
     ),
+  history: z
+    .object({
+      path: z.string().describe('Root-relative applied history entry path'),
+      schemaVersion: z.number().describe('Regrade history schema version'),
+      status: z
+        .enum(['applied', 'checked', 'replay'])
+        .describe(
+          'How this command used the Regrade history file: applied = run appended, replay = identical re-run recognized and not duplicated, checked = consolidated history verified per-run'
+        ),
+    })
+    .optional()
+    .describe('Saved applied Regrade history evidence'),
   matched: z.number().describe('Files with a rewrite or review outcome'),
+  plan: z
+    .object({
+      expansionPending: z
+        .number()
+        .optional()
+        .describe('Pending staged expansion candidates on this plan'),
+      path: z.string().describe('Root-relative Regrade plan path'),
+      schemaVersion: z.number().describe('Regrade plan schema version'),
+      status: z
+        .enum(['active', 'stale'])
+        .describe('Whether the saved plan still matches the source tree'),
+    })
+    .optional()
+    .describe('Saved active Regrade plan evidence'),
+  record: z
+    .object({
+      path: z.string().describe('Root-relative transition record path'),
+      schemaVersion: z.number().describe('Transition record schema version'),
+      status: z
+        .enum(['candidate', 'applied', 'checked'])
+        .describe('How this command used the transition record'),
+    })
+    .optional()
+    .describe('Persisted transition record evidence'),
   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'),