@ankhorage/doctor 0.7.3 → 0.9.0

package/src/bunPolicyAnalysis.ts

@@ -0,0 +1,261 @@
+import { promises as fs } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { DoctorAnalysisResult } from './analysis.js';
+import type { DoctorDiagnostic, DoctorRuleId } from './diagnostics.js';
+
+interface BunRuntimePolicySnapshot {
+  readonly packageManager: string;
+  readonly typesRange: string;
+  readonly version: string;
+}
+
+const DEVTOOLS_POLICY_SPECIFIER = '@ankhorage/devtools/policy';
+const REPAIR_HINT = 'Run "ankh devtools sync" to repair the managed Bun state.';
+const BUN_VERSION_PATTERN = /^\s*bun-version:\s*['"]?([^'"\s#]+)['"]?\s*(?:#.*)?$/mu;
+const WORKFLOWS = [
+  {
+    relativePath: path.join('.github', 'workflows', 'ci.yml'),
+    ruleId: 'repo.workflows.ci.bun-policy',
+  },
+  {
+    relativePath: path.join('.github', 'workflows', 'release.yml'),
+    ruleId: 'repo.workflows.release.bun-policy',
+  },
+] as const satisfies readonly { readonly relativePath: string; readonly ruleId: DoctorRuleId }[];
+
+export async function applyBunRuntimePolicy(
+  result: DoctorAnalysisResult,
+): Promise<DoctorAnalysisResult> {
+  if (result.profile !== 'public-package' || !result.hasPackageJson) {
+    return result;
+  }
+
+  const policy = await loadTargetBunRuntimePolicy(result.targetPath);
+  const packageJsonPath = path.join(result.targetPath, 'package.json');
+  const packageJson = await readPackageJson(packageJsonPath);
+  if (policy === null || packageJson === null) {
+    return result;
+  }
+
+  const diagnostics = [
+    ...result.diagnostics,
+    ...analyzePackageBunPolicy(packageJson, packageJsonPath, result, policy),
+    ...(await analyzeWorkflowBunPolicy(result, policy)),
+  ];
+
+  return withDiagnostics(result, diagnostics);
+}
+
+async function loadTargetBunRuntimePolicy(
+  targetPath: string,
+): Promise<BunRuntimePolicySnapshot | null> {
+  const requireFromTarget = createRequire(path.join(targetPath, 'package.json'));
+  try {
+    const modulePath = requireFromTarget.resolve(DEVTOOLS_POLICY_SPECIFIER);
+    const importedModule = (await import(pathToFileURL(modulePath).href)) as unknown;
+    return parseBunRuntimePolicy(importedModule);
+  } catch (error) {
+    if (isUnavailablePolicyError(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function analyzePackageBunPolicy(
+  packageJson: Record<string, unknown>,
+  packageJsonPath: string,
+  result: DoctorAnalysisResult,
+  policy: BunRuntimePolicySnapshot,
+): DoctorDiagnostic[] {
+  const diagnostics: DoctorDiagnostic[] = [];
+  const { packageManager } = packageJson;
+  if (isNonEmptyString(packageManager) && packageManager.startsWith('bun@')) {
+    pushMismatch(diagnostics, {
+      actual: packageManager,
+      expected: policy.packageManager,
+      location: 'package.json#packageManager',
+      path: packageJsonPath,
+      profile: result.profile,
+      ruleId: 'package.json.package-manager.policy',
+    });
+  }
+
+  const devDependencies = isRecord(packageJson.devDependencies)
+    ? packageJson.devDependencies
+    : null;
+  const bunTypes = devDependencies?.['@types/bun'];
+  if (isNonEmptyString(bunTypes)) {
+    pushMismatch(diagnostics, {
+      actual: bunTypes,
+      expected: policy.typesRange,
+      location: 'package.json#devDependencies.@types/bun',
+      path: packageJsonPath,
+      profile: result.profile,
+      ruleId: 'package.dependencies.types-bun.policy',
+    });
+  }
+
+  return diagnostics;
+}
+
+async function analyzeWorkflowBunPolicy(
+  result: DoctorAnalysisResult,
+  policy: BunRuntimePolicySnapshot,
+): Promise<DoctorDiagnostic[]> {
+  const diagnostics = await Promise.all(
+    WORKFLOWS.map(async (workflow) => await analyzeWorkflow(result, workflow, policy)),
+  );
+  return diagnostics.flat();
+}
+
+async function analyzeWorkflow(
+  result: DoctorAnalysisResult,
+  workflow: (typeof WORKFLOWS)[number],
+  policy: BunRuntimePolicySnapshot,
+): Promise<DoctorDiagnostic[]> {
+  const workflowPath = path.join(result.targetPath, workflow.relativePath);
+  const contents = await readTextOrNull(workflowPath);
+  if (contents === null) {
+    return [createWorkflowDiagnostic(result, workflow, policy, workflowPath, 'missing-path')];
+  }
+
+  const match = BUN_VERSION_PATTERN.exec(contents);
+  const actual = match?.[1];
+  if (!isNonEmptyString(actual)) {
+    return [createWorkflowDiagnostic(result, workflow, policy, workflowPath, 'field-missing')];
+  }
+
+  const diagnostics: DoctorDiagnostic[] = [];
+  pushMismatch(diagnostics, {
+    actual,
+    expected: policy.version,
+    location: `${workflow.relativePath}#bun-version`,
+    path: workflowPath,
+    profile: result.profile,
+    ruleId: workflow.ruleId,
+  });
+  return diagnostics;
+}
+
+function createWorkflowDiagnostic(
+  result: DoctorAnalysisResult,
+  workflow: (typeof WORKFLOWS)[number],
+  policy: BunRuntimePolicySnapshot,
+  workflowPath: string,
+  code: DoctorDiagnostic['code'],
+): DoctorDiagnostic {
+  const detail =
+    code === 'missing-path'
+      ? `Managed workflow is missing: ${workflow.relativePath}.`
+      : `${workflow.relativePath} does not define bun-version.`;
+  return {
+    code,
+    message: `${detail} Expected Bun ${policy.version}. ${REPAIR_HINT}`,
+    path: workflowPath,
+    profile: result.profile,
+    ruleId: workflow.ruleId,
+    severity: 'error',
+  };
+}
+
+function pushMismatch(
+  diagnostics: DoctorDiagnostic[],
+  input: {
+    readonly actual: string;
+    readonly expected: string;
+    readonly location: string;
+    readonly path: string;
+    readonly profile: DoctorAnalysisResult['profile'];
+    readonly ruleId: DoctorRuleId;
+  },
+): void {
+  if (input.actual === input.expected) {
+    return;
+  }
+  diagnostics.push({
+    code: 'field-invalid',
+    message: `Bun policy drift at ${input.location}: expected "${input.expected}", found "${input.actual}". ${REPAIR_HINT}`,
+    path: input.path,
+    profile: input.profile,
+    ruleId: input.ruleId,
+    severity: 'error',
+  });
+}
+
+function parseBunRuntimePolicy(importedModule: unknown): BunRuntimePolicySnapshot | null {
+  if (!isRecord(importedModule) || !isRecord(importedModule.bunRuntimePolicy)) {
+    return null;
+  }
+  const { packageManager, typesRange, version } = importedModule.bunRuntimePolicy;
+  return isNonEmptyString(packageManager) &&
+    isNonEmptyString(typesRange) &&
+    isNonEmptyString(version)
+    ? { packageManager, typesRange, version }
+    : null;
+}
+
+function withDiagnostics(
+  result: DoctorAnalysisResult,
+  diagnostics: readonly DoctorDiagnostic[],
+): DoctorAnalysisResult {
+  return {
+    ...result,
+    diagnostics,
+    fixPlan: result.fixPlan === null ? null : { ...result.fixPlan, diagnostics },
+  };
+}
+
+async function readPackageJson(packageJsonPath: string): Promise<Record<string, unknown> | null> {
+  try {
+    const parsed = JSON.parse(await fs.readFile(packageJsonPath, 'utf8')) as unknown;
+    return isRecord(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+async function readTextOrNull(filePath: string): Promise<string | null> {
+  try {
+    return await fs.readFile(filePath, 'utf8');
+  } catch (error) {
+    if (isNodeError(error) && error.code === 'ENOENT') {
+      return null;
+    }
+    throw error;
+  }
+}
+
+function isUnavailablePolicyError(error: unknown): boolean {
+  if (
+    isNodeError(error) &&
+    (error.code === 'MODULE_NOT_FOUND' ||
+      error.code === 'ERR_MODULE_NOT_FOUND' ||
+      error.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+  ) {
+    return true;
+  }
+
+  const message = error instanceof Error ? error.message : String(error);
+  return (
+    message.includes(DEVTOOLS_POLICY_SPECIFIER) &&
+    (message.includes('Cannot find module') ||
+      message.includes('not exported') ||
+      message.includes('Package subpath'))
+  );
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === 'string' && value.trim() !== '';
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+  return error instanceof Error && 'code' in error;
+}

package/src/commands.ts

@@ -9,6 +9,7 @@ import {
   type DoctorDiagnostic,
 } from './diagnostics.js';
 import { DOCTOR_CAPABILITIES, DOCTOR_COMMAND_CATEGORY } from './packageMetadata.js';
+import type { DoctorReadiness } from './readiness.js';
 
 type DoctorCommandName = 'fix' | 'package' | 'repo' | 'validate';
 
@@ -289,6 +290,17 @@ function renderAnalysisReport(
     }
   }
 
+  const readiness = result.readiness ?? [];
+  lines.push('');
+  lines.push('Readiness:');
+  if (readiness.length === 0) {
+    lines.push('  none');
+  } else {
+    for (const item of readiness) {
+      lines.push(renderReadinessLine(item));
+    }
+  }
+
   if (commandName === 'fix') {
     lines.push('');
     lines.push('Planned changes:');
@@ -316,6 +328,10 @@ function renderDiagnosticLine(diagnostic: DoctorDiagnostic): string {
   return `  - ${diagnostic.severity.toUpperCase()} ${diagnostic.ruleId} (${diagnostic.code}): ${diagnostic.message}`;
 }
 
+function renderReadinessLine(item: DoctorReadiness): string {
+  return `  - ${item.target} ${item.environment} ${item.provider} ${item.transport}: ${item.status} — ${item.message}`;
+}
+
 function renderPlannedChangeLine(change: DoctorPlannedChange): string {
   return `  - ${change.ruleId} [${change.kind}]: ${change.description}`;
 }

package/src/dependencyPolicyAnalysis.ts

@@ -6,6 +6,7 @@ import {
   type DoctorAnalysisRequest,
   type DoctorAnalysisResult,
 } from './analysis.js';
+import { applyBunRuntimePolicy } from './bunPolicyAnalysis.js';
 import { analyzeDoctorTargetWithCliLayout as analyzeBaseDoctorTargetWithCliLayout } from './cliLayoutAnalysis.js';
 import type { DoctorDiagnostic } from './diagnostics.js';
 
@@ -16,15 +17,19 @@ const DEVTOOLS_REQUIRED_RULE_ID = 'package.dependencies.devtools.required';
 export async function analyzeDoctorTarget(
   request: DoctorAnalysisRequest,
 ): Promise<DoctorAnalysisResult> {
-  return applyDevtoolsDependencyPlacementPolicy(await analyzeBaseDoctorTarget(request));
+  return applyRepositoryPolicies(await analyzeBaseDoctorTarget(request));
 }
 
 export async function analyzeDoctorTargetWithCliLayout(
   request: DoctorAnalysisRequest,
 ): Promise<DoctorAnalysisResult> {
-  return applyDevtoolsDependencyPlacementPolicy(
-    await analyzeBaseDoctorTargetWithCliLayout(request),
-  );
+  return applyRepositoryPolicies(await analyzeBaseDoctorTargetWithCliLayout(request));
+}
+
+async function applyRepositoryPolicies(
+  result: DoctorAnalysisResult,
+): Promise<DoctorAnalysisResult> {
+  return applyBunRuntimePolicy(await applyDevtoolsDependencyPlacementPolicy(result));
 }
 
 async function applyDevtoolsDependencyPlacementPolicy(

package/src/diagnostics.ts

@@ -30,13 +30,18 @@ export type DoctorRuleId =
   | 'manifest.auth.flow.unauthorized-route.valid'
   | 'manifest.auth.flow.valid-shape'
   | 'manifest.auth.oauth.callback-route.valid'
+  | 'manifest.auth.oauth.callback-target.configured'
   | 'manifest.auth.oauth.provider.credentials-ref.required'
   | 'manifest.auth.oauth.provider.credentials-ref.valid'
   | 'manifest.auth.oauth.provider.duplicate'
   | 'manifest.auth.oauth.provider.inline-secret.disallowed'
   | 'manifest.auth.oauth.providers.valid'
+  | 'manifest.auth.oauth.setup.supported'
   | 'manifest.auth.oauth.valid-shape'
   | 'manifest.auth.valid-shape'
+  | 'manifest.deploy.targets.enabled'
+  | 'manifest.deploy.targets.legacy-web'
+  | 'manifest.deploy.valid-shape'
   | 'manifest.infra.valid-shape'
   | 'manifest.json.readable'
   | 'manifest.json.valid'
@@ -57,6 +62,7 @@ export type DoctorRuleId =
   | 'package.dependencies.changesets.required'
   | 'package.dependencies.devtools.required'
   | 'package.dependencies.paradox.required'
+  | 'package.dependencies.types-bun.policy'
   | 'package.dependencies.types-bun.required'
   | 'package.dependencies.types-node.required'
   | 'package.dependencies.typescript.required'
@@ -71,6 +77,7 @@ export type DoctorRuleId =
   | 'package.json.license.required'
   | 'package.json.name.required'
   | 'package.json.package-manager.bun'
+  | 'package.json.package-manager.policy'
   | 'package.json.package-manager.required'
   | 'package.json.private.public-package-disallowed'
   | 'package.json.publish-config.public'
@@ -99,6 +106,8 @@ export type DoctorRuleId =
   | 'repo.changeset.required'
   | 'repo.license.required'
   | 'repo.readme.required'
+  | 'repo.workflows.ci.bun-policy'
+  | 'repo.workflows.release.bun-policy'
   | 'repo.workflows.required'
   | 'studio.dependencies.dnd.required'
   | 'studio.dependencies.runtime.required'

package/src/index.ts

@@ -7,6 +7,8 @@ export type {
   DoctorTargetCheck,
   DoctorTargetMode,
 } from './analysis.js';
+export { analyzeAuthReadiness, type DoctorAuthReadinessAnalysis } from './authReadinessAnalysis.js';
+export { analyzeAuthReadinessFile } from './authReadinessFileAnalysis.js';
 export {
   createDoctorRuntimeProvider,
   type CreateDoctorRuntimeProviderOptions,
@@ -37,3 +39,4 @@ export {
   DOCTOR_PACKAGE_NAME,
   DOCTOR_PACKAGE_VERSION,
 } from './packageMetadata.js';
+export type { DoctorReadiness, DoctorReadinessStatus } from './readiness.js';

package/src/manifestAnalysis.ts

@@ -10,6 +10,7 @@ import type {
   DoctorFixPlan,
   DoctorPlannedChange,
 } from './analysis.js';
+import { analyzeAuthReadinessFile } from './authReadinessFileAnalysis.js';
 import type {
   DoctorDiagnostic,
   DoctorDiagnosticCode,
@@ -52,7 +53,8 @@ export async function analyzeAppManifestTarget(
     return null;
   }
 
-  const diagnostics = await analyzeAppManifestFile(targetPath);
+  const authReadiness = await analyzeAuthReadinessFile(targetPath);
+  const diagnostics = [...(await analyzeAppManifestFile(targetPath)), ...authReadiness.diagnostics];
   const plannedChanges: DoctorPlannedChange[] = [];
   const fixPlan: DoctorFixPlan | null =
     request.mode === 'fix'
@@ -71,6 +73,7 @@ export async function analyzeAppManifestTarget(
     hasPackageJson: false,
     plannedChanges,
     profile: MANIFEST_PROFILE,
+    readiness: authReadiness.readiness,
     repoMarkers: [],
     targetPath,
   };

package/src/readiness.ts

@@ -0,0 +1,14 @@
+import type { AuthOAuthProviderId, AuthOAuthTransportId } from '@ankhorage/contracts/auth';
+import type { AppDeployEnvironmentId, AppDeployTargetId } from '@ankhorage/contracts/deploy';
+
+export type DoctorReadinessStatus = 'missing' | 'ready' | 'unsupported';
+
+export interface DoctorReadiness {
+  readonly category: 'auth-oauth';
+  readonly environment: AppDeployEnvironmentId;
+  readonly message: string;
+  readonly provider: AuthOAuthProviderId;
+  readonly status: DoctorReadinessStatus;
+  readonly target: AppDeployTargetId;
+  readonly transport: AuthOAuthTransportId;
+}