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

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,

package/src/release/lock-roundtrip-smoke.ts

@@ -0,0 +1,230 @@
+/**
+ * Lock round-trip invariant (TRL-1200).
+ *
+ * For every committed `trails.lock` in the repo, a fresh `trails compile`
+ * against a cold per-user store followed by `trails validate` must be
+ * green, and the recompiled lock must be byte-identical to the committed
+ * one. Evidence the toolchain cannot reproduce does not merge.
+ *
+ * Failures name the divergence and the command that fixes it. Hand-editing
+ * a lock is never the remediation.
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { dirname, join, relative, resolve } from 'node:path';
+
+const trailsBinFor = (repoRoot: string): string =>
+  join(repoRoot, 'apps/trails/bin/trails.ts');
+
+export interface LockRoundtripSmokeResult {
+  readonly check: 'lock-roundtrip';
+  readonly lockCount: number;
+  readonly message: string;
+  readonly passed: true;
+}
+
+export interface LockRoundtripSmokeOptions {
+  /** Override lock discovery with explicit repo-relative lock paths. */
+  readonly lockPaths?: readonly string[];
+  readonly repoRoot?: string;
+}
+
+const discoverCommittedLocks = (repoRoot: string): readonly string[] => {
+  const result = Bun.spawnSync({
+    cmd: ['git', 'ls-files', '--', 'trails.lock', '*/trails.lock'],
+    cwd: repoRoot,
+    stderr: 'pipe',
+    stdout: 'pipe',
+  });
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `lock-roundtrip: git ls-files failed: ${result.stderr.toString()}`
+    );
+  }
+  return result.stdout
+    .toString()
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+};
+
+const resolveAppModule = (appDir: string): string => {
+  if (existsSync(join(appDir, 'src', 'app.ts'))) {
+    return './src/app.ts';
+  }
+  const packageJsonPath = join(appDir, 'package.json');
+  if (existsSync(packageJsonPath)) {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as {
+      readonly main?: unknown;
+    };
+    if (typeof parsed.main === 'string') {
+      return parsed.main;
+    }
+  }
+  throw new Error(
+    `lock-roundtrip: unable to resolve the app module for "${appDir}" — expected src/app.ts or a package.json "main" entry.`
+  );
+};
+
+const runTrailsCommand = (
+  repoRoot: string,
+  stateHome: string,
+  args: readonly string[]
+): { readonly exitCode: number; readonly output: string } => {
+  const result = Bun.spawnSync({
+    cmd: [process.execPath, trailsBinFor(repoRoot), ...args],
+    cwd: repoRoot,
+    env: {
+      ...process.env,
+      NO_COLOR: '1',
+      TRAILS_STATE_HOME: stateHome,
+      XDG_STATE_HOME: stateHome,
+    } as Record<string, string | undefined>,
+    stderr: 'pipe',
+    stdout: 'pipe',
+  });
+  return {
+    exitCode: result.exitCode,
+    output: `${result.stdout.toString()}${result.stderr.toString()}`,
+  };
+};
+
+const summarizeEntryIds = (value: unknown): readonly string[] => {
+  if (typeof value !== 'object' || value === null) {
+    return [];
+  }
+  const { topoGraph } = value as {
+    readonly topoGraph?: { readonly entries?: readonly { id?: string }[] };
+  };
+  return (topoGraph?.entries ?? [])
+    .map((entry) => entry.id)
+    .filter((id): id is string => typeof id === 'string');
+};
+
+/** Name what diverged between the committed and recompiled lock bytes. */
+const describeLockDivergence = (
+  committed: string,
+  recompiled: string
+): readonly string[] => {
+  const details: string[] = [];
+  let committedParsed: unknown;
+  let recompiledParsed: unknown;
+  try {
+    committedParsed = JSON.parse(committed);
+    recompiledParsed = JSON.parse(recompiled);
+  } catch {
+    return ['committed lock is not valid JSON'];
+  }
+  const committedLock = committedParsed as Record<string, unknown>;
+  const recompiledLock = recompiledParsed as Record<string, unknown>;
+
+  for (const section of ['scope', 'summary', 'topoGraphHash', 'version']) {
+    const left = JSON.stringify(committedLock[section]);
+    const right = JSON.stringify(recompiledLock[section]);
+    if (left !== right) {
+      details.push(`${section}: committed ${left} vs recompiled ${right}`);
+    }
+  }
+
+  const committedIds = new Set(summarizeEntryIds(committedParsed));
+  const recompiledIds = new Set(summarizeEntryIds(recompiledParsed));
+  const missing = [...committedIds].filter((id) => !recompiledIds.has(id));
+  const added = [...recompiledIds].filter((id) => !committedIds.has(id));
+  if (missing.length > 0) {
+    details.push(`entries only in committed lock: ${missing.join(', ')}`);
+  }
+  if (added.length > 0) {
+    details.push(`entries only in recompiled lock: ${added.join(', ')}`);
+  }
+  if (details.length === 0) {
+    details.push('topoGraph entry content differs (same ids, different facts)');
+  }
+  return details;
+};
+
+const checkSingleLock = async (
+  repoRoot: string,
+  lockPath: string
+): Promise<void> => {
+  const absoluteLockPath = resolve(repoRoot, lockPath);
+  const appDir = dirname(absoluteLockPath);
+  const relativeAppDir = relative(repoRoot, appDir) || '.';
+  const appModule = resolveAppModule(appDir);
+  const committedBytes = readFileSync(absoluteLockPath, 'utf8');
+  const stateHome = await mkdtemp(join(tmpdir(), 'lock-roundtrip-'));
+  const fixCommand = `bun apps/trails/bin/trails.ts compile --module ${appModule} --root-dir ${relativeAppDir} --permit '{"id":"lock-refresh","scopes":["topo:write"]}'`;
+  const remediation = `Fix: run \`${fixCommand}\` and commit the refreshed trails.lock. Never hand-edit the lock.`;
+
+  try {
+    const compileResult = runTrailsCommand(repoRoot, stateHome, [
+      'compile',
+      '--module',
+      appModule,
+      '--root-dir',
+      relativeAppDir,
+      '--permit',
+      '{"id":"lock-roundtrip-gate","scopes":["topo:write"]}',
+      '--json',
+    ]);
+    if (compileResult.exitCode !== 0) {
+      throw new Error(
+        `lock-roundtrip: cold compile failed for ${lockPath}.\n${compileResult.output}\n${remediation}`
+      );
+    }
+
+    const validateResult = runTrailsCommand(repoRoot, stateHome, [
+      'validate',
+      '--module',
+      appModule,
+      '--root-dir',
+      relativeAppDir,
+      '--json',
+    ]);
+    if (validateResult.exitCode !== 0) {
+      throw new Error(
+        `lock-roundtrip: validate failed for ${lockPath} after a cold recompile.\n${validateResult.output}\n${remediation}`
+      );
+    }
+
+    const recompiledBytes = readFileSync(absoluteLockPath, 'utf8');
+    if (recompiledBytes !== committedBytes) {
+      const details = describeLockDivergence(committedBytes, recompiledBytes);
+      throw new Error(
+        [
+          `lock-roundtrip: ${lockPath} is not byte-identical after a cold recompile.`,
+          ...details.map((detail) => `  - ${detail}`),
+          remediation,
+        ].join('\n')
+      );
+    }
+  } finally {
+    // The gate is read-only: always restore the committed bytes.
+    writeFileSync(absoluteLockPath, committedBytes);
+    await rm(stateHome, { force: true, recursive: true });
+  }
+};
+
+export const runLockRoundtripSmoke = async (
+  options?: LockRoundtripSmokeOptions
+): Promise<LockRoundtripSmokeResult> => {
+  const repoRoot = resolve(options?.repoRoot ?? process.cwd());
+  const lockPaths = options?.lockPaths ?? discoverCommittedLocks(repoRoot);
+
+  for (const lockPath of lockPaths) {
+    await checkSingleLock(repoRoot, lockPath);
+  }
+
+  const message =
+    lockPaths.length === 0
+      ? 'lock-roundtrip: no committed trails.lock files found — nothing to verify'
+      : `lock-roundtrip: ${lockPaths.length} committed trails.lock file(s) recompiled cold — validate green, byte-identical (${lockPaths.join(', ')})`;
+
+  return {
+    check: 'lock-roundtrip',
+    lockCount: lockPaths.length,
+    message,
+    passed: true,
+  };
+};

package/src/release/notes-cli.ts

@@ -0,0 +1,171 @@
+import { mkdtemp, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import { collectReleaseNotesInput, renderReleaseNotes } from './notes.js';
+import type { ReleaseNotesCollectOptions } from './notes.js';
+
+const RELEASE_BRANCH = 'changeset-release/main';
+
+type CliOptions = Omit<ReleaseNotesCollectOptions, 'mode'>;
+
+const runText = async (cmd: readonly string[]): Promise<string> => {
+  const proc = Bun.spawn([...cmd], { stderr: 'pipe', stdout: 'pipe' });
+  const [stdout, stderr, exitCode] = await Promise.all([
+    new Response(proc.stdout).text(),
+    new Response(proc.stderr).text(),
+    proc.exited,
+  ]);
+  if (exitCode !== 0) {
+    throw new Error(
+      `Command failed (${exitCode}): ${cmd.join(' ')}\n${stderr.trim()}`
+    );
+  }
+  return stdout.trim();
+};
+
+const readRepository = async (): Promise<string> =>
+  process.env['GITHUB_REPOSITORY'] ??
+  (await runText([
+    'gh',
+    'repo',
+    'view',
+    '--json',
+    'nameWithOwner',
+    '--jq',
+    '.nameWithOwner',
+  ]));
+
+const findReleasePullRequestNumber = async (
+  repo: string
+): Promise<string | undefined> => {
+  const output = await runText([
+    'gh',
+    'pr',
+    'list',
+    '--repo',
+    repo,
+    '--head',
+    RELEASE_BRANCH,
+    '--base',
+    'main',
+    '--state',
+    'open',
+    '--json',
+    'number',
+    '--jq',
+    '.[0].number // empty',
+  ]);
+  return output || undefined;
+};
+
+const parseArgs = (args: readonly string[]): CliOptions => {
+  let distTag: string | undefined;
+  let repo: string | undefined;
+  let repoRoot = resolve(process.cwd());
+  let version: string | undefined;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === '--dist-tag') {
+      index += 1;
+      distTag = args[index];
+      continue;
+    }
+    if (arg === '--repo') {
+      index += 1;
+      repo = args[index];
+      continue;
+    }
+    if (arg === '--repo-root') {
+      index += 1;
+      repoRoot = resolve(args[index] ?? repoRoot);
+      continue;
+    }
+    if (arg === '--version') {
+      index += 1;
+      version = args[index];
+      continue;
+    }
+    throw new Error(`Unknown release-notes option: ${arg}`);
+  }
+
+  return {
+    ...(distTag === undefined ? {} : { distTag }),
+    ...(repo === undefined ? {} : { repo }),
+    repoRoot,
+    ...(version === undefined ? {} : { version }),
+  };
+};
+
+const commandGithubRelease = async (args: readonly string[]): Promise<void> => {
+  const input = await collectReleaseNotesInput({
+    ...parseArgs(args),
+    mode: 'github-release',
+  });
+  process.stdout.write(renderReleaseNotes(input));
+};
+
+const commandReleasePr = async (args: readonly string[]): Promise<void> => {
+  const input = await collectReleaseNotesInput({
+    ...parseArgs(args),
+    mode: 'release-pr',
+  });
+  process.stdout.write(renderReleaseNotes(input));
+};
+
+const commandUpdateReleasePr = async (
+  args: readonly string[]
+): Promise<void> => {
+  const options = parseArgs(args);
+  const repo = options.repo ?? (await readRepository());
+  const number = await findReleasePullRequestNumber(repo);
+  if (!number) {
+    throw new Error(`No open ${RELEASE_BRANCH} pull request found`);
+  }
+  const input = await collectReleaseNotesInput({
+    ...options,
+    mode: 'release-pr',
+    repo,
+  });
+  const dir = await mkdtemp(join(tmpdir(), 'trails-release-notes-'));
+  const bodyPath = join(dir, 'body.md');
+  await writeFile(bodyPath, renderReleaseNotes(input));
+  await runText([
+    'gh',
+    'pr',
+    'edit',
+    number,
+    '--repo',
+    repo,
+    '--body-file',
+    bodyPath,
+  ]);
+  console.error(`trails: updated release PR #${number} body`);
+};
+
+export const runReleaseNotesCli = async (
+  args: readonly string[] = process.argv.slice(2)
+): Promise<number> => {
+  try {
+    const [command, ...rest] = args;
+    if (command === 'github-release') {
+      await commandGithubRelease(rest);
+      return 0;
+    }
+    if (command === 'release-pr') {
+      await commandReleasePr(rest);
+      return 0;
+    }
+    if (command === 'update-release-pr') {
+      await commandUpdateReleasePr(rest);
+      return 0;
+    }
+    throw new Error(
+      'Usage: bun scripts/release-notes.ts <github-release|release-pr|update-release-pr> [--version <version>] [--dist-tag <tag>] [--repo <owner/name>] [--repo-root <path>]'
+    );
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    return 1;
+  }
+};