@ontrails/trails 0.2.0

package/src/scaffold-version-sync.ts

@@ -0,0 +1,183 @@
+/**
+ * Scaffold dependency version derivation for the `create.versions` trail.
+ *
+ * Generates or validates `apps/trails/src/scaffold-versions.generated.ts`
+ * from the root `package.json` catalog and devDependencies, and validates
+ * that generated `@ontrails/*` package pins track the `@ontrails/trails`
+ * version exactly.
+ */
+
+import { resolve } from 'node:path';
+
+import {
+  ontrailsPackageRange as appOntrailsPackageRange,
+  trailsPackageVersion as appTrailsPackageVersion,
+} from './versions.js';
+
+interface RootPackageJson {
+  readonly catalog?: Record<string, string>;
+  readonly devDependencies?: Record<string, string>;
+}
+
+export interface OntrailsPackagePinState {
+  readonly ontrailsPackageRange?: string;
+  readonly trailsPackageVersion?: string;
+}
+
+export interface SyncScaffoldVersionsResult {
+  readonly generatedPath: string;
+  readonly mode: 'check' | 'write';
+  readonly written: boolean;
+}
+
+export const diagnoseOntrailsPackagePin = ({
+  ontrailsPackageRange,
+  trailsPackageVersion,
+}: OntrailsPackagePinState): string | undefined => {
+  if (
+    typeof ontrailsPackageRange !== 'string' ||
+    typeof trailsPackageVersion !== 'string'
+  ) {
+    return (
+      'create.versions: apps/trails/src/versions.ts must export ' +
+      '`ontrailsPackageRange` and `trailsPackageVersion`.'
+    );
+  }
+  if (ontrailsPackageRange !== trailsPackageVersion) {
+    return (
+      'create.versions: scaffolded @ontrails/* packages must be exact ' +
+      `pins for @ontrails/trails (${trailsPackageVersion}); got ` +
+      `${ontrailsPackageRange}.`
+    );
+  }
+  return undefined;
+};
+
+const requireValue = (
+  value: string | undefined,
+  label: string,
+  source: string,
+  rootPackageJsonPath: string
+): string => {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(
+      `create.versions: missing "${label}" under ${source} in ${rootPackageJsonPath}`
+    );
+  }
+  return value;
+};
+
+const loadScaffoldVersions = async (
+  rootPackageJsonPath: string
+): Promise<Record<string, string> & Readonly<Record<string, string>>> => {
+  const rootPkg = (await Bun.file(
+    rootPackageJsonPath
+  ).json()) as RootPackageJson;
+  const catalog = rootPkg.catalog ?? {};
+  const devDeps = rootPkg.devDependencies ?? {};
+
+  return {
+    bunTypes: requireValue(
+      devDeps['@types/bun'],
+      '@types/bun',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    commander: requireValue(
+      catalog['commander'],
+      'commander',
+      'catalog',
+      rootPackageJsonPath
+    ),
+    lefthook: requireValue(
+      devDeps['lefthook'],
+      'lefthook',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    oxfmt: requireValue(
+      devDeps['oxfmt'],
+      'oxfmt',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    oxlint: requireValue(
+      devDeps['oxlint'],
+      'oxlint',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    typescript: requireValue(
+      devDeps['typescript'],
+      'typescript',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    ultracite: requireValue(
+      devDeps['ultracite'],
+      'ultracite',
+      'devDependencies',
+      rootPackageJsonPath
+    ),
+    zod: requireValue(catalog['zod'], 'zod', 'catalog', rootPackageJsonPath),
+  };
+};
+
+const renderGeneratedFile = (
+  versions: Record<string, string> & Readonly<Record<string, string>>
+): string => {
+  const keys = Object.keys(versions).toSorted();
+  const lines = keys.map((key: string) => `  ${key}: '${versions[key]}',`);
+  return [
+    '// GENERATED FILE — do not edit by hand. Run `bun run scaffold-versions:sync` to regenerate.',
+    '',
+    'export const scaffoldDependencyVersions = {',
+    ...lines,
+    '} as const;',
+    '',
+  ].join('\n');
+};
+
+export const syncScaffoldVersions = async (options: {
+  check: boolean;
+  rootDir: string;
+}): Promise<SyncScaffoldVersionsResult> => {
+  const rootPackageJsonPath = resolve(options.rootDir, 'package.json');
+  const generatedPath = resolve(
+    options.rootDir,
+    'apps/trails/src/scaffold-versions.generated.ts'
+  );
+  const versions = await loadScaffoldVersions(rootPackageJsonPath);
+  const expected = renderGeneratedFile(versions);
+
+  if (options.check) {
+    const generatedFile = Bun.file(generatedPath);
+    const existing = (await generatedFile.exists())
+      ? await generatedFile.text()
+      : undefined;
+    if (existing !== expected) {
+      throw new Error(
+        `create.versions: ${generatedPath} is out of date.\n` +
+          'Run `bun run scaffold-versions:sync` to regenerate.'
+      );
+    }
+  } else {
+    await Bun.write(generatedPath, expected);
+  }
+
+  // Normally quiet because versions.ts derives both exports from one source;
+  // this trips only if future/manual drift breaks that invariant.
+  const diagnostic = diagnoseOntrailsPackagePin({
+    ontrailsPackageRange: appOntrailsPackageRange,
+    trailsPackageVersion: appTrailsPackageVersion,
+  });
+  if (diagnostic !== undefined) {
+    throw new Error(diagnostic);
+  }
+
+  return {
+    generatedPath,
+    mode: options.check ? 'check' : 'write',
+    written: !options.check,
+  };
+};

package/src/scaffold-versions.generated.ts

@@ -0,0 +1,12 @@
+// GENERATED FILE — do not edit by hand. Run `bun run scaffold-versions:sync` to regenerate.
+
+export const scaffoldDependencyVersions = {
+  bunTypes: '^1.3.11',
+  commander: '^14.0.3',
+  lefthook: '^2.1.1',
+  oxfmt: '0.47.0',
+  oxlint: '1.62.0',
+  typescript: '^5.9.3',
+  ultracite: '7.6.2',
+  zod: '^4.3.5',
+} as const;

package/src/trails/adapter-check.ts

@@ -0,0 +1,244 @@
+/**
+ * `adapter.check` trail -- Local adapter authoring readiness checks.
+ */
+
+import { adapterTargetPlacements, checkAdapters } from '@ontrails/adapter-kit';
+import type { AdapterCheckReport } from '@ontrails/adapter-kit';
+import { isPlainObject, Result, trail, ValidationError } from '@ontrails/core';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { z } from 'zod';
+
+import { resolveTrailRootDir } from './root-dir.js';
+
+const adapterCheckInputSchema = z.object({
+  rootDir: z.string().optional().describe('Root directory to scan'),
+});
+
+const adapterPlacementSchema = z.enum(adapterTargetPlacements);
+
+const adapterCheckDiagnosticSchema = z.object({
+  code: z.string().describe('Stable adapter diagnostic code'),
+  message: z.string(),
+  packageJsonPath: z.string(),
+  packageName: z.string().optional(),
+  placement: adapterPlacementSchema.optional(),
+  severity: z.enum(['error', 'warn']),
+  target: z.string().optional(),
+});
+
+const adapterCheckSubjectSchema = z.object({
+  conformanceTestPaths: z.array(z.string()).readonly(),
+  key: z.string(),
+  ownerPackage: z.string(),
+  packageJsonPath: z.string(),
+  packageName: z.string(),
+  packageRoot: z.string(),
+  placement: adapterPlacementSchema,
+  target: z.string(),
+  targetKey: z.string(),
+  testingImport: z.string().optional(),
+});
+
+const adapterTargetSchema = z.object({
+  conformance: z
+    .object({
+      adapterType: z.string(),
+      casesFactory: z.string(),
+      runner: z.string(),
+    })
+    .optional(),
+  key: z.string(),
+  ownerPackage: z.string(),
+  packageJsonPath: z.string(),
+  packageRoot: z.string(),
+  placements: z.array(adapterPlacementSchema).readonly(),
+  supportExportTarget: z.string().optional(),
+  supportImport: z.string().optional(),
+  target: z.string(),
+  testingExportTarget: z.string().optional(),
+  testingImport: z.string().optional(),
+});
+
+const adapterCheckOutputSchema = z.object({
+  diagnostics: z.array(adapterCheckDiagnosticSchema).readonly(),
+  formatted: z.string(),
+  passed: z.boolean(),
+  subjects: z.array(adapterCheckSubjectSchema).readonly(),
+  targets: z.array(adapterTargetSchema).readonly(),
+});
+
+const relativeToRoot = (rootDir: string, path: string): string => {
+  const normalized = relative(rootDir, path).replaceAll('\\', '/');
+  return normalized.length === 0 || normalized.startsWith('..')
+    ? path
+    : normalized;
+};
+
+const workspacePatternsFromManifest = (
+  manifest: Readonly<Record<string, unknown>>
+): readonly string[] => {
+  const { workspaces } = manifest;
+  if (Array.isArray(workspaces)) {
+    return workspaces.filter(
+      (pattern): pattern is string => typeof pattern === 'string'
+    );
+  }
+
+  const packages = isPlainObject(workspaces)
+    ? workspaces['packages']
+    : undefined;
+  return Array.isArray(packages)
+    ? packages.filter(
+        (pattern): pattern is string => typeof pattern === 'string'
+      )
+    : [];
+};
+
+const readWorkspaceManifest = (
+  packageJsonPath: string
+): Result<Readonly<Record<string, unknown>>, ValidationError> => {
+  try {
+    const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
+    return isPlainObject(parsed)
+      ? Result.ok(parsed)
+      : Result.err(
+          new ValidationError(
+            `adapter.check root package.json must contain a JSON object: "${packageJsonPath}"`
+          )
+        );
+  } catch (error) {
+    return Result.err(
+      new ValidationError(
+        `adapter.check could not read root package.json: "${packageJsonPath}"`,
+        error instanceof Error ? { cause: error } : undefined
+      )
+    );
+  }
+};
+
+const validateAdapterCheckRoot = (
+  rootDir: string
+): Result<void, ValidationError> => {
+  if (!existsSync(rootDir)) {
+    return Result.err(
+      new ValidationError(`adapter.check rootDir does not exist: "${rootDir}"`)
+    );
+  }
+
+  if (!statSync(rootDir).isDirectory()) {
+    return Result.err(
+      new ValidationError(
+        `adapter.check rootDir must be a directory: "${rootDir}"`
+      )
+    );
+  }
+
+  const packageJsonPath = join(rootDir, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    return Result.err(
+      new ValidationError(
+        `adapter.check rootDir must contain a package.json workspace manifest: "${packageJsonPath}"`
+      )
+    );
+  }
+
+  const manifest = readWorkspaceManifest(packageJsonPath);
+  if (manifest.isErr()) {
+    return manifest;
+  }
+
+  if (workspacePatternsFromManifest(manifest.value).length === 0) {
+    return Result.err(
+      new ValidationError(
+        `adapter.check root package.json must declare workspace packages: "${packageJsonPath}"`
+      )
+    );
+  }
+
+  return Result.ok();
+};
+
+export const formatAdapterCheckReport = (
+  report: AdapterCheckReport,
+  rootDir: string
+): string => {
+  const passed = report.diagnostics.length === 0;
+  const lines = [
+    '## Adapter Check Report',
+    '',
+    `Result: ${passed ? 'PASS' : 'FAIL'}`,
+    `Targets: ${report.targets.length}`,
+    `Adapters: ${report.subjects.length}`,
+    `Diagnostics: ${report.diagnostics.length}`,
+  ];
+
+  if (report.targets.length > 0) {
+    lines.push('', '### Targets');
+    for (const target of report.targets) {
+      lines.push(
+        `- ${target.key} (${target.placements.join(', ')}) from ${relativeToRoot(rootDir, target.packageJsonPath)}`
+      );
+    }
+  }
+
+  if (report.subjects.length > 0) {
+    lines.push('', '### Adapters');
+    for (const subject of report.subjects) {
+      const conformance =
+        subject.conformanceTestPaths.length === 0
+          ? 'no conformance tests'
+          : `${subject.conformanceTestPaths.length} conformance test(s)`;
+      lines.push(
+        `- ${subject.packageName} -> ${subject.targetKey} (${subject.placement}, ${conformance})`
+      );
+    }
+  }
+
+  if (report.diagnostics.length > 0) {
+    lines.push('', '### Diagnostics');
+    for (const diagnostic of report.diagnostics) {
+      lines.push(
+        `- ${diagnostic.severity.toUpperCase()} ${diagnostic.code} ${relativeToRoot(rootDir, diagnostic.packageJsonPath)}: ${diagnostic.message}`
+      );
+    }
+  }
+
+  return lines.join('\n');
+};
+
+export const adapterCheckTrail = trail('adapter.check', {
+  description: 'Check adapter authoring readiness',
+  examples: [
+    {
+      input: {},
+      name: 'Check adapters in the current workspace',
+    },
+  ],
+  implementation: (input, ctx) => {
+    const rootDirResult = resolveTrailRootDir(input.rootDir, ctx.cwd);
+    if (rootDirResult.isErr()) {
+      return rootDirResult;
+    }
+
+    const rootDir = rootDirResult.value;
+    const validRoot = validateAdapterCheckRoot(rootDir);
+    if (validRoot.isErr()) {
+      return validRoot;
+    }
+
+    const report = checkAdapters(rootDir);
+
+    return Result.ok({
+      diagnostics: [...report.diagnostics],
+      formatted: formatAdapterCheckReport(report, rootDir),
+      passed: report.diagnostics.length === 0,
+      subjects: [...report.subjects],
+      targets: [...report.targets],
+    });
+  },
+  input: adapterCheckInputSchema,
+  intent: 'read',
+  output: adapterCheckOutputSchema,
+  permit: 'public',
+});