@ankhorage/devtools 1.11.11 → 1.12.1

package/README.md

@@ -188,7 +188,7 @@ The canonical workflow, VS Code, and skill files are packaged with `@ankhorage/d
 
 ## Managed agent instructions
 
-`ankh devtools agents sync` owns the repository-root `AGENTS.md`. The shared instructions are intentionally small and stable. The target repository's package name and description are rendered from `package.json`; the remaining content defines the unconditional current-architecture policy and directs structural work to the managed project-structure skill.
+`ankh devtools agents sync` owns the repository-root `AGENTS.md`. The shared instructions are intentionally small and stable. The target repository's package name and description are rendered from `package.json`; the remaining content defines the unconditional current-architecture policy, directs structural work to the managed project-structure skill, and requires the canonical build, type, lint, Knip, Changeset, and formatting commands before pull request creation.
 
 Only the current Ankhorage architecture is supported. Managed instructions reject deprecated APIs, compatibility aliases, shims, dual old/new paths, historical-state fallbacks, and migrations whose sole purpose is obsolete state. A canonical cross-package change requires affected repositories to update to the latest released public API.
 
@@ -245,7 +245,7 @@ The React profile adds React and React Hooks correctness rules. The React Native
 
 ### Managed ESLint setup and local overrides
 
-`ankh devtools eslint sync` centrally owns `eslint.config.mjs` and creates `eslint.local.config.mjs` once.
+`ankh devtools eslint sync` centrally owns `eslint.config.mjs` and creates `eslint.local.config.mjs` once. When the repository has a root `examples/` directory, synchronization also owns `eslint.examples.config.mjs`; repositories without public examples do not receive that file, and synchronization removes the managed wrapper when the directory is removed.
 
 The canonical wrapper uses automatic profile detection and appends repository-owned flat-config entries:
 
@@ -267,6 +267,16 @@ export default [
 
 Use `eslint.local.config.mjs` for narrow repository-specific flat-config overrides, including temporary file-specific migration overrides. On first synchronization, an existing non-canonical `eslint.config.mjs` is preserved as the initial local config before the canonical wrapper is installed. Synchronization never overwrites that local file afterward.
 
+Each public example lives in a named directory, such as `examples/basic-usage/*.ts`; example source files do not live directly under `examples/`. The examples wrapper uses root `tsconfig.eslint.json` and `tsconfig.json` when present and discovers TypeScript projects below `examples/`. This covers example directories included only by the root ESLint project as well as standalone applications with their own tsconfig. It applies the same shared policy and appends the same repository-owned local entries.
+
+An existing consumer-owned `eslint.examples.config.mjs` requires explicit adoption before synchronization can replace it. Status, dry-run, and sync report an actionable error instead of overwriting or deleting it. Move its repository-specific overrides into `eslint.local.config.mjs`, preserving existing entries and the examples-only file scope; retain custom parser options there when needed. Remove the old examples config only after that transfer, then rerun sync and the examples lint. The generated wrapper carries a Devtools ownership marker and subsequent synchronization updates it normally. Do not mark an old consumer config as managed to bypass this transfer.
+
+Repositories can lint their independently runnable examples explicitly:
+
+```bash
+ankhorage-eslint examples --config eslint.examples.config.mjs --max-warnings=0
+```
+
 ## Prettier
 
 `ankh devtools prettier sync` owns `.prettierrc.js`, emits the correct ESM or CommonJS wrapper based on the repository's `package.json` module type, and creates `prettier.local.config.js` once for narrow repository-specific options.

package/dist/tools/agents/index.js

@@ -39,6 +39,19 @@ For directory ownership, package boundaries, architectural profiles, ports and a
 entrypoints, or cross-repository structural work, load and follow
 \`.agents/skills/ankhorage-project-structure/SKILL.md\`.
 
+## Pull requests
+
+Before creating a pull request, run all of these commands in this order and resolve every failure:
+
+\`\`\`sh
+bun run build
+bun run check-types
+bun run lint
+bun run knip:test
+bun run changeset
+bun run format
+\`\`\`
+
 ## Skill scripts
 
 Scripts inside an Agent Skill must always be TypeScript files with the \`.ts\` extension.

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

@@ -5,6 +5,12 @@ export declare const eslintManagedFiles: readonly [{
 }, {
     readonly relativePath: "eslint.config.mjs";
     readonly contents: "import { createConfig } from '@ankhorage/devtools/eslint';\nimport localConfig from './eslint.local.config.mjs';\n\nconst localEntries = Array.isArray(localConfig) ? localConfig : [localConfig];\n\nexport default [\n  ...createConfig({\n    files: ['src/**/*.{ts,tsx}'],\n    project: ['./tsconfig.json'],\n    tsconfigRootDir: import.meta.dirname,\n  }),\n  ...localEntries,\n];\n";
+}, {
+    readonly relativePath: "eslint.examples.config.mjs";
+    readonly contents: "// This file is managed by @ankhorage/devtools.\nimport { existsSync } from 'node:fs';\n\nimport { createConfig } from '@ankhorage/devtools/eslint';\nimport localConfig from './eslint.local.config.mjs';\n\nconst exampleFiles = ['examples/**/*.{ts,tsx}'];\nconst localEntries = Array.isArray(localConfig) ? localConfig : [localConfig];\nconst rootProjects = ['./tsconfig.eslint.json', './tsconfig.json'].filter((project) =>\n  existsSync(new URL(project, import.meta.url)),\n);\n\nexport default [\n  ...createConfig({\n    files: exampleFiles,\n    project: [...rootProjects, './examples/**/tsconfig.json'],\n    tsconfigRootDir: import.meta.dirname,\n  }),\n  ...localEntries,\n];\n";
+    readonly isApplicable: typeof hasExamplesDirectory;
 }];
 declare function renderInitialLocalConfig(targetDirectory: string): Promise<string>;
+/*** Report whether the target repository owns public examples at its root. */
+declare function hasExamplesDirectory(targetDirectory: string): Promise<boolean>;
 export {};

package/dist/tools/eslint/managed.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { readFile, stat } from 'node:fs/promises';
 import { resolve } from 'node:path';
 const ESLINT_CONFIG = `import { createConfig } from '@ankhorage/devtools/eslint';
 import localConfig from './eslint.local.config.mjs';
@@ -16,6 +16,27 @@ export default [
 `;
 const EMPTY_LOCAL_CONFIG = `export default [];
 `;
+const EXAMPLES_OWNERSHIP_MARKER = '// This file is managed by @ankhorage/devtools.\n';
+const ESLINT_EXAMPLES_CONFIG = `${EXAMPLES_OWNERSHIP_MARKER}import { existsSync } from 'node:fs';
+
+import { createConfig } from '@ankhorage/devtools/eslint';
+import localConfig from './eslint.local.config.mjs';
+
+const exampleFiles = ['examples/**/*.{ts,tsx}'];
+const localEntries = Array.isArray(localConfig) ? localConfig : [localConfig];
+const rootProjects = ['./tsconfig.eslint.json', './tsconfig.json'].filter((project) =>
+  existsSync(new URL(project, import.meta.url)),
+);
+
+export default [
+  ...createConfig({
+    files: exampleFiles,
+    project: [...rootProjects, './examples/**/tsconfig.json'],
+    tsconfigRootDir: import.meta.dirname,
+  }),
+  ...localEntries,
+];
+`;
 export const eslintManagedFiles = [
     {
         relativePath: 'eslint.local.config.mjs',
@@ -26,6 +47,11 @@ export const eslintManagedFiles = [
         relativePath: 'eslint.config.mjs',
         contents: ESLINT_CONFIG,
     },
+    {
+        relativePath: 'eslint.examples.config.mjs',
+        contents: ESLINT_EXAMPLES_CONFIG,
+        isApplicable: hasExamplesDirectory,
+    },
 ];
 async function renderInitialLocalConfig(targetDirectory) {
     try {
@@ -42,3 +68,34 @@ async function renderInitialLocalConfig(targetDirectory) {
 function isNodeError(error) {
     return error instanceof Error && 'code' in error;
 }
+/*** Report whether the target repository owns public examples at its root. */
+async function hasExamplesDirectory(targetDirectory) {
+    await assertExamplesConfigOwnershipAsync(targetDirectory);
+    try {
+        return (await stat(resolve(targetDirectory, 'examples'))).isDirectory();
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+/*** Require explicit adoption of consumer overrides before managing an existing examples config. */
+async function assertExamplesConfigOwnershipAsync(targetDirectory) {
+    let contents;
+    try {
+        contents = await readFile(resolve(targetDirectory, 'eslint.examples.config.mjs'), 'utf8');
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    if (!contents.startsWith(EXAMPLES_OWNERSHIP_MARKER)) {
+        throw new Error('Cannot replace consumer-owned eslint.examples.config.mjs. ' +
+            'Move its repository-specific overrides into eslint.local.config.mjs, keeping their ' +
+            'examples file scope and preserving existing local entries. Then remove the old examples ' +
+            'config and rerun sync to create the Devtools-managed wrapper.');
+    }
+}

package/dist/tools/shared/managedFiles.d.ts

@@ -6,6 +6,7 @@ export interface ManagedFileDefinition {
     readonly contents?: string;
     readonly render?: ManagedFileRenderer;
     readonly mode?: ManagedFileMode;
+    readonly isApplicable?: (targetDirectory: string) => Promise<boolean> | boolean;
 }
 type ManagedFileState = 'current' | 'missing' | 'obsolete' | 'outdated';
 export type ManagedFileSyncAction = 'unchanged' | 'created' | 'removed' | 'updated' | 'would-create' | 'would-remove' | 'would-update';

package/dist/tools/shared/managedFiles.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
 import { dirname, resolve } from 'node:path';
 export async function resolveManagedTargetDirectory(cwd, requestedPath) {
     const targetDirectory = resolve(cwd, requestedPath ?? '.');
@@ -15,10 +15,14 @@ export async function resolveManagedTargetDirectory(cwd, requestedPath) {
     return targetDirectory;
 }
 export async function inspectManagedFiles(targetDirectory, definitions) {
-    return await Promise.all(definitions.map(async (definition) => {
+    const statuses = await Promise.all(definitions.map(async (definition) => {
         const targetPath = resolve(targetDirectory, definition.relativePath);
+        const isApplicable = await (definition.isApplicable?.(targetDirectory) ?? true);
         try {
             const targetContents = await readFile(targetPath, 'utf8');
+            if (!isApplicable) {
+                return { relativePath: definition.relativePath, state: 'obsolete' };
+            }
             if ((definition.mode ?? 'replace') === 'create-only') {
                 return { relativePath: definition.relativePath, state: 'current' };
             }
@@ -30,11 +34,14 @@ export async function inspectManagedFiles(targetDirectory, definitions) {
         }
         catch (error) {
             if (isMissingFileError(error)) {
-                return { relativePath: definition.relativePath, state: 'missing' };
+                return isApplicable
+                    ? { relativePath: definition.relativePath, state: 'missing' }
+                    : undefined;
             }
             throw new Error(`Failed to inspect managed file: ${targetPath}`, { cause: error });
         }
     }));
+    return statuses.filter((status) => status !== undefined);
 }
 export async function syncManagedFiles(targetDirectory, definitions, options) {
     const statuses = await inspectManagedFiles(targetDirectory, definitions);
@@ -54,6 +61,15 @@ async function syncManagedFile(targetDirectory, status, definitionsByPath, optio
     if (definition === undefined) {
         throw new Error(`Missing managed file definition for ${status.relativePath}.`);
     }
+    if (status.state === 'obsolete') {
+        if (!options.dryRun) {
+            await rm(resolve(targetDirectory, definition.relativePath));
+        }
+        return {
+            relativePath: status.relativePath,
+            action: options.dryRun ? 'would-remove' : 'removed',
+        };
+    }
     if (options.dryRun) {
         return {
             relativePath: status.relativePath,

package/dist/tools/skills/assets/ankhorage-project-structure/SKILL.md

@@ -31,6 +31,18 @@ If `hexagonal-architecture` is missing or unreadable, stop immediately and repor
 Cannot continue: the required repository skill `hexagonal-architecture` is missing or unreadable at `.agents/skills/hexagonal-architecture/SKILL.md`. Synchronize the repository skills from `@ankhorage/devtools` and retry.
 ```
 
+## Repository-root examples
+
+`examples/` is a generally valid repository-root folder in every repository covered by this skill.
+Use it for complete, intentional, user-facing examples that people can inspect, copy, install, and
+run independently of a monorepo or internal fixture layout.
+
+Each example lives in a named subdirectory, such as `examples/basic-usage/*.ts`. Do not put example
+source files directly under `examples/`.
+
+Test-only fixtures remain owned by the applicable test structure. Do not relabel fixtures as public
+examples merely to bypass repository structure rules.
+
 ## Required source layout
 
 Every repository provides `src/features/`. It lists the repository's actual product capabilities;
@@ -64,6 +76,7 @@ src/
       utils/
   types/
     <topic>.ts
+  constants.ts
   utils/
 ```
 
@@ -142,6 +155,26 @@ For example, `selectRoute.ts` can own a non-exported `SelectRouteInput` directly
 Types used by several local navigation operations belong together in `src/types/navigation.ts`.
 A navigation binding exchanged by Studio and Navigator belongs in `@ankhorage/contracts/navigator`.
 
+## Constant ownership
+
+Constants are static declarations, not utility implementations. Do not create one exported
+constant per constant-named file under `utils/`.
+
+1. **Used by one implementation module:** keep the constant private in the module that owns it.
+2. **Reused only inside a feature:** group related constants in that feature's `constants.ts`.
+3. **Shared across features in one package:** group related package metadata, static policy values,
+   and other constants in `src/constants.ts`.
+
+A `constants.ts` module may export multiple related constants. Keep it cohesive by ownership and
+purpose; it is not a package-wide catch-all. Split constants when they have different owners, not
+merely to create one file per export.
+
+For example, Navigator's
+[`src/utils/NAVIGATOR_PACKAGE_METADATA.ts`](https://github.com/ankhorage/navigator/blob/main/src/utils/NAVIGATOR_PACKAGE_METADATA.ts)
+and
+[`src/utils/NAVIGATOR_ROUTER_POLICY.ts`](https://github.com/ankhorage/navigator/blob/main/src/utils/NAVIGATOR_ROUTER_POLICY.ts)
+belong together in `ankhorage/navigator/src/constants.ts`.
+
 ## Utilities
 
 `utils/` is the only utility directory name. Do not create `shared/`, `helper/`, `helpers/`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/devtools",
-  "version": "1.11.11",
+  "version": "1.12.1",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",