@ankhorage/devtools 1.14.7 → 1.14.8

package/README.md

@@ -1,4 +1,13 @@
-# devtools
+<!-- markdownlint-disable MD013 MD033 -->
+<!-- This file is generated by Paradox. Do not edit manually. -->
+
+# @ankhorage/devtools
+
+![license: MIT](././paradox/badges/license.svg) ![npm: v1.14.7](././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
+
+## Usage
 
 Shared development tools and repository standards for Ankhorage TypeScript projects.
 
@@ -204,7 +213,7 @@ Agent Skill scripts are always TypeScript files with a `.ts` extension and run w
 
 `createConfig()` defaults to `profile: 'auto'`.
 
-Automatic detection reads the consuming repository's `package.json` and delegates project trait detection to `@ankhorage/utility/project`. Dependency signals are considered across `dependencies`, `devDependencies`, and `peerDependencies`.
+Automatic detection reads the consuming repository's `package.json` and delegates project trait detection to `@ankhorage/project-detector`. Dependency signals are considered across `dependencies`, `devDependencies`, and `peerDependencies`.
 
 Profile precedence is:
 
@@ -375,3 +384,39 @@ A new concern should:
 4. add provider commands under `ankh devtools`
 5. include dry-run, status, and idempotence coverage
 6. document its central ownership and repository-owned extension points
+
+## CLI
+
+Run and synchronize the shared development toolchain through the Ankh CLI.
+
+`ankh devtools changeset`, `ankh devtools lint`, `ankh devtools format`, and
+`ankh devtools knip` execute the bundled Changesets, ESLint, Prettier, and Knip versions.
+Repository synchronization is available through
+`ankh devtools sync` and `ankh devtools status`, with focused `agents`, `skills`, `eslint`,
+`prettier`, `knip`, `package`, `workflows`, and `vscode` sync/status subcommands.
+
+Sync commands accept an optional target directory and `--dry-run`. Aggregate sync is
+deterministic and idempotent: canonical managed files and skill trees are created or updated,
+unrelated repository-local skills and create-only local extension files remain repository-owned,
+and package metadata is merge-updated without replacing unrelated fields.
+
+Fresh repositories can bootstrap the standard setup with `ankh devtools sync .` after adding
+`@ankhorage/devtools`. Existing ESLint configuration is preserved during first migration as a
+local extension before the canonical auto-detecting wrapper is installed.
+
+```bash
+bunx @ankhorage/devtools ankhorage-changeset
+bunx @ankhorage/devtools ankhorage-eslint
+bunx @ankhorage/devtools ankhorage-knip
+bunx @ankhorage/devtools ankhorage-prettier
+```
+
+## Generated documentation
+
+- [Interactive documentation app](././paradox/index.html)
+- [Public API reference](././paradox/exports.md)
+- [Component registry](././paradox/components.md)
+- [Architecture overview](././paradox/diagrams/architecture-overview.mmd)
+- [Module relationships](././paradox/diagrams/module-relationships.mmd)
+- [Export graph](././paradox/diagrams/export-graph.mmd)
+- [createKnipMonorepoConfig sequence](././paradox/diagrams/sequences/create-knip-monorepo-config.mmd)

package/dist/internal/readmeDocs.js

@@ -26,7 +26,7 @@ const REQUIRED_README_SNIPPETS = [
     'devtools.vscode.sync',
     '--dry-run',
     "profile: 'auto'",
-    '@ankhorage/utility/project',
+    '@ankhorage/project-detector',
     'ankhorage-changeset',
     'without creating a second Version Packages pull request',
     'chore(release)',

package/dist/owner/synchronizeRenovateOwnerAsync.js

@@ -3,6 +3,7 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 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 { renderRenovateWorkflowAsync } from '../tools/workflows/renderRenovateWorkflowAsync.js';
 import { renderWorkflowAsync } from '../tools/workflows/renderWorkflowAsync.js';
 export async function synchronizeRenovateOwnerAsync(operation, targetDirectory, options = {}) {
@@ -57,7 +58,7 @@ async function createManagedDefinitionsAsync(targetDirectory, policy) {
         },
         {
             relativePath: 'README.md',
-            contents: replaceReadmePolicy(readme, policy),
+            contents: renderBunPolicyDocumentation(readme, policy),
         },
     ];
 }
@@ -96,26 +97,6 @@ async function readTargetBunPolicyAsync(targetDirectory) {
         version,
     };
 }
-function replaceReadmePolicy(readme, policy) {
-    const startIndex = readme.indexOf(README_POLICY_START);
-    const endIndex = readme.indexOf(README_POLICY_END);
-    if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
-        throw new Error('README.md must contain one ordered Devtools Bun policy marker pair.');
-    }
-    if (readme.includes(README_POLICY_START, startIndex + README_POLICY_START.length) ||
-        readme.includes(README_POLICY_END, endIndex + README_POLICY_END.length)) {
-        throw new Error('README.md must contain exactly one Devtools Bun policy marker pair.');
-    }
-    const replacement = `${README_POLICY_START}\n\n${renderReadmePolicy(policy)}\n\n${README_POLICY_END}`;
-    return `${readme.slice(0, startIndex)}${replacement}${readme.slice(endIndex + README_POLICY_END.length)}`;
-}
-function renderReadmePolicy(policy) {
-    return `\`\`\`text
-Bun runtime       ${policy.version}
-packageManager    ${policy.packageManager}
-@types/bun        ${policy.typesRange}
-\`\`\``;
-}
 async function runBunLockfileAsync(operation, targetDirectory) {
     const args = [
         'install',
@@ -156,5 +137,3 @@ async function syncDefinitionsAsync(targetDirectory, definitions) {
 }
 const BUN_VERSION_PATTERN = /const BUN_VERSION = '(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)';/gu;
 const BUN_TYPES_VERSION_PATTERN = /const BUN_TYPES_VERSION = '(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)';/gu;
-const README_POLICY_END = '<!-- devtools-bun-policy:end -->';
-const README_POLICY_START = '<!-- devtools-bun-policy:start -->';

package/dist/policy/renderBunPolicyDocumentation.d.ts

@@ -0,0 +1,3 @@
+import type { BunPolicy } from '../types/bunPolicy.js';
+/*** Render the managed Bun policy section while preserving the surrounding guide. */
+export declare function renderBunPolicyDocumentation(readme: string, policy: BunPolicy): string;

package/dist/policy/renderBunPolicyDocumentation.js

@@ -0,0 +1,24 @@
+/*** Render the managed Bun policy section while preserving the surrounding guide. */
+export function renderBunPolicyDocumentation(readme, policy) {
+    const startIndex = readme.indexOf(README_POLICY_START);
+    const endIndex = readme.indexOf(README_POLICY_END);
+    if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+        throw new Error('README.md must contain one ordered Devtools Bun policy marker pair.');
+    }
+    if (readme.includes(README_POLICY_START, startIndex + README_POLICY_START.length) ||
+        readme.includes(README_POLICY_END, endIndex + README_POLICY_END.length)) {
+        throw new Error('README.md must contain exactly one Devtools Bun policy marker pair.');
+    }
+    const replacement = `${README_POLICY_START}\n\n${renderReadmePolicy(policy)}\n\n${README_POLICY_END}`;
+    return `${readme.slice(0, startIndex)}${replacement}${readme.slice(endIndex + README_POLICY_END.length)}`;
+}
+/*** Format canonical runtime and type-package versions for the guide. */
+function renderReadmePolicy(policy) {
+    return `\`\`\`text
+Bun runtime       ${policy.version}
+packageManager    ${policy.packageManager}
+@types/bun        ${policy.typesRange}
+\`\`\``;
+}
+const README_POLICY_END = '<!-- devtools-bun-policy:end -->';
+const README_POLICY_START = '<!-- devtools-bun-policy:start -->';

package/dist/tools/eslint/index.js

@@ -2,7 +2,7 @@
  * Create the shared strict ESLint flat configuration used by consuming repositories.
  *
  * The default `profile: 'auto'` reads the nearest `package.json` from `tsconfigRootDir` and uses
- * `@ankhorage/utility/project` to select overlapping project traits. React Native and Expo select
+ * `@ankhorage/project-detector` to select overlapping project traits. React Native and Expo select
  * the `react-native` profile, React and Next.js select `react`, and other projects use `base`.
  *
  * Every profile includes the shared TypeScript, import, unused-import, Prettier, security, and
@@ -30,7 +30,7 @@ import securityPlugin from 'eslint-plugin-security';
 import simpleImportSort from 'eslint-plugin-simple-import-sort';
 import unusedImports from 'eslint-plugin-unused-imports';
 import tseslint from 'typescript-eslint';
-import { resolveEslintProfile } from './profile.js';
+import { resolveEslintProfile } from './resolveEslintProfile.js';
 export const defaultIgnores = [
     '**/ios/**',
     '**/android/**',

package/dist/tools/eslint/resolveEslintProfile.d.ts

@@ -0,0 +1,3 @@
+import type { DevtoolsConfigOptions, ResolvedDevtoolsEslintProfile } from './types.js';
+/*** Read the consuming package metadata and resolve its requested ESLint profile. */
+export declare function resolveEslintProfile(options: DevtoolsConfigOptions): ResolvedDevtoolsEslintProfile;

package/dist/tools/eslint/{profile.js → resolveEslintProfile.js}

@@ -1,6 +1,8 @@
 import { readFileSync } from 'node:fs';
-import { detectProject, } from '@ankhorage/utility/project';
+import { isRecord } from '@ankhorage/utility/object';
 import { resolveProjectPackageJsonPath } from './packageJsonPath.js';
+import { resolveEslintProfileFromDetectionInput } from './resolveEslintProfileFromDetectionInput.js';
+/*** Read the consuming package metadata and resolve its requested ESLint profile. */
 export function resolveEslintProfile(options) {
     const requestedProfile = options.profile ?? 'auto';
     if (requestedProfile !== 'auto')
@@ -9,14 +11,7 @@ export function resolveEslintProfile(options) {
     const input = packageJsonPath === null ? {} : readDetectionInput(packageJsonPath);
     return resolveEslintProfileFromDetectionInput('auto', input);
 }
-export function resolveEslintProfileFromDetectionInput(requestedProfile, input) {
-    if (requestedProfile !== 'auto')
-        return requestedProfile;
-    const { traits } = detectProject(input);
-    if (traits.has('react-native') || traits.has('expo'))
-        return 'react-native';
-    return traits.has('react') ? 'react' : 'base';
-}
+/*** Normalize relevant manifest fields without evaluating project configuration. */
 function readDetectionInput(packageJsonPath) {
     const parsed = JSON.parse(readFileSync(packageJsonPath, 'utf8'));
     if (!isRecord(parsed)) {
@@ -30,20 +25,18 @@ function readDetectionInput(packageJsonPath) {
         ...(typeof parsed.packageManager === 'string' ? { packageManager: parsed.packageManager } : {}),
     };
 }
+/*** Include one dependency section only when it contains a record. */
 function optionalDependencyMap(key, value) {
     const dependencyMap = toDependencyMap(value);
     return dependencyMap === undefined ? {} : { [key]: dependencyMap };
 }
+/*** Retain string package ranges from one manifest dependency section. */
 function toDependencyMap(value) {
     if (!isRecord(value))
         return undefined;
-    const dependencies = {};
-    for (const [name, version] of Object.entries(value)) {
-        if (typeof version === 'string')
-            dependencies[name] = version;
-    }
-    return dependencies;
+    return Object.fromEntries(Object.entries(value).flatMap(([name, version]) => typeof version === 'string' ? [[name, version]] : []));
 }
+/*** Retain runtime engine signals used by the canonical detector. */
 function optionalEngines(value) {
     if (!isRecord(value))
         return {};
@@ -53,6 +46,3 @@ function optionalEngines(value) {
     };
     return Object.keys(engines).length === 0 ? {} : { engines };
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}

package/dist/tools/eslint/resolveEslintProfileFromDetectionInput.d.ts

@@ -0,0 +1,4 @@
+import type { ProjectDetectionInput } from '@ankhorage/project-detector/types';
+import type { DevtoolsEslintProfile, ResolvedDevtoolsEslintProfile } from './types.js';
+/*** Apply Devtools profile precedence to traits from the canonical project detector. */
+export declare function resolveEslintProfileFromDetectionInput(requestedProfile: DevtoolsEslintProfile, input: ProjectDetectionInput): ResolvedDevtoolsEslintProfile;

package/dist/tools/eslint/resolveEslintProfileFromDetectionInput.js

@@ -0,0 +1,10 @@
+import { detectProject } from '@ankhorage/project-detector';
+/*** Apply Devtools profile precedence to traits from the canonical project detector. */
+export function resolveEslintProfileFromDetectionInput(requestedProfile, input) {
+    if (requestedProfile !== 'auto')
+        return requestedProfile;
+    const { traits } = detectProject(input);
+    if (traits.has('react-native') || traits.has('expo'))
+        return 'react-native';
+    return traits.has('react') ? 'react' : 'base';
+}

package/dist/types/bunPolicy.d.ts

@@ -0,0 +1,5 @@
+export interface BunPolicy {
+    readonly packageManager: string;
+    readonly typesRange: string;
+    readonly version: string;
+}

package/dist/types/bunPolicy.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.14.7",
+  "version": "1.14.8",
   "description": "Shared tooling, repository automation, runtime policies, and agent standards for Ankhorage TypeScript projects",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",
@@ -100,7 +100,7 @@
     "lint:fix": "eslint . --fix --max-warnings=0",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
-    "docs": "bun run docs:check",
+    "docs": "paradox && bun run docs:check",
     "docs:check": "bun scripts/check-docs.ts",
     "test": "bun test",
     "changeset": "bun src/cli/bin/changeset.ts",
@@ -108,6 +108,7 @@
     "version-packages": "bun src/cli/bin/changeset.ts version"
   },
   "dependencies": {
+    "@ankhorage/project-detector": "^0.1.0",
     "@ankhorage/utility": "^0.5.1",
     "@changesets/cli": "^3.0.2",
     "@eslint/compat": "^2.1.1",
@@ -127,6 +128,7 @@
     "typescript-eslint": "^8.69.0"
   },
   "devDependencies": {
+    "@ankhorage/paradox": "^0.1.26",
     "@ankhorage/ankh": "^0.8.11",
     "@ankhorage/doctor": "0.10.8",
     "@techstark/opencv-js": "^5.0.0-release.1",

package/dist/tools/eslint/profile.d.ts

@@ -1,4 +0,0 @@
-import { type ProjectDetectionInput } from '@ankhorage/utility/project';
-import type { DevtoolsConfigOptions, DevtoolsEslintProfile, ResolvedDevtoolsEslintProfile } from './types.js';
-export declare function resolveEslintProfile(options: DevtoolsConfigOptions): ResolvedDevtoolsEslintProfile;
-export declare function resolveEslintProfileFromDetectionInput(requestedProfile: DevtoolsEslintProfile, input: ProjectDetectionInput): ResolvedDevtoolsEslintProfile;