@collective-intelligence/lint 0.1.24 → 0.1.25
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.
- package/package.json +2 -2
- package/skills/ci-solution-structure/SKILL.md +12 -12
- package/skills/ci-solution-structure/references/composition.md +1 -1
- package/skills/ci-solution-structure/references/enforcement.md +17 -4
- package/skills/ci-solution-structure/references/package-shape.md +3 -3
- package/skills/ci-solution-structure/references/tiers.md +11 -9
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@collective-intelligence/lint",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.25",
|
|
4
4
|
"description": "Oxlint plugin with the Collective Intelligence lint rules: package boundaries and solution package layout.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"sideEffects": false,
|
|
@@ -48,5 +48,5 @@
|
|
|
48
48
|
"typescript": "7.0.2",
|
|
49
49
|
"ultracite": "7.10.7"
|
|
50
50
|
},
|
|
51
|
-
"gitHead": "
|
|
51
|
+
"gitHead": "a2aa507323bc6d3ce0ef6d3e460f28573ef40dd8"
|
|
52
52
|
}
|
|
@@ -20,9 +20,9 @@ packages/organization/<name> CI identity: App Roles → Capabilities, groups,
|
|
|
20
20
|
↓
|
|
21
21
|
packages/features/<name> one user-visible capability
|
|
22
22
|
↓
|
|
23
|
-
packages/
|
|
23
|
+
packages/entities/<name> one business entity that several features need
|
|
24
24
|
↓
|
|
25
|
-
packages/
|
|
25
|
+
packages/modules/<name> business-agnostic machinery
|
|
26
26
|
|
|
27
27
|
packages/tooling/<name> shared config and build tools; every tier imports it
|
|
28
28
|
```
|
|
@@ -31,13 +31,13 @@ packages/tooling/<name> shared config and build tools; every tier imports
|
|
|
31
31
|
|
|
32
32
|
- Package names are flat: `packages/features/invoicing` is `@acme/invoicing`. Only the folder shows
|
|
33
33
|
the tier.
|
|
34
|
-
- Inside one tier, only
|
|
35
|
-
feature only through the app.
|
|
34
|
+
- Inside one tier, only modules and tooling packages import each other. A feature reaches another
|
|
35
|
+
feature only through the app; an entity never imports another entity.
|
|
36
36
|
- The app composes cross-domain needs: each package exports its view or headless part, and the app
|
|
37
37
|
places the parts side by side.
|
|
38
38
|
- Every cross-package import targets an exported subpath, such as `@acme/invoicing/views`.
|
|
39
|
-
-
|
|
40
|
-
another product could use
|
|
39
|
+
- Modules carry no product terms (domain nouns, product copy, App Role names, Capability keys):
|
|
40
|
+
another product could use them unchanged.
|
|
41
41
|
- Each package declares its own CI resources and Capabilities (CI App Permissions) in `./ci`. Only
|
|
42
42
|
the organization package names App Roles and grants Capabilities to them.
|
|
43
43
|
- `apps/extensions` is a pure composition root: `src/index.ts` passes the organization package and
|
|
@@ -52,7 +52,7 @@ packages/tooling/<name> shared config and build tools; every tier imports
|
|
|
52
52
|
- [Tiers](references/tiers.md): read when you choose the tier for new, moved or split code, decide
|
|
53
53
|
whether a new package is worth it, or compose a cross-domain need.
|
|
54
54
|
- [Package shape](references/package-shape.md): read when you add or change a subpath, `exports`, a
|
|
55
|
-
Capability or a Realtime Topic in a feature or
|
|
55
|
+
Capability or a Realtime Topic in a feature or entity package.
|
|
56
56
|
- [Composition](references/composition.md): read when you change the organization package, App
|
|
57
57
|
Roles, groups, External Apps or `apps/extensions`.
|
|
58
58
|
- [Enforcement](references/enforcement.md): read when you add a workspace, edit tier tags or the root
|
|
@@ -61,20 +61,20 @@ packages/tooling/<name> shared config and build tools; every tier imports
|
|
|
61
61
|
|
|
62
62
|
## Workflow: add a feature package
|
|
63
63
|
|
|
64
|
-
1. Read [Tiers](references/tiers.md). Scan the sibling packages in `features/` and `
|
|
64
|
+
1. Read [Tiers](references/tiers.md). Scan the sibling packages in `features/` and `entities/`, and
|
|
65
65
|
classify the behavior by invariant owner and domain-worthiness.
|
|
66
66
|
|
|
67
67
|
**Complete when:** you name the invariant owner, every sibling you compared, and the real
|
|
68
|
-
boundary that makes a new feature package correct. When the owner is an existing package or
|
|
69
|
-
|
|
68
|
+
boundary that makes a new feature package correct. When the owner is an existing package or an
|
|
69
|
+
entity, apply steps 2 to 5 to that package instead.
|
|
70
70
|
|
|
71
71
|
2. Read [Package shape](references/package-shape.md). Create `packages/features/<name>` with only the
|
|
72
72
|
subpaths the feature needs, one `exports` entry per subpath, and a `turbo.json` tagged
|
|
73
73
|
`tier:features`.
|
|
74
74
|
|
|
75
75
|
**Complete when:** every folder under `src/` has an `index.ts` or `index.tsx` and exactly one
|
|
76
|
-
`exports` entry, `exports` has no other entry, and every cross-package import targets
|
|
77
|
-
|
|
76
|
+
`exports` entry, `exports` has no other entry, and every cross-package import targets an entity,
|
|
77
|
+
module or tooling package.
|
|
78
78
|
|
|
79
79
|
3. Read [Composition](references/composition.md). Declare the CI resources and Capability keys in
|
|
80
80
|
`./ci` and the Realtime Topics in `./headless`. Grant the new Capabilities to App Roles in the
|
|
@@ -16,7 +16,7 @@ The solution deploys to CI as one Extension Package.
|
|
|
16
16
|
- one External App per frontend (`declareExternalApplication`), which carries the App Roles and group
|
|
17
17
|
bindings.
|
|
18
18
|
|
|
19
|
-
It imports the Capability keys from each feature and
|
|
19
|
+
It imports the Capability keys from each feature and entity `./ci` and checks each grant against them:
|
|
20
20
|
|
|
21
21
|
```ts
|
|
22
22
|
import type { InvoicingCapability } from "@acme/invoicing/ci"
|
|
@@ -14,8 +14,8 @@ for `apps/*`):
|
|
|
14
14
|
```
|
|
15
15
|
|
|
16
16
|
The root `turbo.json` `boundaries.tags` table encodes the tier diagram in [SKILL.md](../SKILL.md):
|
|
17
|
-
each tier tag allows every tier below it and `tier:tooling`; `tier:
|
|
18
|
-
|
|
17
|
+
each tier tag allows every tier below it and `tier:tooling`; `tier:modules` and `tier:tooling` also
|
|
18
|
+
allow themselves.
|
|
19
19
|
|
|
20
20
|
```json
|
|
21
21
|
{
|
|
@@ -24,7 +24,7 @@ also allow themselves.
|
|
|
24
24
|
"tags": {
|
|
25
25
|
"tier:features": {
|
|
26
26
|
"dependencies": {
|
|
27
|
-
"allow": ["tier:
|
|
27
|
+
"allow": ["tier:entities", "tier:modules", "tier:tooling"]
|
|
28
28
|
}
|
|
29
29
|
}
|
|
30
30
|
}
|
|
@@ -41,13 +41,26 @@ also allow themselves.
|
|
|
41
41
|
with two repository tests: one reads the root workspace globs and fails unless every workspace has
|
|
42
42
|
a `turbo.json` that extends `//` and carries exactly one known tier tag; one runs
|
|
43
43
|
`turbo boundaries` on a throwaway fixture workspace with the real root table and expects a failure
|
|
44
|
-
for feature → feature and
|
|
44
|
+
for feature → feature, entity → entity and entity → feature.
|
|
45
45
|
- Run `turbo boundaries` in the repository `check` script.
|
|
46
46
|
|
|
47
47
|
Read the error `` Package `@acme/a` found without any tag listed in allowlist for `@acme/b` `` as:
|
|
48
48
|
`@acme/b` imports `@acme/a` against the direction. Move the shared part down a tier, or compose both
|
|
49
49
|
packages in the app (see [Tiers](tiers.md#cross-domain-composition)).
|
|
50
50
|
|
|
51
|
+
### Migrating from `foundation`
|
|
52
|
+
|
|
53
|
+
Earlier versions named the business-agnostic tier `foundation` and the shared domain tier
|
|
54
|
+
`modules`. To migrate a solution:
|
|
55
|
+
|
|
56
|
+
1. Move `packages/modules/*` to `packages/entities/*` and retag each workspace `tier:entities`.
|
|
57
|
+
2. Move `packages/foundation/*` to `packages/modules/*` and retag each workspace `tier:modules`.
|
|
58
|
+
3. Rewrite the root `turbo.json` `boundaries.tags` table with the new tags, and update repository
|
|
59
|
+
tests that list tier tags.
|
|
60
|
+
|
|
61
|
+
Package names stay flat, so imports do not change. `@collective-intelligence/lint` reads no tier
|
|
62
|
+
tag; old tags keep linting until you migrate.
|
|
63
|
+
|
|
51
64
|
## `@collective-intelligence/lint`
|
|
52
65
|
|
|
53
66
|
An oxlint plugin. Install it with `oxlint` as dev dependencies, and extend the `recommended` config
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Package Shape
|
|
2
2
|
|
|
3
|
-
Feature and
|
|
3
|
+
Feature and entity packages share one shape. Each subpath is a folder under `src/` with one
|
|
4
4
|
`index.ts` or `index.tsx` entrypoint and one `package.json` `exports` entry. Create only the
|
|
5
5
|
subpaths the package needs.
|
|
6
6
|
|
|
@@ -41,7 +41,7 @@ packages/features/invoicing/ @acme/invoicing
|
|
|
41
41
|
| `api/` | The Effect `HttpApiGroup` contract: endpoints with payload, success and error schemas from `domain/`. | the app API, the typed client in `views/` |
|
|
42
42
|
| `server/` | The handlers of the `api/` group and the Layer that provides them. Calls CI as the signed-in user. | the app server root only |
|
|
43
43
|
| `headless/` | UI state without rendering: actors (UI state only; server data stays in queries), hooks, query keys, search sources, Realtime Topic definitions. | `views/`, the app |
|
|
44
|
-
| `views/` | Wired screens and widgets built on the shared
|
|
44
|
+
| `views/` | Wired screens and widgets built on the shared UI package, reading data through the typed client and TanStack Query. | the app |
|
|
45
45
|
|
|
46
46
|
`ci/` ships in the deploy bundle (see [Composition](composition.md)), so it holds declarations only:
|
|
47
47
|
the extensions SDK and constants from `domain/`.
|
|
@@ -77,7 +77,7 @@ export const invoicingCapabilities = [
|
|
|
77
77
|
export type InvoicingCapability = (typeof invoicingCapabilities)[number]
|
|
78
78
|
```
|
|
79
79
|
|
|
80
|
-
`server/` handlers and `views/` controls gate on these keys through the
|
|
80
|
+
`server/` handlers and `views/` controls gate on these keys through the access module package.
|
|
81
81
|
|
|
82
82
|
## Realtime Topics
|
|
83
83
|
|
|
@@ -8,15 +8,16 @@ count alone does not establish ownership.
|
|
|
8
8
|
|
|
9
9
|
Classify in this order; the first match owns the code:
|
|
10
10
|
|
|
11
|
-
1.
|
|
12
|
-
access checks, actor and slot state, form lifecycle, env validation, the shared
|
|
11
|
+
1. Business-agnostic machinery with no product terms → `modules`: the Effect runtime bridge, sign-in
|
|
12
|
+
and access checks, actor and slot state, form lifecycle, env validation, the shared UI package
|
|
13
13
|
(primitives, shadcn components, theme).
|
|
14
14
|
2. Shared TypeScript, lint or build configuration → `tooling`.
|
|
15
15
|
3. Solution-wide CI identity → `organization`: package identity, Package Variables, Organization
|
|
16
16
|
settings, App Roles and their Capability grants, groups, External Apps. See
|
|
17
17
|
[Composition](composition.md).
|
|
18
|
-
4.
|
|
19
|
-
(for example customer
|
|
18
|
+
4. One business entity that two or more features need, with its own contract, CI resources, data
|
|
19
|
+
and entity views (for example the customer entity and a customer selector) → `entities`. Logic
|
|
20
|
+
that combines two entities is a feature.
|
|
20
21
|
5. One user-visible capability with its workflow, policy, state, data, CI resources and screens →
|
|
21
22
|
`features`.
|
|
22
23
|
6. Routes, layouts, the app API, the server root, and the wiring of several packages for one surface
|
|
@@ -25,7 +26,7 @@ Classify in this order; the first match owns the code:
|
|
|
25
26
|
A detail with no independent invariant stays with its current owner. Prefer the narrowest honest
|
|
26
27
|
owner; move code to a broader owner only when that owner truly governs it.
|
|
27
28
|
|
|
28
|
-
When
|
|
29
|
+
When module code needs a product type, such as the Capability key union, make it generic over
|
|
29
30
|
that type. The app binds the type from the organization package.
|
|
30
31
|
|
|
31
32
|
## Domain-worthiness
|
|
@@ -39,8 +40,8 @@ boundary: independent policy, lifecycle, state, workflow, CI resources, a consum
|
|
|
39
40
|
scope. File count is no boundary. Reject a navigational split, such as one package per panel, button
|
|
40
41
|
or page fragment.
|
|
41
42
|
|
|
42
|
-
A supporting concept (comments, attachments, tags) stays inside its first feature. It becomes
|
|
43
|
-
|
|
43
|
+
A supporting concept (comments, attachments, tags) stays inside its first feature. It becomes an
|
|
44
|
+
entity when a second feature needs it.
|
|
44
45
|
|
|
45
46
|
## Cross-domain composition
|
|
46
47
|
|
|
@@ -51,5 +52,6 @@ them:
|
|
|
51
52
|
places it on the home page.
|
|
52
53
|
- A global search lists invoices: `@acme/invoicing/headless` exports `invoiceSearchSource`; the app
|
|
53
54
|
registers it with the search.
|
|
54
|
-
-
|
|
55
|
-
feature part in. When several features need the same behavior, move it down into
|
|
55
|
+
- An entity needs feature behavior: the entity exposes a prop, slot or callback, and the app passes
|
|
56
|
+
the feature part in. When several features need the same single-entity behavior, move it down into
|
|
57
|
+
the entity.
|