@ankhorage/devtools 1.11.9 → 1.11.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
|
@@ -2,8 +2,8 @@
|
|
|
2
2
|
name: ankhorage-project-structure
|
|
3
3
|
description: >
|
|
4
4
|
Define, review, or implement the standard source structure of Ankhorage repositories. Use for
|
|
5
|
-
feature ownership, CLI layout, hexagonal boundaries, source-module naming,
|
|
6
|
-
entrypoints.
|
|
5
|
+
feature ownership, CLI layout, hexagonal boundaries, source-module naming, type ownership,
|
|
6
|
+
utilities, or package entrypoints.
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# Ankhorage Project Structure
|
|
@@ -62,6 +62,8 @@ src/
|
|
|
62
62
|
outbound/
|
|
63
63
|
composition/
|
|
64
64
|
utils/
|
|
65
|
+
types/
|
|
66
|
+
<topic>.ts
|
|
65
67
|
utils/
|
|
66
68
|
```
|
|
67
69
|
|
|
@@ -96,26 +98,69 @@ colors/
|
|
|
96
98
|
Resolve the ownership of `otherFolder` and move it to the appropriate taxonomy. Use domain names for
|
|
97
99
|
features, not framework, transport, database, or generic technical names.
|
|
98
100
|
|
|
99
|
-
##
|
|
101
|
+
## Implementation modules
|
|
100
102
|
|
|
101
|
-
Each production
|
|
102
|
-
after imports and module documentation, and its name matches the filename exactly.
|
|
103
|
+
Each production implementation module has exactly one exported runtime declaration. It is the first
|
|
104
|
+
declaration after imports and module documentation, and its name matches the filename exactly.
|
|
105
|
+
This rule does not split types into one-file-per-type modules. Type ownership follows the separate
|
|
106
|
+
rules below. Deliberate public facades may group explicit named exports; they are not internal
|
|
107
|
+
convenience barrels and must not expose private implementation details.
|
|
103
108
|
|
|
104
109
|
- `myFunction.ts` exports `myFunction`.
|
|
105
110
|
- `myFunctionAsync.ts` exports `myFunctionAsync`.
|
|
106
111
|
- A public operation that is asynchronous or returns a `Promise` uses the `Async` suffix in both its
|
|
107
112
|
filename and exported name.
|
|
108
113
|
|
|
109
|
-
Keep private helpers below that exported declaration when they are used only by that module.
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
114
|
+
Keep private helpers below that exported declaration when they are used only by that module.
|
|
115
|
+
Decide the owner of a reused function using the utility rules below, before creating another file.
|
|
116
|
+
|
|
117
|
+
## Type ownership
|
|
118
|
+
|
|
119
|
+
Choose type ownership by its production consumers, not by the number of textual references or
|
|
120
|
+
whether a barrel happens to re-export it:
|
|
121
|
+
|
|
122
|
+
1. **Used by one implementation module:** keep the type directly below the function that owns it,
|
|
123
|
+
without `export`. Its private helpers can use the same local type. A test does not justify
|
|
124
|
+
exporting an implementation-private type; test through the function boundary.
|
|
125
|
+
2. **Reused within the repository:** put related types together in `src/types/<topic>.ts` and use
|
|
126
|
+
type-only imports. Name the file for a cohesive topic, not for each individual type. Such a file
|
|
127
|
+
may export multiple related types/interfaces and contains no runtime implementation. Do not mix
|
|
128
|
+
type-only files among feature functions or `utils/`, and do not create one global catch-all file.
|
|
129
|
+
3. **Shared across repositories:** the canonical declaration belongs in `@ankhorage/contracts` at
|
|
130
|
+
the owning topic's public subpath. Consumers import that contract through a declared dependency,
|
|
131
|
+
not another repository's source or a duplicated local declaration. Keep framework-specific
|
|
132
|
+
adapters separate from the portable shared contract.
|
|
133
|
+
|
|
134
|
+
Inspect published API declarations and real consumer imports before privatizing or relocating a
|
|
135
|
+
type. A public boundary type is not private just because only one implementation uses it locally.
|
|
136
|
+
Coordinate its Contracts change and consumer migration; do not silently remove a public type,
|
|
137
|
+
invent an unreleased dependency version, or retain a compatibility re-export as the final design.
|
|
138
|
+
When the required package change or release is outside the approved scope, state the dependency
|
|
139
|
+
explicitly instead of claiming the migration is complete.
|
|
140
|
+
|
|
141
|
+
For example, `selectRoute.ts` can own a non-exported `SelectRouteInput` directly below `selectRoute`.
|
|
142
|
+
Types used by several local navigation operations belong together in `src/types/navigation.ts`.
|
|
143
|
+
A navigation binding exchanged by Studio and Navigator belongs in `@ankhorage/contracts/navigator`.
|
|
113
144
|
|
|
114
145
|
## Utilities
|
|
115
146
|
|
|
116
147
|
`utils/` is the only utility directory name. Do not create `shared/`, `helper/`, `helpers/`,
|
|
117
|
-
`common/`, or equivalent catch-all folders.
|
|
118
|
-
|
|
148
|
+
`common/`, or equivalent catch-all folders. It is not a destination for every pure function or type.
|
|
149
|
+
|
|
150
|
+
- Used by one module: keep the helper private below its owning function.
|
|
151
|
+
- Reused only inside a feature: keep it in that feature's `utils/`.
|
|
152
|
+
- Shared across features but tied to this package's capability or policy: use `src/utils/`.
|
|
153
|
+
Navigator topology traversal or Expo Router-specific validation does not become a general utility
|
|
154
|
+
merely because several navigator features use it.
|
|
155
|
+
- Generally reusable without the owning product, manifest, or framework policy: inspect the
|
|
156
|
+
published `@ankhorage/utility` API first, reuse it where semantics match, and put missing general
|
|
157
|
+
helpers in that package's owning topic. Examples include generic string escaping or source-literal
|
|
158
|
+
serialization. Do not copy a utility locally, create a forwarding wrapper, or change semantics
|
|
159
|
+
just to reuse a similarly named function.
|
|
160
|
+
|
|
161
|
+
Separate the decisions for functions and types: reusable functions belong to Utility when general;
|
|
162
|
+
repo-local type groups belong to `src/types/`; repo-crossing types belong to Contracts. Respect
|
|
163
|
+
release boundaries and obtain approval for additional package changes when they exceed the task.
|
|
119
164
|
|
|
120
165
|
This skill defines the target architecture. Schedule repository migrations separately and in this
|
|
121
166
|
order: Studio, Deploy, Infra, Repository, Navigator.
|
|
@@ -25,7 +25,7 @@ jobs:
|
|
|
25
25
|
(github.event.pull_request.user.login == 'renovate[bot]' || github.event.pull_request.user.login == 'ankhorage-renovate-sync[bot]') &&
|
|
26
26
|
github.event.pull_request.head.repo.full_name == github.repository &&
|
|
27
27
|
startsWith(github.event.pull_request.head.ref, 'renovate/')
|
|
28
|
-
uses: ankhorage/renovate/.github/workflows/changeset.yml@
|
|
28
|
+
uses: ankhorage/renovate/.github/workflows/changeset.yml@db48610ed5bc6a1191798b123ce86419571d7bc6
|
|
29
29
|
with:
|
|
30
30
|
renovate_sync_client_id: ${{ vars.ANKHORAGE_RENOVATE_SYNC_CLIENT_ID }}
|
|
31
31
|
secrets:
|
package/package.json
CHANGED