@ankhorage/devtools 1.11.11 → 1.12.0

package/README.md

@@ -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/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;

package/package.json

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