@ontrails/regrade 1.0.0-beta.45 → 1.0.0-beta.47

package/src/downstream/vocabulary.ts

@@ -6,6 +6,8 @@ import {
   isPlainObject,
   matchesAnyPathGlob,
 } from '@ontrails/core';
+import { parseWithDiagnostics } from '@ontrails/source';
+import type { SourceComment } from '@ontrails/source';
 import { createHash } from 'node:crypto';
 import {
   dirname,
@@ -24,6 +26,7 @@ import {
 } from './collect.js';
 import type { DownstreamCollectionOptions, SkippedSource } from './collect.js';
 import type {
+  PreparedRegradeRunIdentity,
   RegradeApplySummary,
   RegradeReport,
   RegradeReportEntry,
@@ -32,6 +35,8 @@ import { buildRegradeScanSummary } from './scan-summary.js';
 
 export type VocabularyVerdict = 'applied' | 'deferred' | 'modified' | 'skipped';
 
+export type VocabularyOccurrenceSourceKind = 'source-comment' | 'tsdoc';
+
 export const vocabularyDispositionValues = [
   'code-context-out-of-engine',
   'docs-only',
@@ -170,6 +175,7 @@ export interface VocabularyOccurrence {
   readonly replacement?: string;
   readonly start: number;
   readonly scopeTier: VocabularyScopeTier;
+  readonly sourceKind?: VocabularyOccurrenceSourceKind;
   readonly verdict: VocabularyVerdict;
 }
 
@@ -247,12 +253,23 @@ interface SourceFile {
   readonly absolutePath: string;
   readonly path: string;
   readonly source: string;
+  readonly sourceBytes: string;
 }
 
 interface SourceOccurrence extends VocabularyOccurrence {
   readonly absolutePath: string;
 }
 
+type VocabularySourceKind = 'all' | 'comments';
+
+const sourceCommentKind = (
+  file: SourceFile,
+  comment: SourceComment
+): VocabularyOccurrenceSourceKind =>
+  comment.type === 'Block' && file.source.startsWith('/**', comment.start)
+    ? 'tsdoc'
+    : 'source-comment';
+
 interface SourceOccurrenceDraft extends Omit<
   SourceOccurrence,
   'disposition' | 'reason' | 'scopeTier' | 'verdict'
@@ -450,7 +467,16 @@ const lineColumnForOffset = (
   let line = 1;
   let column = 1;
   for (let index = 0; index < offset; index += 1) {
-    if (source.codePointAt(index) === 10) {
+    const codePoint = source.codePointAt(index);
+    if (
+      codePoint === 10 ||
+      codePoint === 13 ||
+      codePoint === 0x20_28 ||
+      codePoint === 0x20_29
+    ) {
+      if (codePoint === 13 && source.codePointAt(index + 1) === 10) {
+        index += 1;
+      }
       line += 1;
       column = 1;
     } else {
@@ -465,9 +491,32 @@ const contextDetailsForOffset = (
   start: number,
   end: number
 ): { readonly context: string; readonly contextColumn: number } => {
-  const lineStart = source.lastIndexOf('\n', start - 1) + 1;
-  const nextLine = source.indexOf('\n', end);
-  const lineEnd = nextLine === -1 ? source.length : nextLine;
+  let lineStart = start;
+  while (lineStart > 0) {
+    const codePoint = source.codePointAt(lineStart - 1);
+    if (
+      codePoint === 10 ||
+      codePoint === 13 ||
+      codePoint === 0x20_28 ||
+      codePoint === 0x20_29
+    ) {
+      break;
+    }
+    lineStart -= 1;
+  }
+  let lineEnd = end;
+  while (lineEnd < source.length) {
+    const codePoint = source.codePointAt(lineEnd);
+    if (
+      codePoint === 10 ||
+      codePoint === 13 ||
+      codePoint === 0x20_28 ||
+      codePoint === 0x20_29
+    ) {
+      break;
+    }
+    lineEnd += 1;
+  }
   const rawLine = source.slice(lineStart, lineEnd);
   const leadingTrimmed = rawLine.length - rawLine.trimStart().length;
   return {
@@ -735,6 +784,21 @@ const deferFormsForPlan = (plan: VocabularyRegradePlan): readonly string[] => {
   ]);
 };
 
+const titleCaseVocabularyForm = (form: string): string => {
+  const first = form.at(0);
+  return first === undefined ? form : `${first.toUpperCase()}${form.slice(1)}`;
+};
+
+const commentReviewPlan = (
+  plan: VocabularyRegradePlan
+): VocabularyRegradePlan => ({
+  ...plan,
+  deferForms: uniqueSorted([
+    ...(plan.deferForms ?? []),
+    ...(plan.deferForms ?? []).map(titleCaseVocabularyForm),
+  ]),
+});
+
 /**
  * Synthesize the deterministic form proposal carried by a minimal plan seed.
  *
@@ -1471,8 +1535,19 @@ const entryForOccurrences = (
       reviewDetails: occurrences
         .filter((occurrence) => occurrence.verdict === 'deferred')
         .map((occurrence) => ({
+          context: occurrence.context,
           expectedTarget:
             'Add an override or preserve rule to the regrade plan.',
+          judgment: 'unresolved' as const,
+          matchedForm: occurrence.form,
+          ...(occurrence.sourceKind === undefined
+            ? {}
+            : {
+                nodeKind:
+                  occurrence.sourceKind === 'tsdoc'
+                    ? 'TSDocComment'
+                    : 'SourceComment',
+              }),
           reason: occurrence.reason,
           span: {
             column: occurrence.column,
@@ -1528,6 +1603,9 @@ const buildVocabularyEvaluation = (params: {
   readonly preserveInventory?: readonly VocabularyPreserveInventoryEntry[];
   readonly root: string;
   readonly skipped: readonly SkippedSource[];
+  readonly sourceKindForPath?:
+    | ((path: string) => VocabularySourceKind)
+    | undefined;
 }): VocabularyEvaluation => {
   const effectivePlan = params.effectivePlan ?? params.plan;
   const targetForms = targetFormsForPlan(effectivePlan);
@@ -1537,21 +1615,59 @@ const buildVocabularyEvaluation = (params: {
   const scopeSkipped: SkippedSource[] = params.files
     .filter((file) => !includedByScope(file.path, effectivePlan.scope))
     .map((file) => ({ path: file.path, reason: 'excluded-by-regrade-scope' }));
+  const commentParseSkipped: SkippedSource[] = [];
   const occurrences = scopedFiles.flatMap((file) => {
+    const sourceKind = params.sourceKindForPath?.(file.path) ?? 'all';
+    const scanPlan =
+      sourceKind === 'comments'
+        ? commentReviewPlan(effectivePlan)
+        : effectivePlan;
     const deferredOccurrences = deferredOccurrencesForFile(
       file,
-      effectivePlan,
+      scanPlan,
       targetForms
     );
-    return [
-      ...occurrencesForFile(
-        file,
-        effectivePlan,
-        targetForms,
-        deferredOccurrences
-      ),
+    const fileOccurrences = [
+      ...occurrencesForFile(file, scanPlan, targetForms, deferredOccurrences),
       ...deferredOccurrences,
     ];
+    if (sourceKind === 'all') {
+      return fileOccurrences;
+    }
+    if (fileOccurrences.length === 0) {
+      return [];
+    }
+    const parsed = parseWithDiagnostics(file.path, file.source);
+    if (parsed.diagnostics.length > 0 || parsed.ast === null) {
+      commentParseSkipped.push({
+        path: file.path,
+        reason: 'source-comment-parse-diagnostics',
+      });
+      return [];
+    }
+    return fileOccurrences.flatMap((occurrence) => {
+      const comment = parsed.comments.find(
+        (candidate) =>
+          candidate.start <= occurrence.start && occurrence.end <= candidate.end
+      );
+      if (comment === undefined) {
+        return [];
+      }
+      const sourceKindForOccurrence = sourceCommentKind(file, comment);
+      if (occurrence.verdict === 'skipped') {
+        return [{ ...occurrence, sourceKind: sourceKindForOccurrence }];
+      }
+      const { replacement: _replacement, ...reviewOccurrence } = occurrence;
+      return [
+        {
+          ...reviewOccurrence,
+          disposition: 'in-family-unresolved' as const,
+          reason: 'source-comment-requires-review',
+          sourceKind: sourceKindForOccurrence,
+          verdict: 'deferred' as const,
+        },
+      ];
+    });
   });
   const occurrencesByPath = new Map<string, SourceOccurrence[]>();
   for (const occurrence of occurrences) {
@@ -1599,6 +1715,9 @@ const buildVocabularyEvaluation = (params: {
   if (deferredForms.length > 0) {
     gateReasons.push('deferred-forms-or-occurrences');
   }
+  if (commentParseSkipped.length > 0) {
+    gateReasons.push('source-comment-parse-diagnostics');
+  }
   const open = unresolvedOccurrences.length;
   const scopeEvidence = vocabularyScopeEvidence(effectivePlan, occurrences);
   gateReasons.push(...scopeEvidence.gateReasons);
@@ -1616,6 +1735,11 @@ const buildVocabularyEvaluation = (params: {
         path: entry.path,
         reason: entry.reason,
       })),
+      ...commentParseSkipped.map((entry) => ({
+        outcome: 'skip' as const,
+        path: entry.path,
+        reason: entry.reason,
+      })),
     ].toSorted((left, right) => left.path.localeCompare(right.path)),
     occurrences,
     run: {
@@ -1652,7 +1776,7 @@ const buildVocabularyEvaluation = (params: {
       },
     },
     scanned: scopedFiles.length,
-    skipped: [...params.skipped, ...scopeSkipped],
+    skipped: [...params.skipped, ...scopeSkipped, ...commentParseSkipped],
   };
 };
 
@@ -1670,13 +1794,37 @@ const skippedByReason = (
   );
 };
 
+const withScannedPaths = (
+  report: RegradeReport,
+  paths: readonly string[]
+): RegradeReport => {
+  Object.defineProperty(report, 'scannedPaths', {
+    configurable: false,
+    enumerable: false,
+    value: Object.freeze([...paths]),
+    writable: false,
+  });
+  return report;
+};
+
+const cloneVocabularyReport = (report: RegradeReport): RegradeReport => {
+  const clone = structuredClone(report);
+  return report.scannedPaths === undefined
+    ? clone
+    : withScannedPaths(clone, report.scannedPaths);
+};
+
 const withApplySummary = (
   report: RegradeReport,
   apply: RegradeApplySummary
-): RegradeReport => ({
-  ...report,
-  apply,
-});
+): RegradeReport =>
+  withScannedPaths(
+    {
+      ...report,
+      apply,
+    },
+    report.scannedPaths ?? []
+  );
 
 const appliedVocabularyRunReport = (
   postApply: VocabularyRegradeRun,
@@ -1802,10 +1950,12 @@ const readVocabularySourceFiles = (
   const skipped: SkippedSource[] = [...collected.skipped];
   for (const file of collected.files) {
     try {
+      const bytes = readFileSync(file.absolutePath);
       files.push({
         absolutePath: file.absolutePath,
         path: file.path,
-        source: readFileSync(file.absolutePath, 'utf8'),
+        source: bytes.toString('utf8'),
+        sourceBytes: bytes.toString('base64'),
       });
     } catch {
       skipped.push({ path: file.path, reason: 'unreadable-file' });
@@ -1824,6 +1974,9 @@ const buildRunVocabularyEvaluation = (params: {
     | undefined;
   readonly root: string;
   readonly skipped: readonly SkippedSource[];
+  readonly sourceKindForPath?:
+    | ((path: string) => VocabularySourceKind)
+    | undefined;
 }): VocabularyEvaluation =>
   buildVocabularyEvaluation({
     apply: params.apply,
@@ -1835,6 +1988,7 @@ const buildRunVocabularyEvaluation = (params: {
       : { preserveInventory: params.preserveInventory }),
     root: params.root,
     skipped: params.skipped,
+    sourceKindForPath: params.sourceKindForPath,
   });
 
 const ignoredDirectoriesOpenedByPolicy = (
@@ -1893,30 +2047,48 @@ const filterVocabularyCollection = (
   };
 };
 
-export const runVocabularyRegrade = (params: {
-  readonly apply?: boolean;
+interface VocabularyRunInputs {
+  readonly collectedRoot: string;
+  readonly effectivePlan: VocabularyRegradePlan;
+  readonly files: readonly SourceFile[];
+  readonly skipped: readonly SkippedSource[];
+}
+
+interface PrepareVocabularyRegradeRunParams {
   readonly includeEntries?: 'actionable' | 'all';
   readonly plan: VocabularyRegradePlan;
   readonly preserveInventory?: readonly VocabularyPreserveInventoryEntry[];
   readonly root: string;
   readonly sourceFilter?: (path: string) => boolean;
-}): Result<RegradeReport | null, InternalError | ValidationError> => {
-  const planValidation = validateVocabularyPlan(params.plan);
-  if (planValidation.isErr()) {
-    return planValidation;
-  }
-  const inventoryValidation = validatePreserveInventory(
-    params.preserveInventory
-  );
-  if (inventoryValidation.isErr()) {
-    return inventoryValidation;
-  }
+  readonly sourceKindForPath?: (path: string) => VocabularySourceKind;
+}
+
+const snapshotPrepareVocabularyRegradeRunParams = (
+  params: PrepareVocabularyRegradeRunParams
+): PrepareVocabularyRegradeRunParams => ({
+  ...(params.includeEntries === undefined
+    ? {}
+    : { includeEntries: params.includeEntries }),
+  plan: structuredClone(params.plan),
+  ...(params.preserveInventory === undefined
+    ? {}
+    : { preserveInventory: structuredClone(params.preserveInventory) }),
+  root: params.root,
+  ...(params.sourceFilter === undefined
+    ? {}
+    : { sourceFilter: params.sourceFilter }),
+  ...(params.sourceKindForPath === undefined
+    ? {}
+    : { sourceKindForPath: params.sourceKindForPath }),
+});
 
+const collectVocabularyRunInputs = (
+  params: PrepareVocabularyRegradeRunParams
+): VocabularyRunInputs | null => {
   const effectivePlan = effectivePlanForRun(
     params.plan,
     params.preserveInventory
   );
-
   const collected = collectDownstreamSources(params.root, {
     extensions: effectivePlan.scope?.extensions ?? VOCABULARY_SOURCE_EXTENSIONS,
     ...(effectivePlan.scope?.exclude === undefined
@@ -1928,20 +2100,365 @@ export const runVocabularyRegrade = (params: {
     ignoredDirectories: vocabularyIgnoredDirectories(effectivePlan.scope),
   } satisfies DownstreamCollectionOptions);
   if (collected === null) {
-    return Result.ok(null);
+    return null;
   }
-
   const filtered = filterVocabularyCollection(
     collected.files,
     effectivePlan.scope,
     params.sourceFilter
   );
-  const { files, skipped: readSkipped } = readVocabularySourceFiles({
+  const { files, skipped } = readVocabularySourceFiles({
     ...collected,
     files: filtered.files,
     skipped: [...collected.skipped, ...filtered.skipped],
   });
-  const skipped = readSkipped;
+  return { collectedRoot: collected.root, effectivePlan, files, skipped };
+};
+
+const vocabularyReportFromEvaluation = (params: {
+  readonly applySummary?: RegradeApplySummary;
+  readonly collectedRoot: string;
+  readonly dryRunEvaluation: VocabularyEvaluation;
+  readonly effectivePlan: VocabularyRegradePlan;
+  readonly entrySelection: 'actionable' | 'all';
+  readonly files: readonly SourceFile[];
+  readonly plan: VocabularyRegradePlan;
+  readonly reportEvaluation: VocabularyEvaluation;
+  readonly skipped: readonly SkippedSource[];
+}): RegradeReport => {
+  const reportEntries = params.reportEvaluation.entries;
+  const actionableEntries = reportEntries.filter(
+    (entry) => entry.outcome === 'rewrite' || entry.outcome === 'needs-review'
+  );
+  const reportSkippedByReason = skippedByReason(
+    params.reportEvaluation.skipped
+  );
+  const report: RegradeReport = withScannedPaths(
+    {
+      entries:
+        params.entrySelection === 'all' ? reportEntries : actionableEntries,
+      matched: actionableEntries.length,
+      review: reportEntries.filter((entry) => entry.outcome === 'needs-review')
+        .length,
+      rewritten: reportEntries.filter((entry) => entry.outcome === 'rewrite')
+        .length,
+      root: params.collectedRoot,
+      run:
+        params.applySummary === undefined
+          ? params.reportEvaluation.run
+          : vocabularyRunWithAppliedOccurrences(
+              params.reportEvaluation.run,
+              params.dryRunEvaluation.run,
+              params.applySummary
+            ),
+      scan: buildRegradeScanSummary({
+        matchedPaths: actionableEntries.map((entry) => entry.path),
+        occurrencePaths: params.reportEvaluation.occurrences.map(
+          (occurrence) => occurrence.path
+        ),
+        scanned: params.reportEvaluation.scanned,
+        skipped: params.reportEvaluation.skipped.length,
+        skippedByReason: reportSkippedByReason,
+      }),
+      scanned: params.reportEvaluation.scanned,
+      selectedClassIds: [
+        params.plan.id ?? `vocabulary:${params.plan.from}->${params.plan.to}`,
+      ],
+      skipped: params.reportEvaluation.skipped.length,
+      skipsByReason: reportSkippedByReason,
+      unknownClassIds: [],
+    },
+    params.files
+      .filter((file) => includedByScope(file.path, params.effectivePlan.scope))
+      .map((file) => file.path)
+  );
+  return params.applySummary === undefined
+    ? report
+    : withApplySummary(report, params.applySummary);
+};
+
+/**
+ * In-memory vocabulary evaluation ready for freshness-checked apply.
+ *
+ * @example
+ * ```ts
+ * const prepared = prepareVocabularyRegradeRun({ identity, plan, root });
+ * if (prepared.isOk() && prepared.value !== null) {
+ *   console.log(prepared.value.report.run?.gate.status);
+ * }
+ * ```
+ */
+export interface PreparedVocabularyRegradeRun {
+  readonly identity: PreparedRegradeRunIdentity;
+  readonly report: RegradeReport;
+  readonly sourceStateHash: string;
+}
+
+interface PreparedVocabularyRegradeRunState {
+  readonly dryRunEvaluation: VocabularyEvaluation;
+  readonly identity: PreparedRegradeRunIdentity;
+  readonly inputs: VocabularyRunInputs;
+  readonly params: PrepareVocabularyRegradeRunParams;
+  readonly sourceStateHash: string;
+}
+
+const preparedVocabularyRunStates = new WeakMap<
+  PreparedVocabularyRegradeRun,
+  PreparedVocabularyRegradeRunState
+>();
+
+const vocabularySourceStateHash = (files: readonly SourceFile[]): string =>
+  createHash('sha256')
+    .update(
+      JSON.stringify({
+        sources: files
+          .map((file) => ({ bytes: file.sourceBytes, path: file.path }))
+          .toSorted((left, right) => {
+            if (left.path < right.path) {
+              return -1;
+            }
+            if (left.path > right.path) {
+              return 1;
+            }
+            return 0;
+          }),
+      })
+    )
+    .digest('hex');
+
+const unreadableVocabularyPaths = (
+  skipped: readonly SkippedSource[]
+): readonly string[] =>
+  skipped
+    .filter(
+      (entry) =>
+        entry.reason === 'unreadable-file' ||
+        entry.reason === 'unreadable-directory'
+    )
+    .map((entry) => entry.path);
+
+const validateVocabularyPreparedIdentity = (
+  expected: PreparedRegradeRunIdentity,
+  actual: PreparedRegradeRunIdentity
+): Result<void, ValidationError> => {
+  for (const field of [
+    'planContentHash',
+    'policyHash',
+    'scopeHash',
+    'lockStateHash',
+    'toolVersion',
+  ] as const) {
+    if (expected[field] !== actual[field]) {
+      return Result.err(
+        new ValidationError(
+          `Prepared vocabulary Regrade identity field \`${field}\` is stale.`,
+          {
+            context: {
+              actual: actual[field],
+              expected: expected[field],
+              field,
+            },
+          }
+        )
+      );
+    }
+  }
+  return Result.ok();
+};
+
+/**
+ * Classify a vocabulary Regrade run once and retain it for checked apply.
+ *
+ * @example
+ * ```ts
+ * const prepared = prepareVocabularyRegradeRun({ identity, plan, root });
+ * if (prepared.isErr()) throw prepared.error;
+ * ```
+ */
+export const prepareVocabularyRegradeRun = (
+  params: PrepareVocabularyRegradeRunParams & {
+    readonly identity: PreparedRegradeRunIdentity;
+  }
+): Result<PreparedVocabularyRegradeRun | null, ValidationError> => {
+  const preparedParams = snapshotPrepareVocabularyRegradeRunParams(params);
+  const planValidation = validateVocabularyPlan(preparedParams.plan);
+  if (planValidation.isErr()) {
+    return planValidation;
+  }
+  const inventoryValidation = validatePreserveInventory(
+    preparedParams.preserveInventory
+  );
+  if (inventoryValidation.isErr()) {
+    return inventoryValidation;
+  }
+  const inputs = collectVocabularyRunInputs(preparedParams);
+  if (inputs === null) {
+    return Result.ok(null);
+  }
+  const unreadable = unreadableVocabularyPaths(inputs.skipped);
+  if (unreadable.length > 0) {
+    return Result.err(
+      new ValidationError(
+        'Prepared vocabulary Regrade sources must all be readable.',
+        { context: { paths: unreadable } }
+      )
+    );
+  }
+  const dryRunEvaluation = buildRunVocabularyEvaluation({
+    apply: false,
+    effectivePlan: inputs.effectivePlan,
+    files: inputs.files,
+    plan: preparedParams.plan,
+    preserveInventory: preparedParams.preserveInventory,
+    root: preparedParams.root,
+    skipped: inputs.skipped,
+    sourceKindForPath: preparedParams.sourceKindForPath,
+  });
+  const report = vocabularyReportFromEvaluation({
+    collectedRoot: inputs.collectedRoot,
+    dryRunEvaluation,
+    effectivePlan: inputs.effectivePlan,
+    entrySelection: preparedParams.includeEntries ?? 'actionable',
+    files: inputs.files,
+    plan: preparedParams.plan,
+    reportEvaluation: dryRunEvaluation,
+    skipped: inputs.skipped,
+  });
+  const prepared: PreparedVocabularyRegradeRun = {
+    identity: { ...params.identity },
+    report: cloneVocabularyReport(report),
+    sourceStateHash: vocabularySourceStateHash(inputs.files),
+  };
+  preparedVocabularyRunStates.set(prepared, {
+    dryRunEvaluation,
+    identity: { ...params.identity },
+    inputs,
+    params: preparedParams,
+    sourceStateHash: prepared.sourceStateHash,
+  });
+  return Result.ok(prepared);
+};
+
+/**
+ * Apply an in-memory vocabulary evaluation after identity and source checks.
+ *
+ * @example
+ * ```ts
+ * const applied = applyPreparedVocabularyRegradeRun(prepared, identity);
+ * if (applied.isErr()) throw applied.error;
+ * ```
+ */
+export const applyPreparedVocabularyRegradeRun = (
+  prepared: PreparedVocabularyRegradeRun,
+  identity: PreparedRegradeRunIdentity
+): Result<RegradeReport, InternalError | ValidationError> => {
+  const state = preparedVocabularyRunStates.get(prepared);
+  if (state === undefined) {
+    return Result.err(
+      new ValidationError(
+        'Prepared vocabulary Regrade run is not the original in-memory evaluation.'
+      )
+    );
+  }
+  const identityValidation = validateVocabularyPreparedIdentity(
+    state.identity,
+    identity
+  );
+  if (identityValidation.isErr()) {
+    return identityValidation;
+  }
+  const current = collectVocabularyRunInputs(state.params);
+  if (current === null) {
+    return Result.err(
+      new ValidationError(
+        'Prepared vocabulary Regrade root is no longer readable.'
+      )
+    );
+  }
+  const unreadable = unreadableVocabularyPaths(current.skipped);
+  if (unreadable.length > 0) {
+    return Result.err(
+      new ValidationError(
+        'Prepared vocabulary Regrade sources are no longer readable.',
+        { context: { paths: unreadable } }
+      )
+    );
+  }
+  const currentSourceStateHash = vocabularySourceStateHash(current.files);
+  if (currentSourceStateHash !== state.sourceStateHash) {
+    return Result.err(
+      new ValidationError(
+        'Prepared vocabulary Regrade source state is stale.',
+        {
+          context: {
+            actual: currentSourceStateHash,
+            expected: state.sourceStateHash,
+          },
+        }
+      )
+    );
+  }
+  const applyResult = applyVocabularyEvaluation(
+    state.inputs.files,
+    state.dryRunEvaluation
+  );
+  if (applyResult.isErr()) {
+    return applyResult;
+  }
+  const appliedFiles = state.inputs.files.map((file) => ({
+    ...file,
+    source: readFileSync(file.absolutePath, 'utf8'),
+  }));
+  const postApplyEvaluation = buildRunVocabularyEvaluation({
+    apply: true,
+    effectivePlan: state.inputs.effectivePlan,
+    files: appliedFiles,
+    plan: state.params.plan,
+    preserveInventory: state.params.preserveInventory,
+    root: state.params.root,
+    skipped: state.inputs.skipped,
+    sourceKindForPath: state.params.sourceKindForPath,
+  });
+  return Result.ok(
+    vocabularyReportFromEvaluation({
+      applySummary: applyResult.value,
+      collectedRoot: state.inputs.collectedRoot,
+      dryRunEvaluation: state.dryRunEvaluation,
+      effectivePlan: state.inputs.effectivePlan,
+      entrySelection: state.params.includeEntries ?? 'actionable',
+      files: appliedFiles,
+      plan: state.params.plan,
+      reportEvaluation: postApplyEvaluation,
+      skipped: state.inputs.skipped,
+    })
+  );
+};
+
+export const runVocabularyRegrade = (params: {
+  readonly apply?: boolean;
+  readonly includeEntries?: 'actionable' | 'all';
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory?: readonly VocabularyPreserveInventoryEntry[];
+  readonly root: string;
+  readonly sourceFilter?: (path: string) => boolean;
+  readonly sourceKindForPath?: (path: string) => VocabularySourceKind;
+}): Result<RegradeReport | null, InternalError | ValidationError> => {
+  const planValidation = validateVocabularyPlan(params.plan);
+  if (planValidation.isErr()) {
+    return planValidation;
+  }
+  const inventoryValidation = validatePreserveInventory(
+    params.preserveInventory
+  );
+  if (inventoryValidation.isErr()) {
+    return inventoryValidation;
+  }
+
+  const inputs = collectVocabularyRunInputs(params);
+  if (inputs === null) {
+    return Result.ok(null);
+  }
+  const { collectedRoot, effectivePlan, files, skipped } = inputs;
 
   const dryRunEffectiveEvaluation = buildRunVocabularyEvaluation({
     apply: false,
@@ -1951,6 +2468,7 @@ export const runVocabularyRegrade = (params: {
     preserveInventory: params.preserveInventory,
     root: params.root,
     skipped,
+    sourceKindForPath: params.sourceKindForPath,
   });
   let reportEvaluation = dryRunEffectiveEvaluation;
   let applySummary: RegradeApplySummary | undefined;
@@ -1976,51 +2494,22 @@ export const runVocabularyRegrade = (params: {
       preserveInventory: params.preserveInventory,
       root: params.root,
       skipped,
+      sourceKindForPath: params.sourceKindForPath,
     });
   }
 
-  const entrySelection = params.includeEntries ?? 'actionable';
-  const reportEntries = reportEvaluation.entries;
-  const actionableEntries = reportEntries.filter(
-    (entry) => entry.outcome === 'rewrite' || entry.outcome === 'needs-review'
-  );
-  const reportSkippedByReason = skippedByReason(reportEvaluation.skipped);
-  const report: RegradeReport = {
-    entries: entrySelection === 'all' ? reportEntries : actionableEntries,
-    matched: actionableEntries.length,
-    review: reportEntries.filter((entry) => entry.outcome === 'needs-review')
-      .length,
-    rewritten: reportEntries.filter((entry) => entry.outcome === 'rewrite')
-      .length,
-    root: collected.root,
-    run:
-      applySummary === undefined
-        ? reportEvaluation.run
-        : vocabularyRunWithAppliedOccurrences(
-            reportEvaluation.run,
-            dryRunEffectiveEvaluation.run,
-            applySummary
-          ),
-    scan: buildRegradeScanSummary({
-      matchedPaths: actionableEntries.map((entry) => entry.path),
-      occurrencePaths: reportEvaluation.occurrences.map(
-        (occurrence) => occurrence.path
-      ),
-      scanned: reportEvaluation.scanned,
-      skipped: reportEvaluation.skipped.length,
-      skippedByReason: reportSkippedByReason,
-    }),
-    scanned: reportEvaluation.scanned,
-    selectedClassIds: [
-      params.plan.id ?? `vocabulary:${params.plan.from}->${params.plan.to}`,
-    ],
-    skipped: reportEvaluation.skipped.length,
-    skipsByReason: reportSkippedByReason,
-    unknownClassIds: [],
-  };
-
   return Result.ok(
-    applySummary === undefined ? report : withApplySummary(report, applySummary)
+    vocabularyReportFromEvaluation({
+      ...(applySummary === undefined ? {} : { applySummary }),
+      collectedRoot,
+      dryRunEvaluation: dryRunEffectiveEvaluation,
+      effectivePlan,
+      entrySelection: params.includeEntries ?? 'actionable',
+      files,
+      plan: params.plan,
+      reportEvaluation,
+      skipped,
+    })
   );
 };
 
@@ -2170,6 +2659,10 @@ export const vocabularyRegradeRunOutput = z.object({
             scopeTier: z
               .enum(['in-scope', 'policy-classified'])
               .describe('Three-tier scope classification for this occurrence'),
+            sourceKind: z
+              .enum(['source-comment', 'tsdoc'])
+              .optional()
+              .describe('Exact source-comment construct for comment inventory'),
             start: z.number().describe('Source start offset'),
             verdict: z
               .enum(['applied', 'deferred', 'modified', 'skipped'])