@collective-intelligence/lint 0.1.22 → 0.1.24

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/README.md CHANGED
@@ -64,6 +64,13 @@ A JSON config works the same way:
64
64
 
65
65
  The `RuleName` type lists every rule name.
66
66
 
67
+ ## Agent skill
68
+
69
+ The package ships the agent skill `ci-solution-structure` at
70
+ `skills/ci-solution-structure/SKILL.md`. In a Harness Intelligence repository,
71
+ the `collective-intelligence` pack installs the skill and adds the plugin with
72
+ `ci-solution/package-entrypoint` to the managed lint config.
73
+
67
74
  ## Rules
68
75
 
69
76
  | Rule | Enforces | Group |
package/package.json CHANGED
@@ -1,12 +1,13 @@
1
1
  {
2
2
  "name": "@collective-intelligence/lint",
3
- "version": "0.1.22",
3
+ "version": "0.1.24",
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,
7
7
  "files": [
8
8
  "dist",
9
- "README.md"
9
+ "README.md",
10
+ "skills"
10
11
  ],
11
12
  "main": "./dist/index.js",
12
13
  "types": "./dist/index.d.ts",
@@ -43,9 +44,9 @@
43
44
  "devDependencies": {
44
45
  "bun-types": "^1.4.2",
45
46
  "oxfmt": "0.66.0",
46
- "oxlint": "1.82.0",
47
+ "oxlint": "1.90.0",
47
48
  "typescript": "7.0.2",
48
49
  "ultracite": "7.10.7"
49
50
  },
50
- "gitHead": "8d0c8394f5f2ff047131abc8eaf39059cf3c423e"
51
+ "gitHead": "d34b4b06bb1d6cc9cfb4594b57675729177c2707"
51
52
  }
@@ -0,0 +1,117 @@
1
+ ---
2
+ name: ci-solution-structure
3
+ description: |
4
+ Collective Intelligence (CI) solution turborepo structure: tiers, package shape and composition.
5
+ Use when creating, moving, splitting or reviewing a solution workspace package, adding a package
6
+ subpath, declaring CI resources, Capabilities, App Roles or Realtime Topics, or fixing
7
+ `turbo boundaries` or `ci-solution/*` lint errors.
8
+ ---
9
+
10
+ # CI Solution Structure
11
+
12
+ A CI solution is a turborepo. Each workspace package lives at `packages/<tier>/<name>` and has
13
+ exactly one tier. Imports follow the Stable Dependencies Principle and point down the arrows; an
14
+ import may skip tiers:
15
+
16
+ ```text
17
+ apps/* composition roots: routes, app API, server root, deploy declaration
18
+ ↓
19
+ packages/organization/<name> CI identity: App Roles → Capabilities, groups, External Apps
20
+ ↓
21
+ packages/features/<name> one user-visible capability
22
+ ↓
23
+ packages/modules/<name> a domain capability that several features need
24
+ ↓
25
+ packages/foundation/<name> generic machinery
26
+
27
+ packages/tooling/<name> shared config and build tools; every tier imports it
28
+ ```
29
+
30
+ ## Invariants
31
+
32
+ - Package names are flat: `packages/features/invoicing` is `@acme/invoicing`. Only the folder shows
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.
36
+ - The app composes cross-domain needs: each package exports its view or headless part, and the app
37
+ places the parts side by side.
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.
41
+ - Each package declares its own CI resources and Capabilities (CI App Permissions) in `./ci`. Only
42
+ the organization package names App Roles and grants Capabilities to them.
43
+ - `apps/extensions` is a pure composition root: `src/index.ts` passes the organization package and
44
+ every package `./ci` to `declarePackage`.
45
+ - The CI SDKs own the realtime transport. A package contributes only Realtime Topic definitions, in
46
+ `./headless`.
47
+ - Every workspace has a `turbo.json` with exactly one `tier:*` tag; `turbo boundaries` checks only
48
+ tagged workspaces.
49
+
50
+ ## References
51
+
52
+ - [Tiers](references/tiers.md): read when you choose the tier for new, moved or split code, decide
53
+ whether a new package is worth it, or compose a cross-domain need.
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.
56
+ - [Composition](references/composition.md): read when you change the organization package, App
57
+ Roles, groups, External Apps or `apps/extensions`.
58
+ - [Enforcement](references/enforcement.md): read when you add a workspace, edit tier tags or the root
59
+ boundaries table, configure `@collective-intelligence/lint`, or fix a `turbo boundaries` or
60
+ `ci-solution/*` error.
61
+
62
+ ## Workflow: add a feature package
63
+
64
+ 1. Read [Tiers](references/tiers.md). Scan the sibling packages in `features/` and `modules/`, and
65
+ classify the behavior by invariant owner and domain-worthiness.
66
+
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.
70
+
71
+ 2. Read [Package shape](references/package-shape.md). Create `packages/features/<name>` with only the
72
+ subpaths the feature needs, one `exports` entry per subpath, and a `turbo.json` tagged
73
+ `tier:features`.
74
+
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.
78
+
79
+ 3. Read [Composition](references/composition.md). Declare the CI resources and Capability keys in
80
+ `./ci` and the Realtime Topics in `./headless`. Grant the new Capabilities to App Roles in the
81
+ organization package, and add the `./ci` components to `apps/extensions`.
82
+
83
+ **Complete when:** every new Capability is granted to at least one App Role or reported as
84
+ intentionally unassigned, `apps/extensions/src/index.ts` and `apps/extensions/package.json`
85
+ include the package, and the organization package `version` is bumped.
86
+
87
+ 4. Compose the package in each app that uses it: the `./api` group into the app API, the `./server`
88
+ Layer into the server root, the `./views` exports into routes or pages.
89
+
90
+ **Complete when:** each app wires every subpath it needs, through exported subpaths only.
91
+
92
+ 5. Run `turbo boundaries` and the repository lint, type-check and test scripts.
93
+
94
+ **Complete when:** every command passes, or each failure that predates the change is reported
95
+ with its file, line and rule.
96
+
97
+ ## Workflow: review a package change
98
+
99
+ 1. List every changed workspace and file. Map each workspace to its tier and each file to its
100
+ subpath or to package configuration.
101
+
102
+ **Complete when:** every changed file has exactly one tier and one subpath or configuration role.
103
+
104
+ 2. Classify every added or changed import against the tier direction, the
105
+ [subpath direction](references/package-shape.md#subpath-direction) and the exported subpaths.
106
+
107
+ **Complete when:** every import in scope is marked allowed or violation, with file and line.
108
+
109
+ 3. Check the change against every [invariant](#invariants).
110
+
111
+ **Complete when:** each invariant has a pass, fail or not-applicable result with current
112
+ evidence.
113
+
114
+ 4. Run `turbo boundaries` and the lint on the changed workspaces.
115
+
116
+ **Complete when:** every violation from steps 2 to 4 cites file, line and the violated rule, and
117
+ names the tier, package or subpath that resolves it.
@@ -0,0 +1,63 @@
1
+ # Organization Package and `apps/extensions`
2
+
3
+ The solution deploys to CI as one Extension Package.
4
+
5
+ ## Organization package
6
+
7
+ `packages/organization/<name>` (tag `tier:organization`) owns:
8
+
9
+ - the package identity: FQN, display name and `version`. Bump `version` by hand on every change of a
10
+ declaration. The FQN is a constant, because it cannot be a Package Variable;
11
+ - the Package Variables: origins and callback URLs, never credentials;
12
+ - the Organization settings;
13
+ - the App Roles: each App Role lists its Capabilities (`appPermissions`) and its platform permissions
14
+ (`platformPermissions`, for example `knowledge:read` and `knowledge:write`);
15
+ - one Organization Group per App Role, bound to the App Role with a group binding;
16
+ - one External App per frontend (`declareExternalApplication`), which carries the App Roles and group
17
+ bindings.
18
+
19
+ It imports the Capability keys from each feature and module `./ci` and checks each grant against them:
20
+
21
+ ```ts
22
+ import type { InvoicingCapability } from "@acme/invoicing/ci"
23
+
24
+ const accountantCapabilities = [
25
+ "invoicing:read",
26
+ "invoicing:write"
27
+ ] as const satisfies readonly InvoicingCapability[]
28
+ ```
29
+
30
+ It exports what the deploy declaration needs, for example `packageManifest`, `variables` and
31
+ `organizationComponents` (the components in deploy order).
32
+
33
+ ## `apps/extensions`
34
+
35
+ `apps/extensions/src` holds only `index.ts` and the media files it deploys:
36
+
37
+ ```ts
38
+ import { declarePackage } from "@collective-intelligence/extensions-sdk"
39
+ import { customerComponents } from "@acme/customer/ci"
40
+ import { invoicingComponents } from "@acme/invoicing/ci"
41
+ import {
42
+ organizationComponents,
43
+ packageManifest,
44
+ variables
45
+ } from "@acme/organization"
46
+
47
+ export default declarePackage({
48
+ components: [
49
+ ...organizationComponents,
50
+ ...customerComponents,
51
+ ...invoicingComponents
52
+ ],
53
+ manifest: packageManifest,
54
+ variables
55
+ })
56
+ ```
57
+
58
+ - `apps/extensions/package.json` lists the organization package and every imported package as
59
+ `workspace:*` dependencies.
60
+ - `ci deploy --declaration ./src/index.ts` bundles every workspace import into the release asset; only
61
+ the SDK host modules stay external. Code that `./ci` pulls in ships in that asset.
62
+ - Package Media paths such as `media/logo.png` resolve next to the declaration module, so media files
63
+ stay in `apps/extensions/src/media`.
@@ -0,0 +1,80 @@
1
+ # Enforcement
2
+
3
+ `turbo boundaries` checks the direction between packages. `@collective-intelligence/lint` checks the
4
+ folders and imports inside and into a package.
5
+
6
+ ## `turbo boundaries`
7
+
8
+ The root `package.json` workspace globs `["apps/*", "packages/*/*"]` make every tier folder entry a
9
+ workspace. Each workspace `turbo.json` extends the root and carries exactly one tier tag (`tier:app`
10
+ for `apps/*`):
11
+
12
+ ```json
13
+ { "extends": ["//"], "tags": ["tier:features"] }
14
+ ```
15
+
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.
19
+
20
+ ```json
21
+ {
22
+ "boundaries": {
23
+ "implicitDependencies": ["server-only"],
24
+ "tags": {
25
+ "tier:features": {
26
+ "dependencies": {
27
+ "allow": ["tier:modules", "tier:foundation", "tier:tooling"]
28
+ }
29
+ }
30
+ }
31
+ }
32
+ }
33
+ ```
34
+
35
+ - `implicitDependencies: ["server-only"]`: server code imports the `server-only` marker module that
36
+ the framework supplies, without a `package.json` entry. Without this line `turbo boundaries` reports
37
+ it as an undeclared dependency.
38
+ - `turbo boundaries` also reports an import of a file outside the package directory and an import of
39
+ a package that `package.json` does not declare.
40
+ - An untagged workspace has no rule, so `turbo boundaries` never checks its imports. Close the gap
41
+ with two repository tests: one reads the root workspace globs and fails unless every workspace has
42
+ a `turbo.json` that extends `//` and carries exactly one known tier tag; one runs
43
+ `turbo boundaries` on a throwaway fixture workspace with the real root table and expects a failure
44
+ for feature → feature and module → feature.
45
+ - Run `turbo boundaries` in the repository `check` script.
46
+
47
+ Read the error `` Package `@acme/a` found without any tag listed in allowlist for `@acme/b` `` as:
48
+ `@acme/b` imports `@acme/a` against the direction. Move the shared part down a tier, or compose both
49
+ packages in the app (see [Tiers](tiers.md#cross-domain-composition)).
50
+
51
+ ## `@collective-intelligence/lint`
52
+
53
+ An oxlint plugin. Install it with `oxlint` as dev dependencies, and extend the `recommended` config
54
+ in each lint scope's `oxlint.config.ts`:
55
+
56
+ ```ts
57
+ import { recommended } from "@collective-intelligence/lint"
58
+ import { defineConfig } from "oxlint"
59
+
60
+ export default defineConfig({ extends: [recommended] })
61
+ ```
62
+
63
+ In a repository that Harness Intelligence manages, the `collective-intelligence` pack adds the plugin
64
+ and `ci-solution/package-entrypoint` to the managed lint config of every scope, so apps need no
65
+ plugin setup. Each solution package (`packages/<tier>/<name>`) still extends `recommended` in its
66
+ `oxlint.local.ts` for the three solution-layout rules. Outside Harness Intelligence, extend
67
+ `recommended` as shown.
68
+
69
+ `recommended` enables every rule as an error. Each rule enforces one part of the
70
+ [package shape](package-shape.md):
71
+
72
+ | Rule | Enforces |
73
+ | -------------------------------- | ---------------------------------------------------------------------- |
74
+ | `ci-solution/package-entrypoint` | Cross-package imports target an exported subpath. |
75
+ | `ci-solution/subpath-imports` | The [subpath direction](package-shape.md#subpath-direction). |
76
+ | `ci-solution/subpath-entrypoint` | An import into another subpath targets the folder or its `index` file. |
77
+ | `ci-solution/subpath-index` | Every subpath folder under `src/` has an `index.ts` or `index.tsx`. |
78
+
79
+ `package-entrypoint` finds each package through `node_modules`, so the package manager must link the
80
+ workspace packages. The package documentation is the authority for rule options.
@@ -0,0 +1,105 @@
1
+ # Package Shape
2
+
3
+ Feature and module packages share one shape. Each subpath is a folder under `src/` with one
4
+ `index.ts` or `index.tsx` entrypoint and one `package.json` `exports` entry. Create only the
5
+ subpaths the package needs.
6
+
7
+ ```text
8
+ packages/features/invoicing/ @acme/invoicing
9
+ ├── package.json
10
+ ├── turbo.json tier:features
11
+ └── src/
12
+ ├── ci/index.ts
13
+ ├── domain/index.ts
14
+ ├── api/index.ts
15
+ ├── server/index.ts
16
+ ├── headless/index.ts
17
+ └── views/index.ts
18
+ ```
19
+
20
+ ```json
21
+ {
22
+ "exports": {
23
+ "./ci": "./src/ci/index.ts",
24
+ "./domain": "./src/domain/index.ts",
25
+ "./api": "./src/api/index.ts",
26
+ "./server": "./src/server/index.ts",
27
+ "./headless": "./src/headless/index.ts",
28
+ "./views": "./src/views/index.ts"
29
+ }
30
+ }
31
+ ```
32
+
33
+ `exports` lists only subpaths, with no root `.` entry.
34
+
35
+ ## Subpaths
36
+
37
+ | Subpath | Holds | Consumers |
38
+ | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
39
+ | `ci/` | Config-as-code CI resources declared with `@collective-intelligence/extensions-sdk` (`declareKnowledgeEntitySchema`, `declareKnowledgePolicy` and others), and the Capability keys. | organization package, `apps/extensions` |
40
+ | `domain/` | Effect Schema models, branded ids, pure rules, domain errors. No runtime concerns. | every other subpath, other packages |
41
+ | `api/` | The Effect `HttpApiGroup` contract: endpoints with payload, success and error schemas from `domain/`. | the app API, the typed client in `views/` |
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
+ | `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 |
45
+
46
+ `ci/` ships in the deploy bundle (see [Composition](composition.md)), so it holds declarations only:
47
+ the extensions SDK and constants from `domain/`.
48
+
49
+ When the repository installs `effect-backend-structure` and `frontend-domain-structure`, they own the
50
+ inside of `server/` and `views/`; this skill owns the package boundary around them.
51
+
52
+ ## Subpath direction
53
+
54
+ | Folder | Must not import |
55
+ | ----------- | --------------------------------------- |
56
+ | `domain/` | `server/`, `views/`, `headless/`, `ci/` |
57
+ | `ci/` | `views/`, `headless/` |
58
+ | `headless/` | `server/` |
59
+ | `views/` | `server/` |
60
+ | `api/` | no limit |
61
+ | `server/` | no limit |
62
+
63
+ An import into another subpath targets its folder or its `index` file. Imports inside one subpath are
64
+ free.
65
+
66
+ ## Capabilities
67
+
68
+ A package defines its Capability keys in `ci/` as an `as const` list and exports the key type:
69
+
70
+ ```ts
71
+ export const invoicingCapabilities = [
72
+ "invoicing:read",
73
+ "invoicing:write",
74
+ "invoicing:approve"
75
+ ] as const
76
+
77
+ export type InvoicingCapability = (typeof invoicingCapabilities)[number]
78
+ ```
79
+
80
+ `server/` handlers and `views/` controls gate on these keys through the foundation access package.
81
+
82
+ ## Realtime Topics
83
+
84
+ The CI SDKs own the transport:
85
+
86
+ - `@collective-intelligence/external-apps-client-sdk`: `createRealtimeClient`, the topic registry and
87
+ the stream lifecycle.
88
+ - `@collective-intelligence/external-apps-client-sdk-react`: `RealtimeProvider` and
89
+ `useRealtimeTopic(topic, onChanges)`.
90
+ - `@collective-intelligence/external-apps-server-sdk`: the `realtime` option of the BFF handlers
91
+ mounts the ticket route `POST {basePath}/realtime/ticket`.
92
+
93
+ The app mounts `RealtimeProvider` and the ticket route once. A package defines its topics in
94
+ `headless/`. A topic names one CI entity schema and an optional equality filter on one data path:
95
+
96
+ ```ts
97
+ export const invoicesOfCustomer = (customerId: string) => ({
98
+ schema: "acme.invoicing.invoice",
99
+ filter: { field: "customer", eq: customerId }
100
+ })
101
+ ```
102
+
103
+ A widget registers the topic with `useRealtimeTopic`. Events carry ids only, so `onChanges`
104
+ invalidates the widget queries and the data reloads through the package `api/`. The client
105
+ delivers the changes of a tab in one jittered batch, so a burst of changes refetches once.
@@ -0,0 +1,55 @@
1
+ # Tiers
2
+
3
+ ## Choosing a tier
4
+
5
+ Start with the **invariant owner**: the smallest stable domain responsible for the behavior, its
6
+ rules, and the changes that must stay coherent. A route name, a screen region, a file type or a reuse
7
+ count alone does not establish ownership.
8
+
9
+ Classify in this order; the first match owns the code:
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
13
+ (primitives, shadcn components, theme).
14
+ 2. Shared TypeScript, lint or build configuration → `tooling`.
15
+ 3. Solution-wide CI identity → `organization`: package identity, Package Variables, Organization
16
+ settings, App Roles and their Capability grants, groups, External Apps. See
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`.
20
+ 5. One user-visible capability with its workflow, policy, state, data, CI resources and screens →
21
+ `features`.
22
+ 6. Routes, layouts, the app API, the server root, and the wiring of several packages for one surface
23
+ (a page, a home dashboard, a global search) → the app.
24
+
25
+ A detail with no independent invariant stays with its current owner. Prefer the narrowest honest
26
+ owner; move code to a broader owner only when that owner truly governs it.
27
+
28
+ When foundation code needs a product type, such as the Capability key union, make it generic over
29
+ that type. The app binds the type from the organization package.
30
+
31
+ ## Domain-worthiness
32
+
33
+ Before you create or split a package, **scan the siblings** in the target tier. Compare invariant
34
+ owner, product language, workflow, change cadence and consumers. Extend or rename an existing package
35
+ when it already covers the responsibility.
36
+
37
+ A new package is worthy when it has a coherent responsibility, a stable name and at least one real
38
+ boundary: independent policy, lifecycle, state, workflow, CI resources, a consumer contract or reuse
39
+ scope. File count is no boundary. Reject a navigational split, such as one package per panel, button
40
+ or page fragment.
41
+
42
+ A supporting concept (comments, attachments, tags) stays inside its first feature. It becomes a
43
+ module when a second feature needs it.
44
+
45
+ ## Cross-domain composition
46
+
47
+ When one surface needs parts of two packages, each package exports its part and the app composes
48
+ them:
49
+
50
+ - A home page shows an invoice summary: `@acme/invoicing/views` exports `InvoiceSummaryBox`; the app
51
+ places it on the home page.
52
+ - A global search lists invoices: `@acme/invoicing/headless` exports `invoiceSearchSource`; the app
53
+ 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.