@webstir-io/webstir 0.1.1 → 0.1.2

package/src/doctor.ts

@@ -0,0 +1,164 @@
+import type { BackendInspectResult } from './backend-inspect.ts';
+import type { WorkspaceDescriptor } from './types.ts';
+
+import { runBackendInspect } from './backend-inspect.ts';
+import { runRepair } from './repair.ts';
+import { readWorkspaceDescriptor } from './workspace.ts';
+
+export interface RunDoctorOptions {
+  readonly workspaceRoot: string;
+  readonly env?: Record<string, string | undefined>;
+}
+
+export interface DoctorCheck {
+  readonly id: 'scaffold' | 'backend-inspect';
+  readonly status: 'pass' | 'fail' | 'skip';
+  readonly summary: string;
+  readonly detail?: string;
+  readonly changes?: readonly string[];
+}
+
+export interface DoctorIssue {
+  readonly code: 'scaffold_drift' | 'backend_inspect_failed';
+  readonly severity: 'error';
+  readonly message: string;
+  readonly repairable: boolean;
+  readonly changes?: readonly string[];
+}
+
+export interface DoctorRepairPlan {
+  readonly command: 'repair';
+  readonly args: readonly string[];
+  readonly changes: readonly string[];
+}
+
+export interface DoctorBackendSummary {
+  readonly buildRoot: string;
+  readonly module: string;
+  readonly routes: number;
+  readonly jobs: number;
+  readonly data: DoctorBackendDataSummary;
+}
+
+export interface DoctorBackendDataSummary {
+  readonly migrations: DoctorBackendMigrationSummary;
+}
+
+export interface DoctorBackendMigrationSummary {
+  readonly runnerPresent: boolean;
+  readonly migrationsDirectoryPresent: boolean;
+  readonly migrationFilesCount: number;
+  readonly exampleMigrationPresent: boolean;
+  readonly tableEnvKey: string;
+  readonly configuredTable: string;
+}
+
+export interface DoctorResult {
+  readonly workspace: WorkspaceDescriptor;
+  readonly healthy: boolean;
+  readonly checks: readonly DoctorCheck[];
+  readonly issues: readonly DoctorIssue[];
+  readonly repair: DoctorRepairPlan;
+  readonly backend?: DoctorBackendSummary;
+}
+
+export async function runDoctor(options: RunDoctorOptions): Promise<DoctorResult> {
+  const workspace = await readWorkspaceDescriptor(options.workspaceRoot);
+  const checks: DoctorCheck[] = [];
+  const issues: DoctorIssue[] = [];
+
+  const repairResult = await runRepair({
+    workspaceRoot: workspace.root,
+    rawArgs: ['--dry-run'],
+  });
+
+  if (repairResult.changes.length > 0) {
+    checks.push({
+      id: 'scaffold',
+      status: 'fail',
+      summary: `${repairResult.changes.length} scaffold-managed change(s) required.`,
+      changes: repairResult.changes,
+    });
+    issues.push({
+      code: 'scaffold_drift',
+      severity: 'error',
+      message: 'Scaffold-managed files or wiring have drifted from the expected workspace shape.',
+      repairable: true,
+      changes: repairResult.changes,
+    });
+  } else {
+    checks.push({
+      id: 'scaffold',
+      status: 'pass',
+      summary: 'Scaffold-managed files and wiring match the expected workspace shape.',
+    });
+  }
+
+  let backend: DoctorBackendSummary | undefined;
+  if (workspace.mode === 'api' || workspace.mode === 'full') {
+    try {
+      const inspectResult = await runBackendInspect({
+        workspaceRoot: workspace.root,
+        env: options.env,
+      });
+      backend = summarizeBackendInspect(inspectResult);
+      checks.push({
+        id: 'backend-inspect',
+        status: 'pass',
+        summary: `${backend.routes} route(s), ${backend.jobs} job(s), module ${backend.module}.`,
+      });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      checks.push({
+        id: 'backend-inspect',
+        status: 'fail',
+        summary: 'Backend inspect failed.',
+        detail: message,
+      });
+      issues.push({
+        code: 'backend_inspect_failed',
+        severity: 'error',
+        message: `Backend inspect failed: ${message}`,
+        repairable: false,
+      });
+    }
+  } else {
+    checks.push({
+      id: 'backend-inspect',
+      status: 'skip',
+      summary: `Skipped for ${workspace.mode} workspaces.`,
+    });
+  }
+
+  return {
+    workspace,
+    healthy: issues.length === 0,
+    checks,
+    issues,
+    repair: {
+      command: 'repair',
+      args: ['--workspace', workspace.root],
+      changes: repairResult.changes,
+    },
+    ...(backend ? { backend } : {}),
+  };
+}
+
+function summarizeBackendInspect(result: BackendInspectResult): DoctorBackendSummary {
+  return {
+    buildRoot: result.buildRoot,
+    module: `${result.manifest.name}@${result.manifest.version}`,
+    routes: result.manifest.routes?.length ?? 0,
+    jobs: result.manifest.jobs?.length ?? 0,
+    data: {
+      migrations: {
+        runnerPresent: result.data.migrations.runnerPresent,
+        migrationsDirectoryPresent: result.data.migrations.migrationsDirectoryPresent,
+        migrationFilesCount: result.data.migrations.migrationFilesCount,
+        exampleMigrationPresent: result.data.migrations.exampleMigrationPresent,
+        tableEnvKey: result.data.migrations.tableEnvKey,
+        configuredTable: result.data.migrations.configuredTable,
+      },
+    },
+  };
+}

package/src/enable-assets.ts

@@ -33,6 +33,23 @@ export function getClientNavAssets(): readonly StaticFeatureAsset[] {
       targetPath: path.join('src', 'frontend', 'app', 'scripts', 'features', 'client-nav.ts'),
       overwrite: true,
     },
+    {
+      sourcePath: path.join(featuresRoot, 'client_nav', 'form_enhancement.ts'),
+      targetPath: path.join('src', 'frontend', 'app', 'scripts', 'features', 'form-enhancement.ts'),
+      overwrite: true,
+    },
+    {
+      sourcePath: path.join(featuresRoot, 'client_nav', 'document_navigation.ts'),
+      targetPath: path.join(
+        'src',
+        'frontend',
+        'app',
+        'scripts',
+        'features',
+        'document-navigation.ts',
+      ),
+      overwrite: true,
+    },
   ];
 }
 
@@ -185,7 +202,7 @@ jobs:
       - name: Setup Bun
         uses: oven-sh/setup-bun@v2
         with:
-          bun-version: 1.3.5
+          bun-version: 1.3.11
 
       - name: Install dependencies
         run: bun install --frozen-lockfile

package/src/enable.ts

@@ -1,6 +1,7 @@
 import path from 'node:path';
-import { chmod, copyFile, mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { chmod, mkdir, stat } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
 import { getBackendScaffoldAssets } from '@webstir-io/webstir-backend';
 import {
@@ -42,7 +43,7 @@ export async function runEnable(options: RunEnableOptions): Promise<EnableResult
   const [featureToken, ...rest] = options.args;
   if (!featureToken) {
     throw new Error(
-      'Missing enable feature. Usage: webstir enable <scripts <page>|spa|client-nav|search|content-nav|backend|github-pages|gh-deploy> --workspace <path>.'
+      'Missing enable feature. Usage: webstir enable <scripts <page>|spa|client-nav|search|content-nav|backend|github-pages|gh-deploy> --workspace <path>.',
     );
   }
 
@@ -80,10 +81,22 @@ export async function runEnable(options: RunEnableOptions): Promise<EnableResult
       break;
     case 'github-pages':
     case 'gh-pages':
-      await enableGithubPages(workspace.root, path.basename(workspace.root), rest[0], false, changes);
+      await enableGithubPages(
+        workspace.root,
+        path.basename(workspace.root),
+        rest[0],
+        false,
+        changes,
+      );
       break;
     case 'gh-deploy':
-      await enableGithubPages(workspace.root, path.basename(workspace.root), rest[0], true, changes);
+      await enableGithubPages(
+        workspace.root,
+        path.basename(workspace.root),
+        rest[0],
+        true,
+        changes,
+      );
       break;
   }
 
@@ -109,12 +122,16 @@ function parseEnableFeature(value: string): EnableFeature {
       return normalized;
     default:
       throw new Error(
-        `Unknown feature "${value}". Expected scripts, spa, client-nav, search, content-nav, backend, github-pages, or gh-deploy.`
+        `Unknown feature "${value}". Expected scripts, spa, client-nav, search, content-nav, backend, github-pages, or gh-deploy.`,
       );
   }
 }
 
-async function enableScripts(workspaceRoot: string, args: readonly string[], changes: string[]): Promise<void> {
+async function enableScripts(
+  workspaceRoot: string,
+  args: readonly string[],
+  changes: string[],
+): Promise<void> {
   const pageName = args[0];
   if (!pageName) {
     throw new Error('Usage: webstir enable scripts <page> --workspace <path>.');
@@ -137,7 +154,7 @@ async function enableScripts(workspaceRoot: string, args: readonly string[], cha
 async function copyStaticAssets(
   workspaceRoot: string,
   assets: readonly StaticFeatureAsset[],
-  changes: string[]
+  changes: string[],
 ): Promise<void> {
   for (const asset of assets) {
     const targetPath = path.join(workspaceRoot, asset.targetPath);
@@ -151,7 +168,7 @@ async function copyStaticAssets(
       continue;
     }
 
-    await copyFile(asset.sourcePath, targetPath);
+    await Bun.write(targetPath, Bun.file(asset.sourcePath));
     if (asset.executable) {
       await chmod(targetPath, 0o755);
     }
@@ -166,12 +183,16 @@ async function enableBackend(workspaceRoot: string, changes: string[]): Promise<
     for (const asset of assets) {
       const targetPath = path.join(workspaceRoot, asset.targetPath);
       await mkdir(path.dirname(targetPath), { recursive: true });
-      await copyFile(asset.sourcePath, targetPath);
+      await Bun.write(targetPath, Bun.file(asset.sourcePath));
       changes.push(relativeWorkspacePath(workspaceRoot, targetPath));
     }
   }
 
-  await updatePackageJson(workspaceRoot, { enableBackend: true, mode: 'full' }, changes);
+  await updatePackageJson(
+    workspaceRoot,
+    { enableBackend: true, ensureBackendDependency: true, mode: 'full' },
+    changes,
+  );
   await ensureTsReference(workspaceRoot, 'src/backend', changes);
 }
 
@@ -180,7 +201,7 @@ async function enableGithubPages(
   workspaceName: string,
   basePathArg: string | undefined,
   includeWorkflow: boolean,
-  changes: string[]
+  changes: string[],
 ): Promise<void> {
   const resolvedBasePath = resolveGithubPagesBasePath(basePathArg, workspaceName);
   const deployScriptPath = path.join(workspaceRoot, 'utils', 'deploy-gh-pages.sh');
@@ -196,40 +217,44 @@ async function enableGithubPages(
   }
 
   await updateFrontendConfig(workspaceRoot, resolvedBasePath, changes);
-  await updatePackageJson(workspaceRoot, { enableGithubPages: true, ensureDeployScript: true }, changes);
+  await updatePackageJson(
+    workspaceRoot,
+    { enableGithubPages: true, ensureDeployScript: true },
+    changes,
+  );
 }
 
 async function ensureAppScriptImport(
   workspaceRoot: string,
   importPath: string,
-  changes: string[]
+  changes: string[],
 ): Promise<void> {
   const appTsPath = path.join(workspaceRoot, 'src', 'frontend', 'app', 'app.ts');
   if (!existsSync(appTsPath)) {
     return;
   }
 
-  const source = await readFile(appTsPath, 'utf8');
+  const source = await readTextFile(appTsPath);
   const updated = ensureSideEffectImport(source, importPath);
   if (updated === source) {
     return;
   }
 
-  await writeFile(appTsPath, updated, 'utf8');
+  await Bun.write(appTsPath, updated);
   changes.push(relativeWorkspacePath(workspaceRoot, appTsPath));
 }
 
 async function ensureAppCssImport(
   workspaceRoot: string,
   importPath: string,
-  changes: string[]
+  changes: string[],
 ): Promise<void> {
   const appCssPath = path.join(workspaceRoot, 'src', 'frontend', 'app', 'app.css');
   if (!existsSync(appCssPath)) {
     return;
   }
 
-  const source = await readFile(appCssPath, 'utf8');
+  const source = await readTextFile(appCssPath);
   let updated = source;
   updated = ensureLayerIncludes(updated, 'features');
   updated = ensureImportIncludes(updated, importPath, './styles/components/buttons.css');
@@ -237,7 +262,7 @@ async function ensureAppCssImport(
     return;
   }
 
-  await writeFile(appCssPath, updated, 'utf8');
+  await Bun.write(appCssPath, updated);
   changes.push(relativeWorkspacePath(workspaceRoot, appCssPath));
 }
 
@@ -247,20 +272,20 @@ async function ensureHtmlSearchMode(workspaceRoot: string, changes: string[]): P
     return;
   }
 
-  const source = await readFile(appHtmlPath, 'utf8');
+  const source = await readTextFile(appHtmlPath);
   if (source.includes('data-webstir-search-styles=')) {
     return;
   }
 
   const updated = source.replace(
     /<html\b(?![^>]*\bdata-webstir-search-styles=)/i,
-    '<html data-webstir-search-styles="css"'
+    '<html data-webstir-search-styles="css"',
   );
   if (updated === source) {
     return;
   }
 
-  await writeFile(appHtmlPath, updated, 'utf8');
+  await Bun.write(appHtmlPath, updated);
   changes.push(relativeWorkspacePath(workspaceRoot, appHtmlPath));
 }
 
@@ -274,12 +299,13 @@ async function updatePackageJson(
     readonly enableBackend?: boolean;
     readonly enableGithubPages?: boolean;
     readonly mode?: string;
+    readonly ensureBackendDependency?: boolean;
     readonly ensureDeployScript?: boolean;
   },
-  changes: string[]
+  changes: string[],
 ): Promise<void> {
   const packageJsonPath = path.join(workspaceRoot, 'package.json');
-  const source = await readFile(packageJsonPath, 'utf8');
+  const source = await readTextFile(packageJsonPath);
   const root = JSON.parse(source) as Record<string, unknown>;
   const webstir = asRecord(root.webstir);
   const enable = asRecord(webstir.enable);
@@ -309,6 +335,10 @@ async function updatePackageJson(
   webstir.enable = enable;
   root.webstir = webstir;
 
+  if (options.ensureBackendDependency) {
+    await ensureBackendScaffoldDependencies(root);
+  }
+
   if (options.ensureDeployScript) {
     const scripts = asRecord(root.scripts);
     if (typeof scripts.deploy !== 'string') {
@@ -322,17 +352,61 @@ async function updatePackageJson(
     return;
   }
 
-  await writeFile(packageJsonPath, updated, 'utf8');
+  await Bun.write(packageJsonPath, updated);
   changes.push(relativeWorkspacePath(workspaceRoot, packageJsonPath));
 }
 
-async function updateFrontendConfig(workspaceRoot: string, basePath: string, changes: string[]): Promise<void> {
+async function ensureBackendScaffoldDependencies(root: Record<string, unknown>): Promise<void> {
+  const dependencies = asRecord(root.dependencies);
+  if (typeof dependencies['@webstir-io/webstir-backend'] !== 'string') {
+    dependencies['@webstir-io/webstir-backend'] = await resolveBackendDependencySpec(root);
+  }
+  if (typeof dependencies.pino !== 'string') {
+    dependencies.pino = '^10.1.0';
+  }
+  root.dependencies = dependencies;
+
+  const devDependencies = asRecord(root.devDependencies);
+  if (typeof devDependencies['@types/bun'] !== 'string') {
+    devDependencies['@types/bun'] = '^1.3.11';
+  }
+  root.devDependencies = devDependencies;
+}
+
+async function resolveBackendDependencySpec(root: Record<string, unknown>): Promise<string> {
+  const dependencies = asRecord(root.dependencies);
+  const frontendSpec = dependencies['@webstir-io/webstir-frontend'];
+  if (typeof frontendSpec === 'string' && frontendSpec.startsWith('workspace:')) {
+    return 'workspace:*';
+  }
+
+  return await readInstalledPackageVersion('@webstir-io/webstir-backend');
+}
+
+async function readInstalledPackageVersion(packageName: string): Promise<string> {
+  const packageJsonUrl = import.meta.resolve(`${packageName}/package.json`);
+  const packageJsonPath = fileURLToPath(packageJsonUrl);
+  const packageJson = JSON.parse(await readTextFile(packageJsonPath)) as {
+    readonly version?: string;
+  };
+  if (!packageJson.version) {
+    throw new Error(`Missing version in ${packageJsonPath}`);
+  }
+
+  return `^${packageJson.version}`;
+}
+
+async function updateFrontendConfig(
+  workspaceRoot: string,
+  basePath: string,
+  changes: string[],
+): Promise<void> {
   const configPath = path.join(workspaceRoot, 'src', 'frontend', 'frontend.config.json');
   let root: Record<string, unknown> = {};
 
   if (existsSync(configPath)) {
     try {
-      root = JSON.parse(await readFile(configPath, 'utf8')) as Record<string, unknown>;
+      root = JSON.parse(await readTextFile(configPath)) as Record<string, unknown>;
     } catch {
       root = {};
     }
@@ -343,7 +417,7 @@ async function updateFrontendConfig(workspaceRoot: string, basePath: string, cha
   root.publish = publish;
 
   const updated = `${JSON.stringify(root, null, 2)}\n`;
-  const current = existsSync(configPath) ? await readFile(configPath, 'utf8') : null;
+  const current = existsSync(configPath) ? await readTextFile(configPath) : null;
   if (current === updated) {
     return;
   }
@@ -352,19 +426,24 @@ async function updateFrontendConfig(workspaceRoot: string, basePath: string, cha
   changes.push(relativeWorkspacePath(workspaceRoot, configPath));
 }
 
-async function ensureTsReference(workspaceRoot: string, referencePath: string, changes: string[]): Promise<void> {
+async function ensureTsReference(
+  workspaceRoot: string,
+  referencePath: string,
+  changes: string[],
+): Promise<void> {
   const tsconfigPath = path.join(workspaceRoot, 'base.tsconfig.json');
   if (!existsSync(tsconfigPath)) {
     return;
   }
 
-  const source = await readFile(tsconfigPath, 'utf8');
+  const source = await readTextFile(tsconfigPath);
   const root = JSON.parse(source) as Record<string, unknown>;
   const references = Array.isArray(root.references) ? [...root.references] : [];
-  const exists = references.some((entry) =>
-    typeof entry === 'object'
-    && entry !== null
-    && (entry as Record<string, unknown>).path === referencePath
+  const exists = references.some(
+    (entry) =>
+      typeof entry === 'object' &&
+      entry !== null &&
+      (entry as Record<string, unknown>).path === referencePath,
   );
   if (!exists) {
     references.push({ path: referencePath });
@@ -376,11 +455,14 @@ async function ensureTsReference(workspaceRoot: string, referencePath: string, c
     return;
   }
 
-  await writeFile(tsconfigPath, updated, 'utf8');
+  await Bun.write(tsconfigPath, updated);
   changes.push(relativeWorkspacePath(workspaceRoot, tsconfigPath));
 }
 
-function resolveGithubPagesBasePath(basePathArg: string | undefined, workspaceName: string): string {
+function resolveGithubPagesBasePath(
+  basePathArg: string | undefined,
+  workspaceName: string,
+): string {
   const candidate = (basePathArg ?? workspaceName).trim();
   if (!candidate || candidate === '/') {
     return '/';
@@ -409,7 +491,10 @@ function ensureLayerIncludes(css: string, layerName: string): string {
     return css;
   }
 
-  const layers = match[1].split(',').map((layer) => layer.trim()).filter(Boolean);
+  const layers = match[1]
+    .split(',')
+    .map((layer) => layer.trim())
+    .filter(Boolean);
   if (layers.includes(layerName)) {
     return css;
   }
@@ -417,13 +502,18 @@ function ensureLayerIncludes(css: string, layerName: string): string {
   const updated = [...layers];
   const utilitiesIndex = updated.indexOf('utilities');
   const overridesIndex = updated.indexOf('overrides');
-  const insertIndex = utilitiesIndex >= 0 ? utilitiesIndex : overridesIndex >= 0 ? overridesIndex : updated.length;
+  const insertIndex =
+    utilitiesIndex >= 0 ? utilitiesIndex : overridesIndex >= 0 ? overridesIndex : updated.length;
   updated.splice(insertIndex, 0, layerName);
   const replacement = `@layer ${updated.join(', ')};`;
   return `${css.slice(0, match.index)}${replacement}${css.slice(match.index + match[0].length)}`;
 }
 
-function ensureImportIncludes(css: string, importPath: string, insertAfterImportPath: string): string {
+function ensureImportIncludes(
+  css: string,
+  importPath: string,
+  insertAfterImportPath: string,
+): string {
   if (css.includes(`@import "${importPath}"`) || css.includes(`@import '${importPath}'`)) {
     return css;
   }
@@ -431,10 +521,8 @@ function ensureImportIncludes(css: string, importPath: string, insertAfterImport
   const doubleNeedle = `@import "${insertAfterImportPath}"`;
   const singleNeedle = `@import '${insertAfterImportPath}'`;
   let insertAfterIndex = css.indexOf(doubleNeedle);
-  let needle = doubleNeedle;
   if (insertAfterIndex < 0) {
     insertAfterIndex = css.indexOf(singleNeedle);
-    needle = singleNeedle;
   }
 
   if (insertAfterIndex >= 0) {
@@ -456,12 +544,16 @@ function ensureImportIncludes(css: string, importPath: string, insertAfterImport
 
 async function writeTextFile(filePath: string, contents: string, mode?: number): Promise<void> {
   await mkdir(path.dirname(filePath), { recursive: true });
-  await writeFile(filePath, contents, 'utf8');
+  await Bun.write(filePath, contents);
   if (mode !== undefined) {
     await chmod(filePath, mode);
   }
 }
 
+async function readTextFile(filePath: string): Promise<string> {
+  return await Bun.file(filePath).text();
+}
+
 function asRecord(value: unknown): Record<string, unknown> {
   return value && typeof value === 'object' && !Array.isArray(value)
     ? { ...(value as Record<string, unknown>) }

package/src/execute.ts

@@ -19,7 +19,7 @@ export interface RunCommandOptions {
 
 export async function runCommand(
   mode: CommandMode,
-  options: RunCommandOptions
+  options: RunCommandOptions,
 ): Promise<CommandExecutionResult> {
   const workspace = await readWorkspaceDescriptor(options.workspaceRoot);
   const providerLoader = options.loadProvider ?? loadProvider;
@@ -37,6 +37,7 @@ export async function runCommand(
       env: createWorkspaceRuntimeEnv(workspace.root, mode, options.env),
       incremental: false,
     });
+    assertNoFatalDiagnostics(kind, mode, result);
 
     targets.push({
       kind,
@@ -57,25 +58,26 @@ async function prepareCommandTarget(
   workspaceRoot: string,
   kind: BuildTargetKind,
   mode: CommandMode,
-  env?: Record<string, string | undefined>
+  env?: Record<string, string | undefined>,
 ): Promise<void> {
   if (kind !== 'frontend' || mode !== 'publish') {
     return;
   }
 
   // Frontend publish consumes build/frontend artifacts while generating dist output.
-  await provider.build({
+  const result = await provider.build({
     workspaceRoot,
     env: createWorkspaceRuntimeEnv(workspaceRoot, 'build', env),
     incremental: false,
   });
+  assertNoFatalDiagnostics(kind, 'prebuild', result);
 }
 
 function resolveOutputRoot(
   workspaceRoot: string,
   kind: BuildTargetKind,
   mode: CommandMode,
-  buildRoot: string
+  buildRoot: string,
 ): string {
   if (kind === 'frontend' && mode === 'publish') {
     return path.join(workspaceRoot, 'dist', 'frontend');
@@ -83,3 +85,25 @@ function resolveOutputRoot(
 
   return buildRoot;
 }
+
+function assertNoFatalDiagnostics(
+  kind: BuildTargetKind,
+  phase: CommandMode | 'prebuild',
+  result: CommandExecutionResult['targets'][number]['result'],
+): void {
+  const errors = result.manifest.diagnostics.filter(
+    (diagnostic) => diagnostic.severity === 'error',
+  );
+  if (errors.length === 0) {
+    return;
+  }
+
+  const summary = errors
+    .slice(0, 3)
+    .map((diagnostic) => diagnostic.message)
+    .join(' | ');
+  const extra = errors.length > 3 ? ` (+${errors.length - 3} more)` : '';
+  throw new Error(
+    `${kind} ${phase} reported ${errors.length} error diagnostic(s): ${summary}${extra}`,
+  );
+}