@ankhorage/devtools 1.11.10 → 1.11.11

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
@@ -62,6 +62,8 @@ src/
         outbound/
       composition/
       utils/
+  types/
+    <topic>.ts
   utils/
 ```
 
@@ -96,26 +98,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.11.11",
   "description": "Shared development tools and repository standards for Ankhorage",
   "license": "MIT",
   "homepage": "https://github.com/ankhorage/devtools#readme",