@ontrails/trails 1.0.0-beta.30 → 1.0.0-beta.39

package/src/regrade/history.ts

@@ -0,0 +1,320 @@
+/**
+ * Consolidated, append-only Regrade transition history. One file per
+ * transition at `.trails/regrade/history/<transition>.json`; each apply
+ * appends a run entry stamped with the plan content hash and the lock hash
+ * observed at that run.
+ */
+
+import { InternalError, Result, ValidationError } from '@ontrails/core';
+import type { Result as TrailsResult } from '@ontrails/core';
+import { regradeReportOutput } from '@ontrails/regrade';
+import type { RegradeReport } from '@ontrails/regrade';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { z } from 'zod';
+
+import {
+  regradePlanArtifactSchema,
+  regradePlanContentHash,
+  regradePlanDirectory,
+  regradePlanSlugForBody,
+  regradeSourceHash,
+  rootRelativePath,
+} from './plan-artifact.js';
+import type { RegradePlanArtifact, RegradePlanBody } from './plan-artifact.js';
+
+/**
+ * Consolidated history schema version. Version 1 was the retired
+ * one-file-per-run shape whose filename carried the lock hash.
+ */
+export const REGRADE_HISTORY_SCHEMA_VERSION = 2;
+
+const regradeHistoryRunSchema = z
+  .object({
+    lockHashAtRun: z
+      .string()
+      .min(1)
+      .describe('Regrade source hash observed when this run applied'),
+    plan: regradePlanArtifactSchema.describe(
+      'Plan artifact consumed by this run'
+    ),
+    planContentHash: z
+      .string()
+      .min(1)
+      .describe('Canonical content hash of the resolved plan body'),
+    report: regradeReportOutput.describe('Applied report recorded by the run'),
+  })
+  .strict();
+
+const regradeHistoryArtifactSchema = z
+  .object({
+    id: z.string().min(1).describe('Stable transition identity'),
+    kind: z.literal('regrade-history'),
+    path: z.string().describe('Root-relative consolidated history path'),
+    runs: z.array(regradeHistoryRunSchema).min(1),
+    schemaVersion: z.literal(REGRADE_HISTORY_SCHEMA_VERSION),
+  })
+  .strict();
+
+interface RegradeHistoryRun {
+  readonly lockHashAtRun: string;
+  readonly plan: RegradePlanArtifact;
+  readonly planContentHash: string;
+  readonly report: RegradeReport;
+}
+
+export interface RegradeHistoryArtifact {
+  readonly id: string;
+  readonly kind: 'regrade-history';
+  readonly path: string;
+  readonly runs: readonly RegradeHistoryRun[];
+  readonly schemaVersion: typeof REGRADE_HISTORY_SCHEMA_VERSION;
+}
+
+export interface RegradeHistorySummary {
+  readonly path: string;
+  readonly schemaVersion: number;
+  readonly status: 'applied' | 'replay';
+}
+
+export const regradeHistoryPathForPlan = (
+  rootDir: string,
+  plan: RegradePlanBody
+): string =>
+  join(
+    regradePlanDirectory(rootDir),
+    'history',
+    `${regradePlanSlugForBody(plan)}.json`
+  );
+
+export const readRegradeHistoryArtifact = (
+  path: string
+): TrailsResult<RegradeHistoryArtifact, InternalError | ValidationError> => {
+  if (!existsSync(path)) {
+    return Result.err(
+      new ValidationError(`Regrade history "${path}" not found.`)
+    );
+  }
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to read Regrade history artifact.', {
+        ...(error instanceof Error ? { cause: error } : {}),
+        context: { path },
+      })
+    );
+  }
+  const parsed = regradeHistoryArtifactSchema.safeParse(parsedJson);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError('Invalid Regrade history artifact.', {
+        context: { issues: parsed.error.issues, path },
+      })
+    );
+  }
+  return Result.ok(parsed.data as unknown as RegradeHistoryArtifact);
+};
+
+/**
+ * Deterministic transition identity minted at the first recorded run and
+ * preserved for the life of the consolidated history file.
+ */
+export const mintTransitionId = (
+  slug: string,
+  planContentHash: string,
+  lockHashAtRun: string
+): string =>
+  createHash('sha256')
+    .update(`${slug}\n${planContentHash}\n${lockHashAtRun}`)
+    .digest('hex')
+    .slice(0, 12);
+
+/**
+ * Append one applied run to the transition's consolidated history file. A
+ * run whose plan content hash and lock hash both equal the last recorded
+ * run's stamps is a replay: nothing is written and `status: 'replay'` is
+ * surfaced instead of a duplicate record.
+ */
+export const appendRegradeHistoryRun = (params: {
+  readonly artifact: RegradePlanArtifact;
+  readonly report: RegradeReport;
+  readonly rootDir: string;
+}): TrailsResult<RegradeHistorySummary, Error> => {
+  const absolutePath = regradeHistoryPathForPlan(
+    params.rootDir,
+    params.artifact.plan
+  );
+  const relativePath = rootRelativePath(params.rootDir, absolutePath);
+  const planContentHash = regradePlanContentHash(params.artifact.plan);
+  const lockHashAtRun = regradeSourceHash(params.report);
+  const entry: RegradeHistoryRun = {
+    lockHashAtRun,
+    plan: params.artifact,
+    planContentHash,
+    report: params.report,
+  };
+
+  let prior: RegradeHistoryArtifact | undefined;
+  if (existsSync(absolutePath)) {
+    const existing = readRegradeHistoryArtifact(absolutePath);
+    if (existing.isErr()) {
+      return existing;
+    }
+    prior = existing.value;
+    if (
+      params.artifact.transitionId !== undefined &&
+      params.artifact.transitionId !== prior.id
+    ) {
+      return Result.err(
+        new ValidationError(
+          'Regrade plan transition id mismatch — refusing to fork the consolidated history.',
+          {
+            context: {
+              history: prior.id,
+              path: relativePath,
+              plan: params.artifact.transitionId,
+            },
+          }
+        )
+      );
+    }
+    const lastRun = prior.runs.at(-1);
+    // A plan that carries the transition id (adjust round-trips, plan
+    // re-derivation) may evolve the plan identity on the same spine. A plan
+    // WITHOUT the id that disagrees with the recorded plan identity is a
+    // name collision, not a continuation — refuse instead of mixing runs
+    // from unrelated transitions into one history.
+    if (
+      params.artifact.transitionId === undefined &&
+      lastRun !== undefined &&
+      lastRun.plan.plan.id !== params.artifact.plan.id
+    ) {
+      return Result.err(
+        new ValidationError(
+          'Regrade history already records a different plan identity under this transition name. Use `regrade adjust <transition>` to continue it, or pick a different plan name.',
+          {
+            context: {
+              history: lastRun.plan.plan.id,
+              path: relativePath,
+              plan: params.artifact.plan.id,
+            },
+          }
+        )
+      );
+    }
+    if (
+      lastRun !== undefined &&
+      lastRun.planContentHash === planContentHash &&
+      lastRun.lockHashAtRun === lockHashAtRun
+    ) {
+      return Result.ok({
+        path: relativePath,
+        schemaVersion: REGRADE_HISTORY_SCHEMA_VERSION,
+        status: 'replay',
+      });
+    }
+  }
+
+  const artifact: RegradeHistoryArtifact = {
+    id:
+      prior === undefined
+        ? (params.artifact.transitionId ??
+          mintTransitionId(
+            regradePlanSlugForBody(params.artifact.plan),
+            planContentHash,
+            lockHashAtRun
+          ))
+        : prior.id,
+    kind: 'regrade-history',
+    path: relativePath,
+    runs: prior === undefined ? [entry] : [...prior.runs, entry],
+    schemaVersion: REGRADE_HISTORY_SCHEMA_VERSION,
+  };
+  const parsed = regradeHistoryArtifactSchema.safeParse(artifact);
+  if (!parsed.success) {
+    return Result.err(
+      new ValidationError('Invalid Regrade history artifact.', {
+        context: { issues: parsed.error.issues, path: relativePath },
+      })
+    );
+  }
+  try {
+    mkdirSync(dirname(absolutePath), { recursive: true });
+    writeFileSync(absolutePath, `${JSON.stringify(parsed.data, null, 2)}\n`);
+  } catch (error) {
+    return Result.err(
+      new InternalError('Failed to write Regrade history entry.', {
+        ...(error instanceof Error ? { cause: error } : {}),
+        context: { path: relativePath },
+      })
+    );
+  }
+  return Result.ok({
+    path: relativePath,
+    schemaVersion: REGRADE_HISTORY_SCHEMA_VERSION,
+    status: 'applied',
+  });
+};
+
+/**
+ * Verify every recorded run at its own stamped lock: recompute the plan
+ * content hash and lock hash from the recorded plan and report, then compare
+ * with the stamped values.
+ */
+export const verifyRegradeHistoryRuns = (
+  artifact: RegradeHistoryArtifact
+): TrailsResult<{ readonly runs: number }, ValidationError> => {
+  for (const [index, run] of artifact.runs.entries()) {
+    if (regradePlanContentHash(run.plan.plan) !== run.planContentHash) {
+      return Result.err(
+        new ValidationError('Regrade history run stamp mismatch.', {
+          context: {
+            field: 'planContentHash',
+            path: artifact.path,
+            run: index,
+          },
+        })
+      );
+    }
+    if (regradeSourceHash(run.report) !== run.lockHashAtRun) {
+      return Result.err(
+        new ValidationError('Regrade history run stamp mismatch.', {
+          context: { field: 'lockHashAtRun', path: artifact.path, run: index },
+        })
+      );
+    }
+  }
+  return Result.ok({ runs: artifact.runs.length });
+};
+
+const hasPathSeparator = (value: string): boolean =>
+  value.includes('/') || value.includes('\\');
+
+/**
+ * Resolve a transition name (with or without a `.json` suffix) to its
+ * consolidated history file. Path references are rejected — graduated
+ * history lookups are by transition name only.
+ */
+export const resolveRegradeHistoryPath = (
+  rootDir: string,
+  ref: string
+): TrailsResult<string, ValidationError> => {
+  if (hasPathSeparator(ref) || isAbsolute(ref)) {
+    return Result.err(
+      new ValidationError(
+        `Regrade history reference "${ref}" must be a transition name.`
+      )
+    );
+  }
+  const name = ref.endsWith('.json') ? ref.slice(0, -'.json'.length) : ref;
+  const path = join(regradePlanDirectory(rootDir), 'history', `${name}.json`);
+  if (!existsSync(path)) {
+    return Result.err(
+      new ValidationError(`No Regrade history for transition "${ref}" found.`)
+    );
+  }
+  return Result.ok(path);
+};

package/src/regrade/live-api-preserve.ts

@@ -0,0 +1,8 @@
+import type {
+  VocabularyPreserveInventoryEntry,
+  VocabularyRegradePlan,
+} from '@ontrails/regrade';
+
+export const deriveLiveApiPreserveInventory = async (
+  _plan: VocabularyRegradePlan
+): Promise<readonly VocabularyPreserveInventoryEntry[]> => [];

package/src/regrade/plan-artifact.ts

@@ -0,0 +1,265 @@
+/**
+ * Saved Regrade plan artifact shape plus the slug, path, and hash helpers
+ * shared by the `regrade` trails and the consolidated Regrade history module.
+ */
+
+import { isPlainObject } from '@ontrails/core';
+import { vocabularyRegradePlanSchema } from '@ontrails/regrade';
+import type {
+  RegradeReport,
+  RegradeReportEntry,
+  VocabularyRegradePlan,
+} from '@ontrails/regrade';
+import { createHash } from 'node:crypto';
+import { join, normalize, relative } from 'node:path';
+import { z } from 'zod';
+
+export const REGRADE_PLAN_SCHEMA_VERSION = 1;
+
+const regradePlanProvenanceValueSchema = z.enum(['authored', 'derived']);
+
+const classRegradePlanScopeSchema = z
+  .object({
+    exclude: z
+      .array(z.string())
+      .optional()
+      .describe('Root-relative path globs excluded from the class run'),
+    extensions: z
+      .array(z.string())
+      .optional()
+      .describe('Source file extensions scanned by the class run'),
+    include: z
+      .array(z.string())
+      .optional()
+      .describe('Root-relative path globs collected during the class run'),
+  })
+  .strict();
+
+/**
+ * A saved class-mode Regrade plan: which classes run, over what scope, and
+ * why. The parallel payload to {@link vocabularyRegradePlanSchema} — the
+ * `kind` discriminant keeps existing vocabulary plan artifacts
+ * byte-compatible.
+ */
+const classRegradePlanSchema = z.object({
+  classIds: z
+    .array(z.string().min(1))
+    .min(1)
+    .describe('Regrade class ids this plan runs'),
+  id: z.string().min(1).describe('Stable Regrade plan identifier'),
+  intent: z
+    .string()
+    .optional()
+    .describe('Human-authored migration intent for the class run'),
+  kind: z.literal('class').describe('Regrade plan kind'),
+  name: z
+    .string()
+    .min(1)
+    .optional()
+    .describe(
+      'Authored transition name; keys the saved plan and consolidated history filenames'
+    ),
+  scope: classRegradePlanScopeSchema
+    .optional()
+    .describe('Collection scope for the class run'),
+});
+
+export type ClassRegradePlan = z.output<typeof classRegradePlanSchema>;
+
+const regradePlanBodySchema = z.discriminatedUnion('kind', [
+  vocabularyRegradePlanSchema,
+  classRegradePlanSchema,
+]);
+
+export type RegradePlanBody = VocabularyRegradePlan | ClassRegradePlan;
+
+const regradeExpansionCandidateSchema = z.union([
+  z.object({
+    evidence: z
+      .array(
+        z.object({
+          column: z.number().optional(),
+          detail: z.string().optional(),
+          line: z.number().optional(),
+          path: z.string(),
+        })
+      )
+      .default([]),
+    kind: z.enum(['file-rename', 'form', 'namespace', 'preserve']),
+    reason: z.string().optional(),
+    status: z.enum(['pending', 'rejected']).default('pending'),
+    suggestedClassification: z.string(),
+    value: z.string(),
+  }),
+  z
+    .object({
+      detail: z.string().optional(),
+      path: z.string(),
+      status: z.enum(['pending', 'rejected']).default('pending'),
+    })
+    .transform((candidate) => ({
+      evidence: [
+        {
+          ...(candidate.detail === undefined
+            ? {}
+            : { detail: candidate.detail }),
+          path: candidate.path,
+        },
+      ],
+      kind: 'file-rename' as const,
+      ...(candidate.detail === undefined ? {} : { reason: candidate.detail }),
+      status: candidate.status,
+      suggestedClassification: 'legacy-path-candidate',
+      value: candidate.path,
+    })),
+]);
+
+export const regradePlanArtifactSchema = z
+  .object({
+    expansion: z
+      .object({
+        candidates: z.array(regradeExpansionCandidateSchema).default([]),
+      })
+      .optional(),
+    kind: z.literal('regrade-plan'),
+    path: z.string(),
+    plan: regradePlanBodySchema,
+    provenance: z.object({
+      fields: z.record(z.string(), regradePlanProvenanceValueSchema),
+    }),
+    schemaVersion: z.literal(REGRADE_PLAN_SCHEMA_VERSION),
+    sourceHash: z.string(),
+    transitionId: z
+      .string()
+      .min(1)
+      .optional()
+      .describe(
+        'Stable transition identity this plan re-runs; preserves the consolidated history spine'
+      ),
+  })
+  .strict();
+
+export interface RegradePlanExpansion {
+  readonly candidates: readonly {
+    readonly evidence: readonly {
+      readonly column?: number | undefined;
+      readonly detail?: string | undefined;
+      readonly line?: number | undefined;
+      readonly path: string;
+    }[];
+    readonly kind: 'file-rename' | 'form' | 'namespace' | 'preserve';
+    readonly reason?: string | undefined;
+    readonly status: 'pending' | 'rejected';
+    readonly suggestedClassification: string;
+    readonly value: string;
+  }[];
+}
+
+export interface RegradePlanArtifact {
+  readonly expansion?: RegradePlanExpansion | undefined;
+  readonly kind: 'regrade-plan';
+  readonly path: string;
+  readonly plan: RegradePlanBody;
+  readonly provenance: {
+    readonly fields: Readonly<Record<string, 'authored' | 'derived'>>;
+  };
+  readonly schemaVersion: typeof REGRADE_PLAN_SCHEMA_VERSION;
+  readonly sourceHash: string;
+  readonly transitionId?: string | undefined;
+}
+
+/** A plan artifact narrowed to a vocabulary plan body. */
+export type VocabularyRegradePlanArtifact = RegradePlanArtifact & {
+  readonly plan: VocabularyRegradePlan;
+};
+
+const regradeSlugText = (text: string): string =>
+  text
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9]+/g, '-')
+    .replaceAll(/^-|-$/g, '');
+
+const regradePlanSlug = (plan: Pick<VocabularyRegradePlan, 'from' | 'to'>) =>
+  regradeSlugText(`${plan.from}-to-${plan.to}`);
+
+export const regradePlanSlugForBody = (plan: RegradePlanBody): string =>
+  plan.kind === 'class'
+    ? regradeSlugText(plan.name ?? plan.classIds.join('-'))
+    : regradePlanSlug(plan);
+
+const normalizeRelativePath = (path: string): string =>
+  normalize(path).replaceAll('\\', '/');
+
+export const rootRelativePath = (
+  rootDir: string,
+  absolutePath: string
+): string => normalizeRelativePath(relative(rootDir, absolutePath));
+
+export const regradePlanDirectory = (rootDir: string): string =>
+  join(rootDir, '.trails', 'regrade');
+
+export const regradePlanPathForPlan = (
+  rootDir: string,
+  plan: RegradePlanBody
+): string =>
+  join(regradePlanDirectory(rootDir), `${regradePlanSlugForBody(plan)}.json`);
+
+const sourceHashEntryFacts = (
+  entries: readonly RegradeReportEntry[]
+): readonly Pick<
+  RegradeReportEntry,
+  'classId' | 'notes' | 'outcome' | 'path' | 'reason' | 'reviewDetails'
+>[] =>
+  entries
+    .filter(
+      (entry) => entry.outcome === 'rewrite' || entry.outcome === 'needs-review'
+    )
+    .map(({ classId, notes, outcome, path, reason, reviewDetails }) => ({
+      ...(classId === undefined ? {} : { classId }),
+      ...(notes === undefined ? {} : { notes }),
+      outcome,
+      path,
+      ...(reason === undefined ? {} : { reason }),
+      ...(reviewDetails === undefined ? {} : { reviewDetails }),
+    }));
+
+export const regradeSourceHash = (report: RegradeReport): string =>
+  createHash('sha256')
+    .update(
+      JSON.stringify({
+        entries: sourceHashEntryFacts(report.entries),
+        ledger: report.run?.ledger,
+        selectedClassIds: report.selectedClassIds,
+      })
+    )
+    .digest('hex');
+
+const canonicalizeJsonValue = (value: unknown): unknown => {
+  if (Array.isArray(value)) {
+    return value.map((entry) => canonicalizeJsonValue(entry));
+  }
+  if (isPlainObject(value)) {
+    return Object.fromEntries(
+      Object.keys(value)
+        .toSorted()
+        .map((key) => [key, canonicalizeJsonValue(value[key])])
+    );
+  }
+  return value;
+};
+
+/**
+ * JSON.stringify with recursively sorted object keys so structurally equal
+ * values serialize identically regardless of key insertion order. Arrays keep
+ * their authored order.
+ */
+export const canonicalJsonStringify = (value: unknown): string =>
+  JSON.stringify(canonicalizeJsonValue(value));
+
+/**
+ * Canonical content hash of a resolved Regrade plan body — the authored
+ * migration intent. Stable across key insertion order; changes on any edit to
+ * the plan contents.
+ */
+export const regradePlanContentHash = (plan: RegradePlanBody): string =>
+  createHash('sha256').update(canonicalJsonStringify(plan)).digest('hex');

package/src/release/index.ts

@@ -89,6 +89,18 @@ export {
   type RegistryView,
   type RegistryWorkspace,
 } from './native-bun-registry.js';
+export {
+  collectReleaseNotesInput,
+  dedupeReleaseChanges,
+  extractChangelogEntry,
+  renderReleaseNotes,
+  type ReleaseNotesCollectOptions,
+  type ReleaseNotesChange,
+  type ReleaseNotesInput,
+  type ReleaseNotesPackageVersion,
+  type ReleaseNotesParsedChange,
+} from './notes.js';
+export { runReleaseNotesCli } from './notes-cli.js';
 export {
   channelIntentForDistTag,
   evaluateReleasePolicy,
@@ -115,6 +127,11 @@ export {
   type ReleaseSmokeCheckResult,
   type ReleaseSmokeResult,
 } from './smoke.js';
+export {
+  runLockRoundtripSmoke,
+  type LockRoundtripSmokeOptions,
+  type LockRoundtripSmokeResult,
+} from './lock-roundtrip-smoke.js';
 export {
   runPackedArtifactsSmoke,
   type PackedArtifactsSmokeResult,