@ankhorage/devtools 1.15.2 → 1.15.3

package/README.md

@@ -3,7 +3,7 @@
 
 # @ankhorage/devtools
 
-![license: MIT](././paradox/badges/license.svg) ![npm: v1.15.2](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
+![license: MIT](././paradox/badges/license.svg) ![npm: v1.15.3](././paradox/badges/npm.svg) ![runtime: bun](././paradox/badges/runtime.svg) ![typescript: strict](././paradox/badges/typescript.svg) ![eslint: checked](././paradox/badges/eslint.svg) ![prettier: checked](././paradox/badges/prettier.svg) ![build: checked](././paradox/badges/build.svg) ![tests: checked](././paradox/badges/tests.svg) ![docs: paradox](././paradox/badges/docs.svg)
 
 Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects
 

package/dist/owner/synchronizeRenovateOwnerAsync.d.ts

@@ -1,3 +1,4 @@
+/*** Synchronize or validate Renovate-owned Devtools policy artifacts. */
 export declare function synchronizeRenovateOwnerAsync(operation: OwnerSyncOperation, targetDirectory: string, options?: OwnerSyncOptions): Promise<void>;
 type OwnerSyncOperation = 'status' | 'sync';
 interface OwnerSyncOptions {

package/dist/owner/synchronizeRenovateOwnerAsync.js

@@ -4,8 +4,10 @@ import { dirname, resolve } from 'node:path';
 import { applyBunRuntimePolicy } from '../policy/applyBunRuntimePolicy.js';
 import { nodeRuntimePolicy } from '../policy/bunRuntimePolicy.js';
 import { renderBunPolicyDocumentation } from '../policy/renderBunPolicyDocumentation.js';
+import { readCurrentDoctorVersion } from '../tools/workflows/readCurrentDoctorVersion.js';
 import { renderRenovateWorkflowAsync } from '../tools/workflows/renderRenovateWorkflowAsync.js';
 import { renderWorkflowAsync } from '../tools/workflows/renderWorkflowAsync.js';
+/*** Synchronize or validate Renovate-owned Devtools policy artifacts. */
 export async function synchronizeRenovateOwnerAsync(operation, targetDirectory, options = {}) {
     const target = resolve(targetDirectory);
     const policy = await readTargetBunPolicyAsync(target);
@@ -23,12 +25,14 @@ export async function synchronizeRenovateOwnerAsync(operation, targetDirectory,
         await (options.runLockfileAsync ?? runBunLockfileAsync)(operation, target);
     }
 }
+/*** Assert that Renovate owner synchronization targets the Devtools repository. */
 async function assertDevtoolsTargetAsync(targetDirectory) {
     const manifest = JSON.parse(await readFile(resolve(targetDirectory, 'package.json'), 'utf8'));
     if (!isRecord(manifest) || manifest.name !== '@ankhorage/devtools') {
         throw new Error('The Renovate owner sync target must be @ankhorage/devtools.');
     }
 }
+/*** Build the canonical owner-managed artifact definitions for the target repository. */
 async function createManagedDefinitionsAsync(targetDirectory, policy) {
     const manifest = JSON.parse(await readFile(resolve(targetDirectory, 'package.json'), 'utf8'));
     if (!isRecord(manifest)) {
@@ -37,6 +41,7 @@ async function createManagedDefinitionsAsync(targetDirectory, policy) {
     const readme = await readFile(resolve(targetDirectory, 'README.md'), 'utf8');
     const workflowPolicy = {
         bunVersion: policy.version,
+        doctorVersion: readCurrentDoctorVersion(),
         nodeVersion: nodeRuntimePolicy.setupVersion,
     };
     return [
@@ -62,6 +67,7 @@ async function createManagedDefinitionsAsync(targetDirectory, policy) {
         },
     ];
 }
+/*** Return owner-managed artifact paths whose current bytes differ from policy output. */
 async function getOutdatedPathsAsync(targetDirectory, definitions) {
     const results = await Promise.all(definitions.map(async ({ contents, relativePath }) => {
         const current = await readFile(resolve(targetDirectory, relativePath), 'utf8').catch((error) => {
@@ -73,12 +79,15 @@ async function getOutdatedPathsAsync(targetDirectory, definitions) {
     }));
     return results.filter((relativePath) => relativePath !== null);
 }
+/*** Narrow an unknown error to a Node error carrying an error code. */
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }
+/*** Narrow an unknown JSON-like value to a non-array record. */
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/*** Read the target repository's canonical Bun policy literals. */
 async function readTargetBunPolicyAsync(targetDirectory) {
     const contents = await readFile(resolve(targetDirectory, 'src/policy/bunRuntimePolicy.ts'), 'utf8');
     const matches = [...contents.matchAll(BUN_VERSION_PATTERN)];
@@ -97,6 +106,7 @@ async function readTargetBunPolicyAsync(targetDirectory) {
         version,
     };
 }
+/*** Synchronize or validate the target Bun lockfile through Bun itself. */
 async function runBunLockfileAsync(operation, targetDirectory) {
     const args = [
         'install',
@@ -118,9 +128,11 @@ async function runBunLockfileAsync(operation, targetDirectory) {
         });
     });
 }
+/*** Serialize a package manifest using repository formatting. */
 function serializePackageManifest(manifest) {
     return `${JSON.stringify(manifest, null, 2)}\n`;
 }
+/*** Write changed owner-managed artifacts while preserving byte-identical files. */
 async function syncDefinitionsAsync(targetDirectory, definitions) {
     for (const { contents, relativePath } of definitions) {
         const targetPath = resolve(targetDirectory, relativePath);

package/dist/tools/package/index.d.ts

@@ -1,8 +1,13 @@
 import type { ManagedFileStatus, ManagedFileSyncResult } from '../shared/managedFiles.js';
+/*** Inspect whether the Devtools-owned package manifest contract is current. */
 export declare function inspectPackageManifest(targetDirectory: string, devtoolsVersion: string): Promise<ManagedFileStatus>;
+/*** Synchronize the Devtools-owned package manifest fields. */
 export declare function syncPackageManifest(targetDirectory: string, devtoolsVersion: string, options: {
     readonly dryRun: boolean;
 }): Promise<ManagedFileSyncResult>;
+/*** Apply the Devtools-owned package scripts, dependencies, and Bun runtime policy. */
 export declare function applyManagedPackageContract(manifest: Record<string, unknown>, devtoolsVersion: string, changesetsConfigExists?: boolean): Record<string, unknown>;
+/*** Check whether the Devtools-owned package manifest fields match current policy. */
 export declare function isManagedPackageContractCurrent(manifest: Record<string, unknown>, devtoolsVersion: string, changesetsConfigExists?: boolean): boolean;
+/*** Read the current Devtools package version used for consumer synchronization. */
 export declare function readCurrentDevtoolsVersion(): string;

package/dist/tools/package/index.js

@@ -2,10 +2,9 @@
  * Synchronize the consumer `package.json` contract owned by `@ankhorage/devtools`.
  *
  * Package synchronization is merge-aware. It installs the current `@ankhorage/devtools` version
- * as a development dependency for normal consumers, while `@ankhorage/ankh` keeps devtools as a
- * runtime dependency because the CLI loads it as a bundled core provider. Individually installed
- * toolchain packages that devtools now owns are removed, and the canonical `lint`, `lint:fix`,
- * `format`, `format:check`, and `knip:check` scripts are written.
+ * as a development dependency for every consumer, including `@ankhorage/ankh`. Individually
+ * installed toolchain packages that devtools now owns are removed, and the canonical `lint`,
+ * `lint:fix`, `format`, `format:check`, and `knip:check` scripts are written.
  * Unrelated manifest fields, scripts, dependencies, and metadata are preserved.
  *
  * The Bun runtime policy is shared by every repository, including devtools itself. Devtools skips
@@ -25,7 +24,6 @@ import { bunRuntimePolicy } from '../../policy/bunRuntimePolicy.js';
 import { changesetsPolicy } from '../../policy/changesetsPolicy.js';
 const PACKAGE_PATH = 'package.json';
 const DEVTOOLS_PACKAGE_NAME = '@ankhorage/devtools';
-const ANKH_PACKAGE_NAME = '@ankhorage/ankh';
 const BUN_TYPES_PACKAGE_NAME = '@types/bun';
 const CHANGESETS_CONFIG_PATH = '.changeset/config.json';
 const STANDARD_SCRIPTS = {
@@ -51,6 +49,7 @@ const DEVTOOLS_OWNED_DEV_DEPENDENCIES = [
     'prettier',
     'typescript-eslint',
 ];
+/*** Inspect whether the Devtools-owned package manifest contract is current. */
 export async function inspectPackageManifest(targetDirectory, devtoolsVersion) {
     const snapshot = await readPackageManifest(targetDirectory);
     if (!snapshot.exists) {
@@ -63,6 +62,7 @@ export async function inspectPackageManifest(targetDirectory, devtoolsVersion) {
             : 'outdated',
     };
 }
+/*** Synchronize the Devtools-owned package manifest fields. */
 export async function syncPackageManifest(targetDirectory, devtoolsVersion, options) {
     const snapshot = await readPackageManifest(targetDirectory);
     if (snapshot.exists &&
@@ -82,6 +82,7 @@ export async function syncPackageManifest(targetDirectory, devtoolsVersion, opti
         action: snapshot.exists ? 'updated' : 'created',
     };
 }
+/*** Apply the Devtools-owned package scripts, dependencies, and Bun runtime policy. */
 export function applyManagedPackageContract(manifest, devtoolsVersion, changesetsConfigExists = false) {
     if (manifest.name === DEVTOOLS_PACKAGE_NAME) {
         return applyBunRuntimePolicy(manifest, bunRuntimePolicy);
@@ -97,7 +98,7 @@ export function applyManagedPackageContract(manifest, devtoolsVersion, changeset
     const dependencies = toRecord(manifest.dependencies);
     delete dependencies[changesetsPolicy.packageName];
     delete devDependencies[changesetsPolicy.packageName];
-    applyDevtoolsDependencyPlacement(manifest, dependencies, devDependencies, devtoolsVersion);
+    applyDevtoolsDependencyPlacement(dependencies, devDependencies, devtoolsVersion);
     return applyBunRuntimePolicy({
         ...manifest,
         ...normalizedDependencies(manifest, dependencies),
@@ -105,6 +106,7 @@ export function applyManagedPackageContract(manifest, devtoolsVersion, changeset
         devDependencies,
     }, bunRuntimePolicy);
 }
+/*** Check whether the Devtools-owned package manifest fields match current policy. */
 export function isManagedPackageContractCurrent(manifest, devtoolsVersion, changesetsConfigExists = false) {
     if (!hasCurrentBunRuntimePolicy(manifest)) {
         return false;
@@ -121,8 +123,9 @@ export function isManagedPackageContractCurrent(manifest, devtoolsVersion, chang
         dependencies[changesetsPolicy.packageName] === undefined &&
         devDependencies[changesetsPolicy.packageName] === undefined &&
         hasCurrentChangesetsScripts(scripts, changesetsEnabled) &&
-        hasCurrentDevtoolsDependencyPlacement(manifest, dependencies, devDependencies, devtoolsVersion));
+        hasCurrentDevtoolsDependencyPlacement(dependencies, devDependencies, devtoolsVersion));
 }
+/*** Read the current Devtools package version used for consumer synchronization. */
 export function readCurrentDevtoolsVersion() {
     const parsed = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
     if (!isRecord(parsed) || typeof parsed.version !== 'string' || parsed.version.trim() === '') {
@@ -130,6 +133,7 @@ export function readCurrentDevtoolsVersion() {
     }
     return parsed.version;
 }
+/*** Read one package manifest snapshot and Changesets applicability state. */
 async function readPackageManifest(targetDirectory) {
     const changesetsConfigExists = existsSync(resolve(targetDirectory, CHANGESETS_CONFIG_PATH));
     try {
@@ -147,62 +151,63 @@ async function readPackageManifest(targetDirectory) {
         throw error;
     }
 }
+/*** Check the Bun package manager and Bun type dependency contract. */
 function hasCurrentBunRuntimePolicy(manifest) {
     const devDependencies = toRecord(manifest.devDependencies);
     return (manifest.packageManager === bunRuntimePolicy.packageManager &&
         devDependencies[BUN_TYPES_PACKAGE_NAME] === bunRuntimePolicy.typesRange);
 }
-function applyDevtoolsDependencyPlacement(manifest, dependencies, devDependencies, devtoolsVersion) {
-    const versionRange = `^${devtoolsVersion}`;
-    if (manifest.name === ANKH_PACKAGE_NAME) {
-        dependencies[DEVTOOLS_PACKAGE_NAME] = versionRange;
-        delete devDependencies[DEVTOOLS_PACKAGE_NAME];
-        return;
-    }
-    devDependencies[DEVTOOLS_PACKAGE_NAME] = versionRange;
+/*** Place Devtools in development dependencies for every consuming repository. */
+function applyDevtoolsDependencyPlacement(dependencies, devDependencies, devtoolsVersion) {
+    devDependencies[DEVTOOLS_PACKAGE_NAME] = `^${devtoolsVersion}`;
     delete dependencies[DEVTOOLS_PACKAGE_NAME];
 }
-function hasCurrentDevtoolsDependencyPlacement(manifest, dependencies, devDependencies, devtoolsVersion) {
-    const versionRange = `^${devtoolsVersion}`;
-    if (manifest.name === ANKH_PACKAGE_NAME) {
-        return (dependencies[DEVTOOLS_PACKAGE_NAME] === versionRange &&
-            devDependencies[DEVTOOLS_PACKAGE_NAME] === undefined);
-    }
-    return (devDependencies[DEVTOOLS_PACKAGE_NAME] === versionRange &&
+/*** Check that Devtools is development-only at the current synchronized version. */
+function hasCurrentDevtoolsDependencyPlacement(dependencies, devDependencies, devtoolsVersion) {
+    return (devDependencies[DEVTOOLS_PACKAGE_NAME] === `^${devtoolsVersion}` &&
         dependencies[DEVTOOLS_PACKAGE_NAME] === undefined);
 }
+/*** Remove direct development dependencies owned by the Devtools package. */
 function removeOwnedDependencies(devDependencies) {
     for (const dependencyName of DEVTOOLS_OWNED_DEV_DEPENDENCIES) {
         delete devDependencies[dependencyName];
     }
     return devDependencies;
 }
+/*** Preserve an existing dependencies object or omit a newly empty one. */
 function normalizedDependencies(manifest, dependencies) {
     return Object.keys(dependencies).length === 0 && manifest.dependencies === undefined
         ? {}
         : { dependencies };
 }
+/*** Check the canonical development-tool scripts. */
 function hasStandardScripts(scripts) {
     return (scripts.knip === undefined &&
         Object.entries(STANDARD_SCRIPTS).every(([name, command]) => scripts[name] === command));
 }
+/*** Check Changesets scripts when the repository participates in Changesets. */
 function hasCurrentChangesetsScripts(scripts, changesetsEnabled) {
     return (!changesetsEnabled ||
         Object.entries(changesetsPolicy.packageScripts).every(([name, command]) => scripts[name] === command));
 }
+/*** Determine whether the repository participates in Changesets synchronization. */
 function isChangesetsEnabled(scripts, changesetsConfigExists) {
     return (changesetsConfigExists ||
         Object.keys(changesetsPolicy.packageScripts).some((scriptName) => scripts[scriptName] !== undefined));
 }
+/*** Serialize a package manifest using the repository formatting contract. */
 function serializePackageManifest(manifest) {
     return `${JSON.stringify(manifest, null, 2)}\n`;
 }
+/*** Copy a JSON-like value to a mutable record or return an empty record. */
 function toRecord(value) {
     return isRecord(value) ? { ...value } : {};
 }
+/*** Narrow an unknown JSON-like value to a non-array record. */
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/*** Narrow an unknown error to a Node error carrying an error code. */
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }

package/dist/tools/workflows/files/ci.yml

@@ -49,7 +49,7 @@ jobs:
           fi
 
       - name: Validate Ankhorage repository
-        run: bunx @ankhorage/ankh doctor validate .
+        run: BUN_INSTALL_CACHE_DIR="${RUNNER_TEMP}/doctor-cache" bunx @ankhorage/doctor@__ANKH_DOCTOR_VERSION__ validate .
 
       - name: Run lint
         run: |

package/dist/tools/workflows/index.js

@@ -2,6 +2,7 @@ import { access } from 'node:fs/promises';
 import { join } from 'node:path';
 import { resolveApmReleaseCommandAsync } from '../../features/apm-release-validation/adapters/outbound/resolveApmReleaseCommandAsync.js';
 import { bunRuntimePolicy, nodeRuntimePolicy } from '../../policy/bunRuntimePolicy.js';
+import { readCurrentDoctorVersion } from './readCurrentDoctorVersion.js';
 import { renderRenovateWorkflowAsync } from './renderRenovateWorkflowAsync.js';
 import { renderWorkflowAsync } from './renderWorkflowAsync.js';
 export const workflowManagedFiles = [
@@ -27,6 +28,7 @@ export const workflowManagedFiles = [
         mode: 'create-only',
     },
 ];
+/*** Create a managed workflow definition rendered from current shared runtime policies. */
 function createWorkflowDefinition(relativePath, sourcePath) {
     const sourceUrl = new URL(sourcePath, import.meta.url);
     return {
@@ -34,6 +36,7 @@ function createWorkflowDefinition(relativePath, sourcePath) {
         render: async (targetDirectory) => await renderWorkflowAsync(sourceUrl, {
             apmReleaseCommand: await resolveApmReleaseCommandAsync(targetDirectory),
             bunVersion: bunRuntimePolicy.version,
+            doctorVersion: readCurrentDoctorVersion(),
             nodeVersion: nodeRuntimePolicy.setupVersion,
         }),
     };
@@ -46,6 +49,7 @@ function createRenovateWorkflowDefinition() {
         render: async (targetDirectory) => await renderRenovateWorkflowAsync(sourceUrl, targetDirectory, {
             apmReleaseCommand: await resolveApmReleaseCommandAsync(targetDirectory),
             bunVersion: bunRuntimePolicy.version,
+            doctorVersion: readCurrentDoctorVersion(),
             nodeVersion: nodeRuntimePolicy.setupVersion,
         }),
     };

package/dist/tools/workflows/readCurrentDoctorVersion.d.ts

@@ -0,0 +1,2 @@
+/*** Read the exact Doctor version owned by the current Devtools package release. */
+export declare function readCurrentDoctorVersion(): string;

package/dist/tools/workflows/readCurrentDoctorVersion.js

@@ -0,0 +1,15 @@
+import { readFileSync } from 'node:fs';
+import { isRecord } from '@ankhorage/utility/object';
+const DOCTOR_PACKAGE_NAME = '@ankhorage/doctor';
+/*** Read the exact Doctor version owned by the current Devtools package release. */
+export function readCurrentDoctorVersion() {
+    const parsed = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
+    if (!isRecord(parsed) || !isRecord(parsed.devDependencies)) {
+        throw new Error('Devtools package.json must define development dependencies.');
+    }
+    const version = parsed.devDependencies[DOCTOR_PACKAGE_NAME];
+    if (typeof version !== 'string' || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(version)) {
+        throw new Error(`Devtools must pin ${DOCTOR_PACKAGE_NAME} to one exact version.`);
+    }
+    return version;
+}

package/dist/tools/workflows/renderWorkflowAsync.d.ts

@@ -1,7 +1,8 @@
 export interface WorkflowPolicy {
     readonly bunVersion: string;
+    readonly doctorVersion: string;
     readonly nodeVersion: string;
     readonly apmReleaseCommand?: string;
 }
-/*** Renders one workflow template with the canonical runtime and Changesets policy. */
+/*** Renders one workflow template with the canonical runtime, Doctor, and Changesets policy. */
 export declare function renderWorkflowAsync(sourceUrl: URL, policy: WorkflowPolicy): Promise<string>;

package/dist/tools/workflows/renderWorkflowAsync.js

@@ -1,6 +1,6 @@
 import { readFile } from 'node:fs/promises';
 import { changesetsPolicy } from '../../policy/changesetsPolicy.js';
-/*** Renders one workflow template with the canonical runtime and Changesets policy. */
+/*** Renders one workflow template with the canonical runtime, Doctor, and Changesets policy. */
 export async function renderWorkflowAsync(sourceUrl, policy) {
     const template = await readFile(sourceUrl, 'utf8');
     return template
@@ -8,6 +8,7 @@ export async function renderWorkflowAsync(sourceUrl, policy) {
         .replaceAll(CHANGESETS_PUBLISH_COMMAND_TOKEN, changesetsPolicy.workflowCommands.publish)
         .replaceAll(CHANGESETS_STATUS_COMMAND_TOKEN, changesetsPolicy.workflowCommands.status)
         .replaceAll(CHANGESETS_VERSION_COMMAND_TOKEN, changesetsPolicy.workflowCommands.version)
+        .replaceAll(DOCTOR_VERSION_TOKEN, policy.doctorVersion)
         .replaceAll('__ANKH_APM_RELEASE_COMMAND__', policy.apmReleaseCommand ?? './node_modules/.bin/ankhorage-apm-release')
         .replaceAll(NODE_VERSION_TOKEN, policy.nodeVersion);
 }
@@ -15,4 +16,5 @@ const BUN_VERSION_TOKEN = '__ANKH_BUN_VERSION__';
 const CHANGESETS_PUBLISH_COMMAND_TOKEN = '__ANKH_CHANGESETS_PUBLISH_COMMAND__';
 const CHANGESETS_STATUS_COMMAND_TOKEN = '__ANKH_CHANGESETS_STATUS_COMMAND__';
 const CHANGESETS_VERSION_COMMAND_TOKEN = '__ANKH_CHANGESETS_VERSION_COMMAND__';
+const DOCTOR_VERSION_TOKEN = '__ANKH_DOCTOR_VERSION__';
 const NODE_VERSION_TOKEN = '__ANKH_NODE_VERSION__';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.15.2",
+  "version": "1.15.3",
   "description": "Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -144,7 +144,7 @@
   "devDependencies": {
     "@ankhorage/paradox": "^0.1.26",
     "@ankhorage/ankh": "^0.8.11",
-    "@ankhorage/doctor": "0.10.8",
+    "@ankhorage/doctor": "0.10.14",
     "@techstark/opencv-js": "^5.0.0-release.1",
     "@types/bun": "^1.4.1",
     "@types/node": "^26.4.1",