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

package/src/release/notes.ts

@@ -0,0 +1,390 @@
+/* oxlint-disable max-lines-per-function, max-statements -- release-note parsing keeps source extraction explicit. */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+const DEFAULT_REPO = 'outfitter-dev/trails';
+
+interface PackageJson {
+  readonly name?: string;
+  readonly private?: boolean;
+  readonly version?: string;
+}
+
+interface ReleaseNotesWorkspace {
+  readonly isPrivate: boolean;
+  readonly name: string;
+  readonly path: string;
+  readonly version: string;
+}
+
+export interface ReleaseNotesChange {
+  readonly commit?: string | undefined;
+  readonly packages: readonly string[];
+  readonly summary: string;
+  readonly url?: string | undefined;
+}
+
+export interface ReleaseNotesPackageVersion {
+  readonly name: string;
+  readonly version: string;
+}
+
+export interface ReleaseNotesInput {
+  readonly changes: readonly ReleaseNotesChange[];
+  readonly distTag: string;
+  readonly mode: 'github-release' | 'release-pr';
+  readonly packageVersions: readonly ReleaseNotesPackageVersion[];
+  readonly repo?: string | undefined;
+  readonly version: string;
+}
+
+interface ChangelogEntryInput {
+  readonly changelog: string;
+  readonly packageName: string;
+  readonly version: string;
+}
+
+export interface ReleaseNotesParsedChange {
+  readonly commit?: string | undefined;
+  readonly packageName: string;
+  readonly summary: string;
+  readonly url?: string | undefined;
+}
+
+export interface ReleaseNotesCollectOptions {
+  readonly distTag?: string | undefined;
+  readonly mode: ReleaseNotesInput['mode'];
+  readonly repo?: string | undefined;
+  readonly repoRoot: string;
+  readonly version?: string | undefined;
+}
+
+interface CurrentParsedChange {
+  readonly commit?: string | undefined;
+  readonly packageName: string;
+  readonly summaryLines: string[];
+  readonly url?: string | undefined;
+}
+
+const readJson = async <T>(path: string): Promise<T> =>
+  (await Bun.file(path).json()) as T;
+
+const discoverWorkspaceDirs = async (
+  repoRoot: string,
+  patterns: readonly string[]
+): Promise<string[]> => {
+  const dirs: string[] = [];
+
+  for (const pattern of patterns) {
+    if (pattern.endsWith('/*')) {
+      const parent = join(repoRoot, pattern.slice(0, -2));
+      const entries = await readdir(parent, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) {
+          continue;
+        }
+        const dir = join(parent, entry.name);
+        if (await Bun.file(join(dir, 'package.json')).exists()) {
+          dirs.push(dir);
+        }
+      }
+      continue;
+    }
+
+    const dir = join(repoRoot, pattern);
+    if (await Bun.file(join(dir, 'package.json')).exists()) {
+      dirs.push(dir);
+    }
+  }
+
+  return dirs;
+};
+
+const discoverReleaseNotesWorkspaces = async (
+  repoRoot: string,
+  { includePrivate }: { readonly includePrivate: boolean }
+): Promise<ReleaseNotesWorkspace[]> => {
+  const root = await readJson<{ workspaces?: string[] }>(
+    join(repoRoot, 'package.json')
+  );
+  const dirs = await discoverWorkspaceDirs(repoRoot, root.workspaces ?? []);
+  const workspaces: ReleaseNotesWorkspace[] = [];
+
+  for (const dir of dirs) {
+    const pkg = await readJson<PackageJson>(join(dir, 'package.json'));
+    if (
+      typeof pkg.name !== 'string' ||
+      !pkg.name.startsWith('@ontrails/') ||
+      typeof pkg.version !== 'string' ||
+      (pkg.private === true && !includePrivate)
+    ) {
+      continue;
+    }
+    workspaces.push({
+      isPrivate: pkg.private === true,
+      name: pkg.name,
+      path: dir.slice(repoRoot.length + 1),
+      version: pkg.version,
+    });
+  }
+
+  return workspaces.toSorted((a, b) => a.name.localeCompare(b.name));
+};
+
+const readTrailsVersion = async (repoRoot: string): Promise<string> => {
+  const pkg = await readJson<PackageJson>(
+    join(repoRoot, 'apps', 'trails', 'package.json')
+  );
+  if (!pkg.version) {
+    throw new Error('Missing version in apps/trails/package.json');
+  }
+  return pkg.version;
+};
+
+const distTagForVersion = (version: string): string =>
+  version.includes('-')
+    ? (version.split('-')[1]?.split('.')[0] ?? 'beta')
+    : 'latest';
+
+export const extractChangelogEntry = (
+  changelog: string,
+  version: string
+): string | undefined => {
+  const lines = changelog.split('\n');
+  const heading = `## ${version}`;
+  const start = lines.findIndex((line) => line.trim() === heading);
+  if (start === -1) {
+    return undefined;
+  }
+
+  let end = lines.length;
+  for (let index = start + 1; index < lines.length; index += 1) {
+    if (/^##\s+\S/u.test(lines[index] ?? '')) {
+      end = index;
+      break;
+    }
+  }
+
+  return lines
+    .slice(start + 1, end)
+    .join('\n')
+    .trim();
+};
+
+const normalizeSummary = (lines: readonly string[]): string =>
+  lines.join(' ').replaceAll(/\s+/gu, ' ').trim();
+
+const parseChangeStart = (
+  line: string
+): Omit<ReleaseNotesParsedChange, 'packageName'> | undefined => {
+  if (
+    !line.startsWith('- ') ||
+    line.startsWith('- Updated dependencies') ||
+    line.startsWith('- @ontrails/')
+  ) {
+    return undefined;
+  }
+
+  const linked = line.match(/^- \[`?([0-9a-f]{7,40})`?\]\(([^)]+)\):\s*(.*)$/u);
+  if (linked) {
+    return {
+      commit: linked[1],
+      summary: linked[3] ?? '',
+      url: linked[2],
+    };
+  }
+
+  const raw = line.match(/^- ([0-9a-f]{7,40}):\s*(.*)$/u);
+  if (raw) {
+    return {
+      commit: raw[1],
+      summary: raw[2] ?? '',
+    };
+  }
+
+  return { summary: line.slice(2) };
+};
+
+const parseChangelogEntryChanges = ({
+  changelog,
+  packageName,
+  version,
+}: ChangelogEntryInput): ReleaseNotesParsedChange[] => {
+  const entry = extractChangelogEntry(changelog, version);
+  if (!entry) {
+    return [];
+  }
+
+  const changes: ReleaseNotesParsedChange[] = [];
+  let current: CurrentParsedChange | undefined;
+
+  const flush = () => {
+    if (!current) {
+      return;
+    }
+    const summary = normalizeSummary(current.summaryLines);
+    if (summary) {
+      changes.push({
+        ...(current.commit === undefined ? {} : { commit: current.commit }),
+        packageName: current.packageName,
+        summary,
+        ...(current.url === undefined ? {} : { url: current.url }),
+      });
+    }
+  };
+
+  for (const line of entry.split('\n')) {
+    const start = parseChangeStart(line);
+    if (start) {
+      flush();
+      current = {
+        ...(start.commit === undefined ? {} : { commit: start.commit }),
+        packageName,
+        summaryLines: [start.summary],
+        ...(start.url === undefined ? {} : { url: start.url }),
+      };
+      continue;
+    }
+
+    if (current && line.startsWith('  ') && line.trim()) {
+      current.summaryLines.push(line.trim());
+      continue;
+    }
+
+    if (line.startsWith('- ')) {
+      flush();
+      current = undefined;
+    }
+  }
+
+  flush();
+  return changes;
+};
+
+export const dedupeReleaseChanges = (
+  changes: readonly ReleaseNotesParsedChange[]
+): ReleaseNotesChange[] => {
+  const byKey = new Map<string, ReleaseNotesChange>();
+
+  for (const change of changes) {
+    const key = `${change.commit ?? ''}\n${change.summary}`;
+    const existing = byKey.get(key);
+    if (existing) {
+      byKey.set(key, {
+        ...existing,
+        packages: [
+          ...new Set([...existing.packages, change.packageName]),
+        ].toSorted(),
+      });
+      continue;
+    }
+
+    byKey.set(key, {
+      ...(change.commit === undefined ? {} : { commit: change.commit }),
+      packages: [change.packageName],
+      summary: change.summary,
+      ...(change.url === undefined ? {} : { url: change.url }),
+    });
+  }
+
+  return [...byKey.values()];
+};
+
+const renderCommitLink = (change: ReleaseNotesChange, repo: string): string => {
+  if (!change.commit) {
+    return '';
+  }
+  const short = change.commit.slice(0, 7);
+  const url =
+    change.url ?? `https://github.com/${repo}/commit/${change.commit}`;
+  return `[\`${short}\`](${url}): `;
+};
+
+const renderPackages = (packages: readonly string[]): string =>
+  packages.map((name) => `\`${name}\``).join(', ');
+
+export const renderReleaseNotes = ({
+  changes,
+  distTag,
+  mode,
+  packageVersions,
+  repo = DEFAULT_REPO,
+  version,
+}: ReleaseNotesInput): string => {
+  const intro =
+    mode === 'release-pr'
+      ? `${packageVersions.length} \`@ontrails/*\` packages will be bumped to \`${version}\`.`
+      : `Published the publishable \`@ontrails/*\` package set at \`${version}\` on the \`${distTag}\` dist-tag.`;
+  const highlights = changes.slice(0, 5);
+  const lines = [`# Release ${version}`, '', intro, '', '## Highlights', ''];
+
+  if (highlights.length === 0) {
+    lines.push('- No user-facing changes were detected in package changelogs.');
+  } else {
+    lines.push(...highlights.map((change) => `- ${change.summary}`));
+  }
+
+  lines.push('', '## Changes', '');
+  if (changes.length === 0) {
+    lines.push('- No user-facing changes were detected in package changelogs.');
+  } else {
+    lines.push(
+      ...changes.map(
+        (change) =>
+          `- ${renderCommitLink(change, repo)}${change.summary} Packages: ${renderPackages(change.packages)}`
+      )
+    );
+  }
+
+  lines.push(
+    '',
+    '<details>',
+    '<summary>Package Versions</summary>',
+    '',
+    ...packageVersions.map((pkg) => `- \`${pkg.name}@${pkg.version}\``),
+    '',
+    '</details>',
+    ''
+  );
+
+  return lines.join('\n');
+};
+
+export const collectReleaseNotesInput = async ({
+  distTag,
+  mode,
+  repo,
+  repoRoot,
+  version,
+}: ReleaseNotesCollectOptions): Promise<ReleaseNotesInput> => {
+  const resolvedVersion = version ?? (await readTrailsVersion(repoRoot));
+  const resolvedDistTag = distTag ?? distTagForVersion(resolvedVersion);
+  const workspaces = await discoverReleaseNotesWorkspaces(repoRoot, {
+    includePrivate: mode === 'release-pr',
+  });
+  const packageVersions = workspaces.map((workspace) => ({
+    name: workspace.name,
+    version: workspace.version,
+  }));
+  const parsedChangesByPackage = await Promise.all(
+    workspaces.map(async (workspace: ReleaseNotesWorkspace) =>
+      parseChangelogEntryChanges({
+        changelog: await Bun.file(
+          join(repoRoot, workspace.path, 'CHANGELOG.md')
+        ).text(),
+        packageName: workspace.name,
+        version: resolvedVersion,
+      })
+    )
+  );
+  const parsedChanges = parsedChangesByPackage.flat();
+
+  return {
+    changes: dedupeReleaseChanges(parsedChanges),
+    distTag: resolvedDistTag,
+    mode,
+    packageVersions,
+    ...(repo === undefined ? {} : { repo }),
+    version: resolvedVersion,
+  };
+};

package/src/release/pack-coherence.ts

@@ -1,5 +1,6 @@
 import { readFile, readdir, writeFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
+import { escapeRegExp } from '@ontrails/core';
 
 export interface ReleasePackCoherenceInput {
   readonly branchName?: string | undefined;
@@ -234,9 +235,6 @@ export const findLockfileWorkspaceMetadataMismatches = ({
   return mismatches;
 };
 
-const escapeRegExp = (text: string): string =>
-  text.replaceAll(/[.*+?^${}()|[\]\\]/gu, '\\$&');
-
 const findWorkspaceBlockRange = (
   text: string,
   workspacePath: string

package/src/release/smoke.ts

@@ -1,3 +1,5 @@
+import { runLockRoundtripSmoke } from './lock-roundtrip-smoke.js';
+import type { LockRoundtripSmokeResult } from './lock-roundtrip-smoke.js';
 import { runPackedArtifactsSmoke } from './packed-artifacts-smoke.js';
 import type { PackedArtifactsSmokeResult } from './packed-artifacts-smoke.js';
 import { runWayfinderDogfoodSmoke } from './wayfinder-dogfood-smoke.js';
@@ -5,12 +7,14 @@ import type { WayfinderDogfoodSmokeResult } from './wayfinder-dogfood-smoke.js';
 
 export const releaseSmokeCheckValues = [
   'all',
+  'lock-roundtrip',
   'packed-artifacts',
   'wayfinder-dogfood',
 ] as const;
 export type ReleaseSmokeCheck = (typeof releaseSmokeCheckValues)[number];
 
 export type ReleaseSmokeCheckResult =
+  | LockRoundtripSmokeResult
   | PackedArtifactsSmokeResult
   | WayfinderDogfoodSmokeResult;
 
@@ -23,7 +27,9 @@ export interface ReleaseSmokeResult {
 const checksForInput = (
   check: ReleaseSmokeCheck
 ): readonly Exclude<ReleaseSmokeCheck, 'all'>[] =>
-  check === 'all' ? ['packed-artifacts', 'wayfinder-dogfood'] : [check];
+  check === 'all'
+    ? ['lock-roundtrip', 'packed-artifacts', 'wayfinder-dogfood']
+    : [check];
 
 export const runReleaseSmoke = async (
   check: ReleaseSmokeCheck
@@ -31,6 +37,10 @@ export const runReleaseSmoke = async (
   const results: ReleaseSmokeCheckResult[] = [];
 
   for (const selectedCheck of checksForInput(check)) {
+    if (selectedCheck === 'lock-roundtrip') {
+      results.push(await runLockRoundtripSmoke());
+      continue;
+    }
     if (selectedCheck === 'packed-artifacts') {
       results.push(await runPackedArtifactsSmoke());
       continue;

package/src/release/wayfinder-dogfood-smoke.ts

@@ -138,7 +138,7 @@ const writeOperatorAppWrapper = async (tempRoot: string): Promise<void> => {
   const appModuleUrl = pathToFileURL(join(repoRoot, 'apps/trails/src/app.ts'));
   await writeFile(
     join(srcDir, 'app.ts'),
-    `export { app, trailsCliAliases } from ${JSON.stringify(appModuleUrl.href)};\n`
+    `export { app, trailsOverlays } from ${JSON.stringify(appModuleUrl.href)};\n`
   );
 };
 

package/src/run-schema.ts

@@ -14,6 +14,18 @@ const writeJson = (value: unknown): void => {
   process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 };
 
+const pathStartsWith = (
+  path: readonly string[],
+  prefix: readonly string[]
+): boolean =>
+  path.length > prefix.length &&
+  prefix.every((segment, index) => path[index] === segment);
+
+const childCommandsForPath = (
+  schema: ReturnType<typeof deriveCliSchema>,
+  path: readonly string[]
+) => schema.commands.filter((entry) => pathStartsWith(entry.commandPath, path));
+
 export const attachSchemaCommand = (
   program: Command,
   commands: readonly CliCommand[]
@@ -30,12 +42,33 @@ export const attachSchemaCommand = (
       }
 
       const command = findCliSchemaCommand(schema, path);
+      const children = childCommandsForPath(schema, path);
       if (command === undefined) {
+        if (children.length > 0) {
+          writeJson({
+            namespace: {
+              commandPath: path,
+              commands: children,
+            },
+          });
+          return;
+        }
+
         process.stderr.write(`Unknown CLI command: ${path.join(' ')}\n`);
         process.exitCode = 1;
         return;
       }
 
-      writeJson({ command });
+      writeJson(
+        children.length === 0
+          ? { command }
+          : {
+              command,
+              namespace: {
+                commandPath: path,
+                commands: children,
+              },
+            }
+      );
     });
 };

package/src/trails/compile.ts

@@ -1,5 +1,6 @@
 import { trail } from '@ontrails/core';
-import type { CliCommandAliasInput, Result, Topo } from '@ontrails/core';
+import type { Result, Topo } from '@ontrails/core';
+import type { TopoGraphOverlayRegistration } from '@ontrails/topographer';
 import { z } from 'zod';
 
 import { withFreshOperatorApp } from './operator-context.js';
@@ -13,11 +14,9 @@ import {
 export const compileCurrentTopo = async (
   app: Topo,
   options?: {
-    readonly cliAliases?:
-      | Readonly<Record<string, readonly CliCommandAliasInput[]>>
-      | undefined;
     readonly force?: boolean | undefined;
     readonly rootDir?: string;
+    readonly overlays?: readonly TopoGraphOverlayRegistration[] | undefined;
   }
 ): Promise<Result<TopoExportReport, Error>> => exportCurrentTopo(app, options);
 
@@ -36,8 +35,8 @@ export const compileTrail = trail('compile', {
   blaze: async (input: CompileTrailInput, ctx) =>
     withFreshOperatorApp(input, ctx, ({ lease, rootDir }) =>
       compileCurrentTopo(lease.app, {
-        cliAliases: lease.cliAliases,
         force: input.force,
+        overlays: lease.overlays,
         rootDir,
       })
     ),

package/src/trails/create-adapter.ts

@@ -13,9 +13,16 @@ import type {
   AdapterTargetConformanceManifest,
   AdapterTargetPlacement,
 } from '@ontrails/adapter-kit';
-import { Result, trail, ValidationError } from '@ontrails/core';
-import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import {
+  findWorkspacePackage,
+  listWorkspacePatterns,
+  Result,
+  trail,
+  ValidationError,
+} from '@ontrails/core';
+import type { WorkspaceRootManifest } from '@ontrails/core';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
 import { z } from 'zod';
 
 import {
@@ -69,20 +76,11 @@ interface AdapterOperationPlan {
   readonly targetKey: string;
 }
 
-interface RootManifest {
-  readonly workspaces?: unknown;
-}
-
 interface WorkspacePackageManifest {
   readonly exports?: unknown;
   readonly name?: unknown;
 }
 
-interface WorkspacePackageName {
-  readonly name: string;
-  readonly workspacePath: string;
-}
-
 interface LocalNamedReexport {
   readonly local: string;
   readonly specifier: string;
@@ -123,27 +121,6 @@ const readJson = <T>(path: string): T | undefined => {
   }
 };
 
-const workspacePatternsFromManifest = (
-  manifest: RootManifest | undefined
-): readonly string[] => {
-  const { workspaces } = manifest ?? {};
-  if (Array.isArray(workspaces)) {
-    return workspaces.filter(
-      (pattern): pattern is string => typeof pattern === 'string'
-    );
-  }
-
-  const packages =
-    workspaces && typeof workspaces === 'object' && !Array.isArray(workspaces)
-      ? (workspaces as Record<string, unknown>)['packages']
-      : undefined;
-  return Array.isArray(packages)
-    ? packages.filter(
-        (pattern): pattern is string => typeof pattern === 'string'
-      )
-    : [];
-};
-
 const normalizeWorkspacePattern = (pattern: string): string =>
   pattern.replace(/^\.\//u, '').replace(/\/+$/u, '');
 
@@ -169,54 +146,14 @@ const rootWorkspaceIncludesPath = (
   rootDir: string,
   workspacePath: string
 ): boolean => {
-  const rootManifest = readJson<RootManifest>(join(rootDir, 'package.json'));
-  return workspacePatternsFromManifest(rootManifest).some((pattern) =>
+  const rootManifest = readJson<WorkspaceRootManifest>(
+    join(rootDir, 'package.json')
+  );
+  return listWorkspacePatterns(rootManifest).some((pattern) =>
     workspacePatternCoversPath(pattern, workspacePath)
   );
 };
 
-const workspaceDirsForPattern = (
-  rootDir: string,
-  pattern: string
-): readonly string[] => {
-  if (!pattern.endsWith('/*')) {
-    const workspaceDir = join(rootDir, pattern);
-    return existsSync(workspaceDir) ? [workspaceDir] : [];
-  }
-
-  const groupDir = join(rootDir, pattern.slice(0, -2));
-  if (!existsSync(groupDir)) {
-    return [];
-  }
-
-  return readdirSync(groupDir, { withFileTypes: true })
-    .filter((entry) => entry.isDirectory())
-    .map((entry) => join(groupDir, entry.name))
-    .toSorted();
-};
-
-const findWorkspacePackageName = (
-  rootDir: string,
-  packageName: string
-): WorkspacePackageName | undefined => {
-  const rootManifest = readJson<RootManifest>(join(rootDir, 'package.json'));
-  for (const pattern of workspacePatternsFromManifest(rootManifest)) {
-    for (const workspaceDir of workspaceDirsForPattern(rootDir, pattern)) {
-      const manifest = readJson<WorkspacePackageManifest>(
-        join(workspaceDir, 'package.json')
-      );
-      if (manifest?.name === packageName) {
-        return {
-          name: packageName,
-          workspacePath: relative(rootDir, workspaceDir),
-        };
-      }
-    }
-  }
-
-  return undefined;
-};
-
 const resolvePhysicalRootDir = (
   rootDir: string
 ): Result<string, ValidationError> => {
@@ -882,10 +819,13 @@ const buildExtractedPlan = (
   if (!packageNamePattern.test(packageName)) {
     return fail(packageNameMessage);
   }
-  const existingPackage = findWorkspacePackageName(rootDir, packageName);
+  const existingPackage = findWorkspacePackage<WorkspacePackageManifest>(
+    rootDir,
+    packageName
+  );
   if (existingPackage) {
     return fail(
-      `Workspace package name "${existingPackage.name}" already exists at ${existingPackage.workspacePath}.`
+      `Workspace package name "${packageName}" already exists at ${existingPackage.workspacePath}.`
     );
   }
 

package/src/trails/deprecate.ts

@@ -51,7 +51,7 @@ export const deprecateTrail = trail('deprecate', {
   }),
   intent: 'write',
   output: z.object({
-    file: z.string(),
+    filePath: z.string(),
     trailId: z.string(),
     updated: z.boolean(),
   }),