@ankhorage/devtools 1.11.10 → 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

@@ -2,8 +2,8 @@
 name: ankhorage-project-structure
 description: >
   Define, review, or implement the standard source structure of Ankhorage repositories. Use for
-  feature ownership, CLI layout, hexagonal boundaries, source-module naming, utilities, or package
-  entrypoints.
+  feature ownership, CLI layout, hexagonal boundaries, source-module naming, type ownership,
+  utilities, or package entrypoints.
 ---
 
 # Ankhorage Project Structure
@@ -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;
@@ -62,6 +74,8 @@ src/
         outbound/
       composition/
       utils/
+  types/
+    <topic>.ts
   utils/
 ```
 
@@ -96,26 +110,69 @@ colors/
 Resolve the ownership of `otherFolder` and move it to the appropriate taxonomy. Use domain names for
 features, not framework, transport, database, or generic technical names.
 
-## One export per production module
+## Implementation modules
 
-Each production source file has exactly one export. Its exported declaration is the first declaration
-after imports and module documentation, and its name matches the filename exactly.
+Each production implementation module has exactly one exported runtime declaration. It is the first
+declaration after imports and module documentation, and its name matches the filename exactly.
+This rule does not split types into one-file-per-type modules. Type ownership follows the separate
+rules below. Deliberate public facades may group explicit named exports; they are not internal
+convenience barrels and must not expose private implementation details.
 
 - `myFunction.ts` exports `myFunction`.
 - `myFunctionAsync.ts` exports `myFunctionAsync`.
 - A public operation that is asynchronous or returns a `Promise` uses the `Async` suffix in both its
   filename and exported name.
 
-Keep private helpers below that exported declaration when they are used only by that module. Move a
-helper used by multiple modules to `utils/` at the owning layer. Put a repository-wide utility in
-`src/utils/`. Put a generally reusable cross-package utility in the correct `@ankhorage/utility`
-location.
+Keep private helpers below that exported declaration when they are used only by that module.
+Decide the owner of a reused function using the utility rules below, before creating another file.
+
+## Type ownership
+
+Choose type ownership by its production consumers, not by the number of textual references or
+whether a barrel happens to re-export it:
+
+1. **Used by one implementation module:** keep the type directly below the function that owns it,
+   without `export`. Its private helpers can use the same local type. A test does not justify
+   exporting an implementation-private type; test through the function boundary.
+2. **Reused within the repository:** put related types together in `src/types/<topic>.ts` and use
+   type-only imports. Name the file for a cohesive topic, not for each individual type. Such a file
+   may export multiple related types/interfaces and contains no runtime implementation. Do not mix
+   type-only files among feature functions or `utils/`, and do not create one global catch-all file.
+3. **Shared across repositories:** the canonical declaration belongs in `@ankhorage/contracts` at
+   the owning topic's public subpath. Consumers import that contract through a declared dependency,
+   not another repository's source or a duplicated local declaration. Keep framework-specific
+   adapters separate from the portable shared contract.
+
+Inspect published API declarations and real consumer imports before privatizing or relocating a
+type. A public boundary type is not private just because only one implementation uses it locally.
+Coordinate its Contracts change and consumer migration; do not silently remove a public type,
+invent an unreleased dependency version, or retain a compatibility re-export as the final design.
+When the required package change or release is outside the approved scope, state the dependency
+explicitly instead of claiming the migration is complete.
+
+For example, `selectRoute.ts` can own a non-exported `SelectRouteInput` directly below `selectRoute`.
+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`.
 
 ## Utilities
 
 `utils/` is the only utility directory name. Do not create `shared/`, `helper/`, `helpers/`,
-`common/`, or equivalent catch-all folders. Feature-local utilities live in that feature's `utils/`;
-utilities shared by repository features live in `src/utils/`.
+`common/`, or equivalent catch-all folders. It is not a destination for every pure function or type.
+
+- Used by one module: keep the helper private below its owning function.
+- Reused only inside a feature: keep it in that feature's `utils/`.
+- Shared across features but tied to this package's capability or policy: use `src/utils/`.
+  Navigator topology traversal or Expo Router-specific validation does not become a general utility
+  merely because several navigator features use it.
+- Generally reusable without the owning product, manifest, or framework policy: inspect the
+  published `@ankhorage/utility` API first, reuse it where semantics match, and put missing general
+  helpers in that package's owning topic. Examples include generic string escaping or source-literal
+  serialization. Do not copy a utility locally, create a forwarding wrapper, or change semantics
+  just to reuse a similarly named function.
+
+Separate the decisions for functions and types: reusable functions belong to Utility when general;
+repo-local type groups belong to `src/types/`; repo-crossing types belong to Contracts. Respect
+release boundaries and obtain approval for additional package changes when they exceed the task.
 
 This skill defines the target architecture. Schedule repository migrations separately and in this
 order: Studio, Deploy, Infra, Repository, Navigator.

package/package.json

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