@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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@collective-intelligence/lint",
3
- "version": "0.1.24",
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": "d34b4b06bb1d6cc9cfb4594b57675729177c2707"
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/modules/<name> a domain capability that several features need
23
+ packages/entities/<name> one business entity that several features need
24
24
  ↓
25
- packages/foundation/<name> generic machinery
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 foundation and tooling packages import each other. A feature reaches another
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
- - Foundation carries no product terms (domain nouns, product copy, App Role names, Capability keys):
40
- another product could use it unchanged.
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 module package.
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 `modules/`, 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 a
69
- module, apply steps 2 to 5 to that package instead.
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 a module,
77
- foundation or tooling package.
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 module `./ci` and checks each grant against them:
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:foundation` and `tier:tooling`
18
- also allow themselves.
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:modules", "tier:foundation", "tier:tooling"]
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 module → feature.
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 module packages share one shape. Each subpath is a folder under `src/` with one
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 foundation ui package, reading data through the typed client and TanStack Query. | the app |
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 foundation access package.
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. Generic machinery with no product terms → `foundation`: the Effect runtime bridge, sign-in and
12
- access checks, actor and slot state, form lifecycle, env validation, the shared ui kit
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. A domain capability that two or more features need, with its own CI resources, data and views
19
- (for example customer membership and a customer selector) → `modules`.
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 foundation code needs a product type, such as the Capability key union, make it generic over
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 a
43
- module when a second feature needs it.
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
- - A module needs feature behavior: the module exposes a prop, slot or callback, and the app passes the
55
- feature part in. When several features need the same behavior, move it down into the module.
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.