@ontrails/trails 1.0.0-beta.42 → 1.0.0-beta.43

package/src/regrade/plan-artifact.ts

@@ -10,6 +10,7 @@ import type {
   RegradeReportEntry,
   VocabularyRegradePlan,
 } from '@ontrails/regrade';
+import { getGovernedVocabularyTransition } from '@ontrails/warden';
 import { createHash } from 'node:crypto';
 import { join, normalize, relative } from 'node:path';
 import { z } from 'zod';
@@ -18,6 +19,108 @@ export const REGRADE_PLAN_SCHEMA_VERSION = 1;
 
 const regradePlanProvenanceValueSchema = z.enum(['authored', 'derived']);
 
+const regradePlanDerivationSchema = z
+  .object({
+    fileRenames: z.array(
+      z
+        .object({
+          evidence: z.array(z.string()),
+          from: z.string(),
+          provenance: z.literal('derived'),
+          status: z.literal('pending'),
+          to: z.string(),
+        })
+        .strict()
+    ),
+    forms: z.array(
+      z
+        .object({
+          from: z.string(),
+          kind: z.enum(['review', 'safe-rewrite']),
+          provenance: regradePlanProvenanceValueSchema,
+          reason: z.string(),
+          source: z.enum([
+            'default-morphology',
+            'plan-defer',
+            'plan-override',
+            'seed',
+          ]),
+          to: z.string().optional(),
+        })
+        .strict()
+    ),
+    namespaces: z.array(
+      z
+        .object({
+          inScope: z.number().int().nonnegative(),
+          namespace: z.string(),
+          policyClassified: z.number().int().nonnegative(),
+          provenance: z.literal('derived'),
+        })
+        .strict()
+    ),
+    preserves: z.array(
+      z
+        .object({
+          disposition: z.literal('preserve-current-live-api'),
+          evidence: z.array(z.string()),
+          pattern: z.string(),
+          provenance: z.literal('derived'),
+          reason: z.string().optional(),
+        })
+        .strict()
+    ),
+    referenceClosure: z
+      .object({
+        entries: z.array(
+          z
+            .object({
+              outcome: z.enum(['needs-review', 'rewrite']),
+              path: z.string(),
+              provenance: z.literal('derived'),
+              reason: z.string().optional(),
+            })
+            .strict()
+        ),
+        issue: z.string().optional(),
+        moves: z.array(
+          z
+            .object({
+              deferred: z.number().int().nonnegative(),
+              from: z.string(),
+              historical: z.number().int().nonnegative(),
+              preserved: z.number().int().nonnegative(),
+              provenance: z.literal('derived'),
+              rewritten: z.number().int().nonnegative(),
+              skipped: z.number().int().nonnegative(),
+              to: z.string(),
+            })
+            .strict()
+        ),
+      })
+      .strict(),
+    reviews: z.array(
+      z
+        .object({
+          evidence: z.array(
+            z
+              .object({
+                column: z.number().int().positive().optional(),
+                line: z.number().int().positive().optional(),
+                path: z.string(),
+              })
+              .strict()
+          ),
+          provenance: z.literal('derived'),
+          reason: z.string(),
+          status: z.literal('pending'),
+          value: z.string(),
+        })
+        .strict()
+    ),
+  })
+  .strict();
+
 const classRegradePlanScopeSchema = z
   .object({
     exclude: z
@@ -86,6 +189,7 @@ const regradeExpansionCandidateSchema = z.union([
       )
       .default([]),
     kind: z.enum(['file-rename', 'form', 'namespace', 'preserve']),
+    provenance: regradePlanProvenanceValueSchema.default('derived'),
     reason: z.string().optional(),
     status: z.enum(['pending', 'rejected']).default('pending'),
     suggestedClassification: z.string(),
@@ -107,6 +211,7 @@ const regradeExpansionCandidateSchema = z.union([
         },
       ],
       kind: 'file-rename' as const,
+      provenance: 'derived' as const,
       ...(candidate.detail === undefined ? {} : { reason: candidate.detail }),
       status: candidate.status,
       suggestedClassification: 'legacy-path-candidate',
@@ -116,6 +221,7 @@ const regradeExpansionCandidateSchema = z.union([
 
 export const regradePlanArtifactSchema = z
   .object({
+    derivation: regradePlanDerivationSchema.optional(),
     expansion: z
       .object({
         candidates: z.array(regradeExpansionCandidateSchema).default([]),
@@ -148,6 +254,7 @@ export interface RegradePlanExpansion {
       readonly path: string;
     }[];
     readonly kind: 'file-rename' | 'form' | 'namespace' | 'preserve';
+    readonly provenance: 'authored' | 'derived';
     readonly reason?: string | undefined;
     readonly status: 'pending' | 'rejected';
     readonly suggestedClassification: string;
@@ -156,6 +263,7 @@ export interface RegradePlanExpansion {
 }
 
 export interface RegradePlanArtifact {
+  readonly derivation?: RegradePlanDerivation | undefined;
   readonly expansion?: RegradePlanExpansion | undefined;
   readonly kind: 'regrade-plan';
   readonly path: string;
@@ -168,6 +276,10 @@ export interface RegradePlanArtifact {
   readonly transitionId?: string | undefined;
 }
 
+export type RegradePlanDerivation = z.output<
+  typeof regradePlanDerivationSchema
+>;
+
 /** A plan artifact narrowed to a vocabulary plan body. */
 export type VocabularyRegradePlanArtifact = RegradePlanArtifact & {
   readonly plan: VocabularyRegradePlan;
@@ -185,7 +297,15 @@ const regradePlanSlug = (plan: Pick<VocabularyRegradePlan, 'from' | 'to'>) =>
 export const regradePlanSlugForBody = (plan: RegradePlanBody): string =>
   plan.kind === 'class'
     ? regradeSlugText(plan.name ?? plan.classIds.join('-'))
-    : regradePlanSlug(plan);
+    : (() => {
+        const transition =
+          plan.id === undefined
+            ? undefined
+            : getGovernedVocabularyTransition(plan.id);
+        return transition?.target.kind === 'classified'
+          ? regradeSlugText(transition.id)
+          : regradePlanSlug(plan);
+      })();
 
 const normalizeRelativePath = (path: string): string =>
   normalize(path).replaceAll('\\', '/');
@@ -245,9 +365,51 @@ const canonicalizeJsonValue = (value: unknown): unknown => {
 export const canonicalJsonStringify = (value: unknown): string =>
   JSON.stringify(canonicalizeJsonValue(value));
 
-const regradeSourceHashFacts = (report: RegradeReport): unknown => ({
+export const isGeneratedRegradeArtifactPath = (path: string): boolean =>
+  /(?:^|\/)\.trails\/regrade\/.+\.json$/u.test(path);
+
+const sourceHashLedgerFacts = (
+  report: RegradeReport,
+  policyMode: 'current' | 'legacy'
+): unknown => {
+  const ledger = report.run?.ledger;
+  if (ledger === undefined) {
+    return undefined;
+  }
+  // The active plan is written after its source hash and must not stale itself.
+  const occurrences = ledger.occurrences.filter(
+    (occurrence) =>
+      occurrence.scopeTier !== 'policy-classified' ||
+      (policyMode === 'current' &&
+        !isGeneratedRegradeArtifactPath(occurrence.path))
+  );
+  const forms = new Set(occurrences.map((occurrence) => occurrence.form));
+  return {
+    cycle: ledger.cycle,
+    forms: Object.fromEntries(
+      Object.entries(ledger.forms).filter(([form]) => forms.has(form))
+    ),
+    occurrences,
+  };
+};
+
+const regradeSourceHashFacts = (
+  report: RegradeReport,
+  policyMode: 'current' | 'legacy' = 'current',
+  fileEvidenceMode: 'current' | 'legacy' = 'current'
+): unknown => ({
   entries: sourceHashEntryFacts(report.entries),
-  ledger: report.run?.ledger,
+  fileRenames: report.run?.report.fileRenames?.map(
+    ({ deferred, from, historical, preserved, rewritten, skipped, to }) => ({
+      deferred,
+      from,
+      ...(fileEvidenceMode === 'current' ? { historical, preserved } : {}),
+      rewritten,
+      ...(fileEvidenceMode === 'current' ? { skipped } : {}),
+      to,
+    })
+  ),
+  ledger: sourceHashLedgerFacts(report, policyMode),
   selectedClassIds: report.selectedClassIds,
 });
 
@@ -259,22 +421,39 @@ export const regradeSourceHash = (report: RegradeReport): string =>
     canonicalJsonStringify(regradeSourceHashFacts(report))
   );
 
+/** Match only the complete current source-evidence shape used by active plans. */
+export const currentRegradeSourceHashMatches = (
+  stampedHash: string,
+  report: RegradeReport
+): boolean => stampedHash === regradeSourceHash(report);
+
 export const legacyRegradeSourceHash = (report: RegradeReport): string =>
   hashSerializedSourceFacts(JSON.stringify(regradeSourceHashFacts(report)));
 
-/** Match source evidence written before canonical JSON hashing. */
-export const regradeSourceHashMatches = (
-  stampedHash: string,
+export const regradeSourceHashes = (
   report: RegradeReport
-): boolean =>
-  stampedHash === regradeSourceHash(report) ||
-  stampedHash === legacyRegradeSourceHash(report);
+): readonly string[] => {
+  const facts = [
+    regradeSourceHashFacts(report),
+    regradeSourceHashFacts(report, 'current', 'legacy'),
+    regradeSourceHashFacts(report, 'legacy'),
+    regradeSourceHashFacts(report, 'legacy', 'legacy'),
+  ];
+  return [
+    ...new Set(
+      facts.flatMap((value) => [
+        hashSerializedSourceFacts(canonicalJsonStringify(value)),
+        hashSerializedSourceFacts(JSON.stringify(value)),
+      ])
+    ),
+  ];
+};
 
-export const regradeSourceHashes = (
+/** Match source evidence written by any supported historical hash shape. */
+export const regradeSourceHashMatches = (
+  stampedHash: string,
   report: RegradeReport
-): readonly string[] => [
-  ...new Set([regradeSourceHash(report), legacyRegradeSourceHash(report)]),
-];
+): boolean => regradeSourceHashes(report).includes(stampedHash);
 
 /**
  * Canonical content hash of a resolved Regrade plan body — the authored

package/src/regrade/plan-derivation.ts

@@ -0,0 +1,301 @@
+import {
+  createAstIdentifierRenameClass,
+  deriveFileRenameCandidates,
+  deriveVocabularyFormProposals,
+  runFileRenameRegrade,
+  runRegrade,
+} from '@ontrails/regrade';
+import type {
+  RegradeReport,
+  VocabularyPreserveInventoryEntry,
+  VocabularyRegradePlan,
+} from '@ontrails/regrade';
+
+import { isGeneratedRegradeArtifactPath } from './plan-artifact.js';
+import type {
+  RegradePlanArtifact,
+  RegradePlanDerivation,
+} from './plan-artifact.js';
+
+const provenanceForForm = (
+  source: RegradePlanDerivation['forms'][number]['source'],
+  fields: RegradePlanArtifact['provenance']['fields']
+): 'authored' | 'derived' => {
+  if (source === 'seed') {
+    return 'authored';
+  }
+  if (source === 'plan-override') {
+    return fields['overrides'] ?? 'derived';
+  }
+  if (source === 'plan-defer') {
+    return fields['deferForms'] ?? 'derived';
+  }
+  return 'derived';
+};
+
+const namespaceCensus = (
+  report: RegradeReport
+): RegradePlanDerivation['namespaces'] => {
+  const namespaces = new Map<
+    string,
+    { inScope: number; policyClassified: number }
+  >();
+  for (const occurrence of report.run?.ledger.occurrences ?? []) {
+    if (isGeneratedRegradeArtifactPath(occurrence.path)) {
+      continue;
+    }
+    const namespace = occurrence.path.split('/')[0] ?? occurrence.path;
+    const counts = namespaces.get(namespace) ?? {
+      inScope: 0,
+      policyClassified: 0,
+    };
+    if (occurrence.scopeTier === 'policy-classified') {
+      counts.policyClassified += 1;
+    } else {
+      counts.inScope += 1;
+    }
+    namespaces.set(namespace, counts);
+  }
+  return [...namespaces.entries()]
+    .map(([namespace, counts]) => ({
+      ...counts,
+      namespace,
+      provenance: 'derived' as const,
+    }))
+    .toSorted((left, right) => left.namespace.localeCompare(right.namespace));
+};
+
+const observedReviews = (
+  report: RegradeReport
+): RegradePlanDerivation['reviews'] => {
+  const reviews = new Map<string, RegradePlanDerivation['reviews'][number]>();
+  for (const occurrence of report.run?.ledger.occurrences ?? []) {
+    if (
+      isGeneratedRegradeArtifactPath(occurrence.path) ||
+      (occurrence.verdict !== 'deferred' &&
+        occurrence.disposition !== 'code-context-out-of-engine' &&
+        occurrence.disposition !== 'in-family-unresolved')
+    ) {
+      continue;
+    }
+    const key = `${occurrence.form}\0${occurrence.reason}`;
+    const current = reviews.get(key);
+    const evidence = {
+      column: occurrence.column,
+      line: occurrence.line,
+      path: occurrence.path,
+    };
+    reviews.set(key, {
+      evidence:
+        current === undefined ? [evidence] : [...current.evidence, evidence],
+      provenance: 'derived',
+      reason: occurrence.reason,
+      status: 'pending',
+      value: occurrence.form,
+    });
+  }
+  return [...reviews.values()]
+    .map((review) => ({
+      ...review,
+      evidence: review.evidence.toSorted((left, right) =>
+        left.path === right.path
+          ? (left.line ?? 0) - (right.line ?? 0)
+          : left.path.localeCompare(right.path)
+      ),
+    }))
+    .toSorted((left, right) => left.value.localeCompare(right.value));
+};
+
+const identifierReviews = (params: {
+  readonly plan: VocabularyRegradePlan;
+  readonly rootDir: string;
+}): RegradePlanDerivation['reviews'] => {
+  const { scope } = params.plan;
+  const sourceForms = [
+    ...new Map(
+      deriveVocabularyFormProposals(params.plan).map((form) => [
+        form.from,
+        form,
+      ])
+    ).values(),
+  ];
+  const collection = {
+    ...(scope?.exclude === undefined ? {} : { exclude: scope.exclude }),
+    extensions: scope?.extensions ?? ['.js', '.jsx', '.mjs', '.ts', '.tsx'],
+    ...(scope?.include === undefined ? {} : { include: scope.include }),
+  };
+  const entries: RegradeReport['entries'][number][] = [];
+  for (const form of sourceForms) {
+    const report = runRegrade({
+      classes: [
+        createAstIdentifierRenameClass({
+          from: form.from,
+          id: `derived-plan-identifiers:${form.from}->${form.to ?? params.plan.to}`,
+          match: 'identifier-segment',
+          reviewAllMatches: true,
+          to: form.to ?? params.plan.to,
+        }),
+      ],
+      collection,
+      root: params.rootDir,
+    });
+    if (report.isErr()) {
+      return [
+        {
+          evidence: [],
+          provenance: 'derived',
+          reason: `identifier-review-scan-failed: ${report.error.message}`,
+          status: 'pending',
+          value: form.from,
+        },
+      ];
+    }
+    entries.push(...(report.value?.entries ?? []));
+  }
+  return entries
+    .flatMap((entry) =>
+      (entry.reviewDetails ?? []).flatMap((detail) =>
+        detail.symbol === undefined
+          ? []
+          : [
+              {
+                evidence: [
+                  {
+                    ...(detail.span?.column === undefined
+                      ? {}
+                      : { column: detail.span.column }),
+                    ...(detail.span?.line === undefined
+                      ? {}
+                      : { line: detail.span.line }),
+                    path: entry.path,
+                  },
+                ],
+                provenance: 'derived' as const,
+                reason: detail.reason,
+                status: 'pending' as const,
+                value: detail.symbol,
+              },
+            ]
+      )
+    )
+    .toSorted((left, right) => left.value.localeCompare(right.value));
+};
+
+const mergeReviews = (
+  ...groups: readonly RegradePlanDerivation['reviews'][]
+): RegradePlanDerivation['reviews'] => {
+  const merged = new Map<string, RegradePlanDerivation['reviews'][number]>();
+  for (const review of groups.flat()) {
+    const key = `${review.value}\0${review.reason}`;
+    const current = merged.get(key);
+    merged.set(key, {
+      ...review,
+      evidence: [...(current?.evidence ?? []), ...review.evidence]
+        .filter(
+          (entry, index, evidence) =>
+            evidence.findIndex(
+              (candidate) =>
+                candidate.path === entry.path &&
+                candidate.line === entry.line &&
+                candidate.column === entry.column
+            ) === index
+        )
+        .toSorted((left, right) => left.path.localeCompare(right.path)),
+    });
+  }
+  return [...merged.values()].toSorted((left, right) =>
+    left.value === right.value
+      ? left.reason.localeCompare(right.reason)
+      : left.value.localeCompare(right.value)
+  );
+};
+
+const referenceClosure = (params: {
+  readonly candidates: ReturnType<typeof deriveFileRenameCandidates>;
+  readonly plan: VocabularyRegradePlan;
+  readonly rootDir: string;
+}): RegradePlanDerivation['referenceClosure'] => {
+  if (params.candidates.length === 0) {
+    return { entries: [], moves: [] };
+  }
+  const result = runFileRenameRegrade({
+    excludeGeneratedArtifacts: true,
+    renames: params.candidates,
+    root: params.rootDir,
+    ...(params.plan.scope === undefined ? {} : { scope: params.plan.scope }),
+  });
+  if (result.isErr()) {
+    return { entries: [], issue: result.error.message, moves: [] };
+  }
+  return {
+    entries: result.value.report.entries
+      .filter(
+        (
+          entry
+        ): entry is typeof entry & {
+          readonly outcome: 'needs-review' | 'rewrite';
+        } => entry.outcome === 'needs-review' || entry.outcome === 'rewrite'
+      )
+      .map((entry) => ({
+        outcome: entry.outcome,
+        path: entry.path,
+        provenance: 'derived' as const,
+        ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+      }))
+      .toSorted((left, right) => left.path.localeCompare(right.path)),
+    moves: result.value.evidence.map(
+      ({ deferred, from, historical, preserved, rewritten, skipped, to }) => ({
+        deferred,
+        from,
+        historical,
+        preserved,
+        provenance: 'derived' as const,
+        rewritten,
+        skipped,
+        to,
+      })
+    ),
+  };
+};
+
+export const deriveRegradePlanDerivation = (params: {
+  readonly plan: VocabularyRegradePlan;
+  readonly preserveInventory: readonly VocabularyPreserveInventoryEntry[];
+  readonly provenance: RegradePlanArtifact['provenance'];
+  readonly report: RegradeReport;
+  readonly rootDir: string;
+}): RegradePlanDerivation => {
+  const candidates = deriveFileRenameCandidates({
+    plan: params.plan,
+    root: params.rootDir,
+  });
+  return {
+    fileRenames: candidates.map((candidate) => ({
+      ...candidate,
+      evidence: [...candidate.evidence],
+      provenance: 'derived' as const,
+      status: 'pending' as const,
+    })),
+    forms: deriveVocabularyFormProposals(params.plan).map((form) => ({
+      ...form,
+      provenance: provenanceForForm(form.source, params.provenance.fields),
+    })),
+    namespaces: namespaceCensus(params.report),
+    preserves: params.preserveInventory.map((entry) => ({
+      disposition: 'preserve-current-live-api' as const,
+      evidence: [...entry.evidence],
+      pattern: entry.pattern,
+      provenance: 'derived' as const,
+      ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+    })),
+    referenceClosure: referenceClosure({
+      candidates,
+      plan: params.plan,
+      rootDir: params.rootDir,
+    }),
+    reviews: mergeReviews(
+      observedReviews(params.report),
+      identifierReviews({ plan: params.plan, rootDir: params.rootDir })
+    ),
+  };
+};

package/src/regrade/source-transaction.ts

@@ -0,0 +1,75 @@
+import { InternalError, Result, deriveSafePath } from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+import type { RegradeReport } from '@ontrails/regrade';
+import { readFileSync, writeFileSync } from 'node:fs';
+
+export interface RegradeSourceSnapshot {
+  readonly absolutePath: string;
+  readonly source: Uint8Array;
+}
+
+export const snapshotRegradeSources = (params: {
+  readonly reports: readonly (RegradeReport | null)[];
+  readonly rootDir: string;
+}): TrailsResult<readonly RegradeSourceSnapshot[], Error> => {
+  const paths = new Set(
+    params.reports.flatMap(
+      (report) =>
+        report?.entries
+          .filter(
+            (entry) =>
+              entry.outcome === 'rewrite' || entry.outcome === 'needs-review'
+          )
+          .map((entry) => entry.path) ?? []
+    )
+  );
+  const snapshots: RegradeSourceSnapshot[] = [];
+  try {
+    for (const path of paths) {
+      const absolutePath = deriveSafePath(params.rootDir, path);
+      if (absolutePath.isErr()) {
+        return absolutePath;
+      }
+      snapshots.push({
+        absolutePath: absolutePath.value,
+        source: readFileSync(absolutePath.value),
+      });
+    }
+  } catch (error) {
+    return Result.err(
+      new InternalError(
+        'Failed to snapshot Regrade sources before apply.',
+        error instanceof Error ? { cause: error } : {}
+      )
+    );
+  }
+  return Result.ok(snapshots);
+};
+
+const rollbackRegradeSources = (
+  snapshots: readonly RegradeSourceSnapshot[]
+): Error | null => {
+  try {
+    for (const snapshot of snapshots) {
+      writeFileSync(snapshot.absolutePath, snapshot.source);
+    }
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error : new Error(String(error));
+  }
+};
+
+export const regradeApplyErrorAfterRollback = (
+  error: Error,
+  snapshots: readonly RegradeSourceSnapshot[]
+): TrailsResult<never, Error> => {
+  const rollbackError = rollbackRegradeSources(snapshots);
+  return rollbackError === null
+    ? Result.err(error)
+    : Result.err(
+        new InternalError('Regrade apply failed and source rollback failed.', {
+          cause: error,
+          context: { rollbackError: rollbackError.message },
+        })
+      );
+};