@ankhorage/doctor 0.11.2 → 0.11.3

package/src/bunPolicyAnalysis.ts

@@ -1,31 +1,21 @@
 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';
+import { REPOSITORY_POLICY } from '@ankhorage/policy/repository';
 
-interface BunRuntimePolicySnapshot {
-  readonly packageManager: string;
-  readonly typesRange: string;
-  readonly version: string;
-}
+import type { DoctorAnalysisResult } from './analysis.js';
+import type { DoctorDiagnostic } from './diagnostics.js';
 
-const DEVTOOLS_POLICY_SPECIFIER = '@ankhorage/devtools/policy';
+const BUN_POLICY = REPOSITORY_POLICY.runtime.bun;
 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 }[];
 
+type RepositoryPolicyRule = (typeof REPOSITORY_POLICY.rules)[keyof typeof REPOSITORY_POLICY.rules];
+type WorkflowTarget = (typeof BUN_POLICY.workflowTargets)[number];
+
+/***
+ * Applies canonical repository Bun-policy diagnostics to a Doctor analysis result.
+ */
 export async function applyBunRuntimePolicy(
   result: DoctorAnalysisResult,
 ): Promise<DoctorAnalysisResult> {
@@ -33,54 +23,37 @@ export async function applyBunRuntimePolicy(
     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;
-  }
+  if (packageJson === null) return result;
 
   const diagnostics = [
     ...result.diagnostics,
-    ...analyzePackageBunPolicy(packageJson, packageJsonPath, result, policy),
-    ...(await analyzeWorkflowBunPolicy(result, policy)),
+    ...analyzePackageBunPolicy(packageJson, packageJsonPath, result),
+    ...(await analyzeWorkflowBunPolicy(result)),
   ];
 
   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;
-  }
-}
-
+/***
+ * Reports package-manifest drift from the canonical Bun runtime contract.
+ */
 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,
+      expected: BUN_POLICY.packageManager,
       location: 'package.json#packageManager',
       path: packageJsonPath,
       profile: result.profile,
-      ruleId: 'package.json.package-manager.policy',
+      rule: REPOSITORY_POLICY.rules.packageManager,
     });
   }
 
@@ -91,77 +64,86 @@ function analyzePackageBunPolicy(
   if (isNonEmptyString(bunTypes)) {
     pushMismatch(diagnostics, {
       actual: bunTypes,
-      expected: policy.typesRange,
+      expected: BUN_POLICY.typesRange,
       location: 'package.json#devDependencies.@types/bun',
       path: packageJsonPath,
       profile: result.profile,
-      ruleId: 'package.dependencies.types-bun.policy',
+      rule: REPOSITORY_POLICY.rules.bunTypes,
     });
   }
 
   return diagnostics;
 }
 
-async function analyzeWorkflowBunPolicy(
-  result: DoctorAnalysisResult,
-  policy: BunRuntimePolicySnapshot,
-): Promise<DoctorDiagnostic[]> {
+/***
+ * Reports managed workflow drift from the canonical Bun setup version.
+ */
+async function analyzeWorkflowBunPolicy(result: DoctorAnalysisResult): Promise<DoctorDiagnostic[]> {
   const diagnostics = await Promise.all(
-    WORKFLOWS.map(async (workflow) => await analyzeWorkflow(result, workflow, policy)),
+    BUN_POLICY.workflowTargets.map(async (workflow) => await analyzeWorkflow(result, workflow)),
   );
   return diagnostics.flat();
 }
 
+/***
+ * Checks one managed workflow for the canonical Bun setup version.
+ */
 async function analyzeWorkflow(
   result: DoctorAnalysisResult,
-  workflow: (typeof WORKFLOWS)[number],
-  policy: BunRuntimePolicySnapshot,
+  workflow: WorkflowTarget,
 ): Promise<DoctorDiagnostic[]> {
-  const workflowPath = path.join(result.targetPath, workflow.relativePath);
+  const workflowPath = path.join(result.targetPath, workflow.path);
   const contents = await readTextOrNull(workflowPath);
   if (contents === null) {
-    return [createWorkflowDiagnostic(result, workflow, policy, workflowPath, 'missing-path')];
+    return [createWorkflowDiagnostic(result, workflow, 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')];
+    return [createWorkflowDiagnostic(result, workflow, workflowPath, 'field-missing')];
   }
 
   const diagnostics: DoctorDiagnostic[] = [];
   pushMismatch(diagnostics, {
     actual,
-    expected: policy.version,
-    location: `${workflow.relativePath}#bun-version`,
+    expected: BUN_POLICY.version,
+    location: `${workflow.path}#bun-version`,
     path: workflowPath,
     profile: result.profile,
-    ruleId: workflow.ruleId,
+    rule: getRepositoryRule(workflow.ruleId),
   });
   return diagnostics;
 }
 
+/***
+ * Creates a missing or malformed managed-workflow diagnostic from central rule metadata.
+ */
 function createWorkflowDiagnostic(
   result: DoctorAnalysisResult,
-  workflow: (typeof WORKFLOWS)[number],
-  policy: BunRuntimePolicySnapshot,
+  workflow: WorkflowTarget,
   workflowPath: string,
   code: DoctorDiagnostic['code'],
 ): DoctorDiagnostic {
   const detail =
     code === 'missing-path'
-      ? `Managed workflow is missing: ${workflow.relativePath}.`
-      : `${workflow.relativePath} does not define bun-version.`;
+      ? `Managed workflow is missing: ${workflow.path}.`
+      : `${workflow.path} does not define bun-version.`;
+  const rule = getRepositoryRule(workflow.ruleId);
+
   return {
     code,
-    message: `${detail} Expected Bun ${policy.version}. ${REPAIR_HINT}`,
+    message: `${detail} Expected Bun ${BUN_POLICY.version}. ${REPAIR_HINT}`,
     path: workflowPath,
     profile: result.profile,
-    ruleId: workflow.ruleId,
-    severity: 'error',
+    ruleId: rule.id,
+    severity: rule.severity,
   };
 }
 
+/***
+ * Adds one value-mismatch diagnostic using the owning Policy rule metadata.
+ */
 function pushMismatch(
   diagnostics: DoctorDiagnostic[],
   input: {
@@ -170,34 +152,35 @@ function pushMismatch(
     readonly location: string;
     readonly path: string;
     readonly profile: DoctorAnalysisResult['profile'];
-    readonly ruleId: DoctorRuleId;
+    readonly rule: RepositoryPolicyRule;
   },
 ): void {
-  if (input.actual === input.expected) {
-    return;
-  }
+  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',
+    ruleId: input.rule.id,
+    severity: input.rule.severity,
   });
 }
 
-function parseBunRuntimePolicy(importedModule: unknown): BunRuntimePolicySnapshot | null {
-  if (!isRecord(importedModule) || !isRecord(importedModule.bunRuntimePolicy)) {
-    return null;
+/***
+ * Resolves one stable repository rule by its Policy-owned id.
+ */
+function getRepositoryRule(ruleId: string): RepositoryPolicyRule {
+  const rule = Object.values(REPOSITORY_POLICY.rules).find((entry) => entry.id === ruleId);
+  if (rule === undefined) {
+    throw new Error(`Unknown repository policy rule: ${ruleId}`);
   }
-  const { packageManager, typesRange, version } = importedModule.bunRuntimePolicy;
-  return isNonEmptyString(packageManager) &&
-    isNonEmptyString(typesRange) &&
-    isNonEmptyString(version)
-    ? { packageManager, typesRange, version }
-    : null;
+  return rule;
 }
 
+/***
+ * Copies updated diagnostics into the analysis result and optional fix plan.
+ */
 function withDiagnostics(
   result: DoctorAnalysisResult,
   diagnostics: readonly DoctorDiagnostic[],
@@ -209,6 +192,9 @@ function withDiagnostics(
   };
 }
 
+/***
+ * Reads a package manifest when it contains a JSON object.
+ */
 async function readPackageJson(packageJsonPath: string): Promise<Record<string, unknown> | null> {
   try {
     const parsed = JSON.parse(await fs.readFile(packageJsonPath, 'utf8')) as unknown;
@@ -218,44 +204,35 @@ async function readPackageJson(packageJsonPath: string): Promise<Record<string,
   }
 }
 
+/***
+ * Reads a UTF-8 file while treating a missing managed path as absent.
+ */
 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;
-    }
+    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'))
-  );
+/***
+ * Narrows unknown JSON data to a non-array record.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
 
+/***
+ * Narrows a value to a non-empty string.
+ */
 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);
-}
-
+/***
+ * Narrows unknown failures to Node errors with stable error codes.
+ */
 function isNodeError(error: unknown): error is NodeJS.ErrnoException {
   return error instanceof Error && 'code' in error;
 }

package/dist/readme-usage.d.ts

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=readme-usage.d.ts.map

package/dist/readme-usage.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"readme-usage.d.ts","sourceRoot":"","sources":["../src/readme-usage.ts"],"names":[],"mappings":""}

package/dist/readme-usage.js

@@ -1,51 +0,0 @@
-import { runCli } from './cli/standalone.js';
-/***
- * Provider and CLI surface
- *
- * `@ankhorage/doctor` is the repo/package compliance provider for Ankhorage.
- *
- * The same shared command implementation backs both:
- *
- * - `ankh doctor ...`
- * - `bunx @ankhorage/doctor ...`
- *
- * Current command surface:
- *
- * - `validate`
- * - `fix`
- * - `repo`
- * - `package`
- *
- * `doctor#2` adds a profile-based policy engine:
- *
- * - strict `public-package` validation for extracted public package repos
- * - light recognized `integration-monorepo` validation for `ankhorage4`
- * - canonical app-manifest authentication validation for JSON file targets
- * - non-mutating `fix` plans for deterministic mechanical changes only
- *
- * Public-package script validation follows the canonical Devtools contract. In particular,
- * packages must expose `knip:check`; the obsolete `knip` script does not satisfy that policy.
- * Changesets dependency placement follows the same ownership boundary: `@ankhorage/devtools`
- * publishes `@changesets/cli` from `dependencies`, while consumers use the Devtools-owned
- * command without declaring the CLI directly.
- *
- * Manifest validation accepts `infra.auth.flow` as the only auth-flow location, rejects
- * `settings.authFlow` with a manual-migration diagnostic, and permits authentication without
- * an authorization block.
- *
- * Still deferred:
- *
- * - GitHub checks
- * - CI checks
- * - on-disk `fix --apply`
- * - deeper cross-repo policy enforcement
- *
- * Path handling:
- *
- * - pass a repo/package directory or app-manifest JSON file as `[path]`, or
- * - omit it to inspect the current working directory
- *
- * @usage
- */
-await runCli(['--help']);
-//# sourceMappingURL=readme-usage.js.map

package/dist/readme-usage.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"readme-usage.js","sourceRoot":"","sources":["../src/readme-usage.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC","sourcesContent":["import { runCli } from './cli/standalone.js';\n\n/***\n * Provider and CLI surface\n *\n * `@ankhorage/doctor` is the repo/package compliance provider for Ankhorage.\n *\n * The same shared command implementation backs both:\n *\n * - `ankh doctor ...`\n * - `bunx @ankhorage/doctor ...`\n *\n * Current command surface:\n *\n * - `validate`\n * - `fix`\n * - `repo`\n * - `package`\n *\n * `doctor#2` adds a profile-based policy engine:\n *\n * - strict `public-package` validation for extracted public package repos\n * - light recognized `integration-monorepo` validation for `ankhorage4`\n * - canonical app-manifest authentication validation for JSON file targets\n * - non-mutating `fix` plans for deterministic mechanical changes only\n *\n * Public-package script validation follows the canonical Devtools contract. In particular,\n * packages must expose `knip:check`; the obsolete `knip` script does not satisfy that policy.\n * Changesets dependency placement follows the same ownership boundary: `@ankhorage/devtools`\n * publishes `@changesets/cli` from `dependencies`, while consumers use the Devtools-owned\n * command without declaring the CLI directly.\n *\n * Manifest validation accepts `infra.auth.flow` as the only auth-flow location, rejects\n * `settings.authFlow` with a manual-migration diagnostic, and permits authentication without\n * an authorization block.\n *\n * Still deferred:\n *\n * - GitHub checks\n * - CI checks\n * - on-disk `fix --apply`\n * - deeper cross-repo policy enforcement\n *\n * Path handling:\n *\n * - pass a repo/package directory or app-manifest JSON file as `[path]`, or\n * - omit it to inspect the current working directory\n *\n * @usage\n */\nawait runCli(['--help']);\n"]}

package/src/readme-usage.ts

@@ -1,51 +0,0 @@
-import { runCli } from './cli/standalone.js';
-
-/***
- * Provider and CLI surface
- *
- * `@ankhorage/doctor` is the repo/package compliance provider for Ankhorage.
- *
- * The same shared command implementation backs both:
- *
- * - `ankh doctor ...`
- * - `bunx @ankhorage/doctor ...`
- *
- * Current command surface:
- *
- * - `validate`
- * - `fix`
- * - `repo`
- * - `package`
- *
- * `doctor#2` adds a profile-based policy engine:
- *
- * - strict `public-package` validation for extracted public package repos
- * - light recognized `integration-monorepo` validation for `ankhorage4`
- * - canonical app-manifest authentication validation for JSON file targets
- * - non-mutating `fix` plans for deterministic mechanical changes only
- *
- * Public-package script validation follows the canonical Devtools contract. In particular,
- * packages must expose `knip:check`; the obsolete `knip` script does not satisfy that policy.
- * Changesets dependency placement follows the same ownership boundary: `@ankhorage/devtools`
- * publishes `@changesets/cli` from `dependencies`, while consumers use the Devtools-owned
- * command without declaring the CLI directly.
- *
- * Manifest validation accepts `infra.auth.flow` as the only auth-flow location, rejects
- * `settings.authFlow` with a manual-migration diagnostic, and permits authentication without
- * an authorization block.
- *
- * Still deferred:
- *
- * - GitHub checks
- * - CI checks
- * - on-disk `fix --apply`
- * - deeper cross-repo policy enforcement
- *
- * Path handling:
- *
- * - pass a repo/package directory or app-manifest JSON file as `[path]`, or
- * - omit it to inspect the current working directory
- *
- * @usage
- */
-await runCli(['--help']);