@collective-intelligence/lint 0.2.2 → 0.2.4
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 +7 -3
- package/dist/index.js +2 -2
- package/package.json +2 -2
- package/skills/ci-solution-structure/SKILL.md +13 -11
- package/skills/ci-solution-structure/references/composition.md +23 -11
- package/skills/ci-solution-structure/references/package-shape.md +20 -17
- package/skills/ci-solution-structure/references/tiers.md +2 -1
package/README.md
CHANGED
|
@@ -211,7 +211,9 @@ The rule reports each `fromPromise`, `fromCallback`, `fromObservable` and
|
|
|
211
211
|
`fromEventObservable` that an import, a re-export or a namespace import
|
|
212
212
|
(`XState.fromPromise`, `XState["fromPromise"]`,
|
|
213
213
|
`const { fromPromise } = XState`) takes from `xstate` or `xstate/*`. Make side-effect actors with `fromEffect` from
|
|
214
|
-
`@collective-intelligence/external-apps-client-sdk-react/effect
|
|
214
|
+
`@collective-intelligence/external-apps-client-sdk-react/effect` in a detached
|
|
215
|
+
app, or from `@collective-intelligence/extensions-sdk-frontend-react/effect` in
|
|
216
|
+
a hosted Studio Widget. Machines and
|
|
215
217
|
`fromTransition` actors have no side effects and are not reported. A local name
|
|
216
218
|
that shadows the namespace import, such as a parameter named `XState`, is not
|
|
217
219
|
reported.
|
|
@@ -221,8 +223,10 @@ reported.
|
|
|
221
223
|
The rule reports each `useMutation` that an import, a re-export or a namespace
|
|
222
224
|
import (`ReactQuery.useMutation`, `ReactQuery["useMutation"]`,
|
|
223
225
|
`const { useMutation } = ReactQuery`) takes from `@tanstack/react-query`. Write through a `fromEffect` actor from
|
|
224
|
-
`@collective-intelligence/external-apps-client-sdk-react/effect
|
|
225
|
-
|
|
226
|
+
`@collective-intelligence/external-apps-client-sdk-react/effect` in a detached
|
|
227
|
+
app, or from `@collective-intelligence/extensions-sdk-frontend-react/effect` in
|
|
228
|
+
a hosted Studio Widget; after the write, the actor refreshes reads through the
|
|
229
|
+
`QueryCache` of the same entrypoint (`invalidate`, `setData`).
|
|
226
230
|
|
|
227
231
|
The rule checks every module. `useMutation` runs only during a React render,
|
|
228
232
|
so a module that takes it is a view, a hook or a helper of one of them.
|
package/dist/index.js
CHANGED
|
@@ -104,7 +104,7 @@ var SIDE_EFFECT_ACTORS = new Set([
|
|
|
104
104
|
"fromPromise"
|
|
105
105
|
]);
|
|
106
106
|
var messages = {
|
|
107
|
-
sideEffectActor: "`{{name}}` makes XState actor logic outside Effect. Make the actor with `fromEffect` from `@collective-intelligence/external-apps-client-sdk-react/effect
|
|
107
|
+
sideEffectActor: "`{{name}}` makes XState actor logic outside Effect. Make the actor with `fromEffect` from `@collective-intelligence/external-apps-client-sdk-react/effect` in a detached app, or from `@collective-intelligence/extensions-sdk-frontend-react/effect` in a Studio Widget."
|
|
108
108
|
};
|
|
109
109
|
var isXState = (source) => source === "xstate" || source.startsWith("xstate/");
|
|
110
110
|
var effectActors = {
|
|
@@ -264,7 +264,7 @@ var effectSubpath = {
|
|
|
264
264
|
// src/rules/effect-writes/effect-writes.ts
|
|
265
265
|
import { defineRule as defineRule3 } from "@oxlint/plugins";
|
|
266
266
|
var messages3 = {
|
|
267
|
-
mutationHook: "`useMutation` writes outside Effect. Write through a `fromEffect` actor from `@collective-intelligence/external-apps-client-sdk-react/effect
|
|
267
|
+
mutationHook: "`useMutation` writes outside Effect. Write through a `fromEffect` actor from `@collective-intelligence/external-apps-client-sdk-react/effect` in a detached app, or from `@collective-intelligence/extensions-sdk-frontend-react/effect` in a Studio Widget; refresh reads through the `QueryCache` of the same entrypoint."
|
|
268
268
|
};
|
|
269
269
|
var isTanStackQuery = (source) => source === "@tanstack/react-query";
|
|
270
270
|
var takesTanStackQuery = (statement) => (statement.type === "ImportDeclaration" || statement.type === "ExportNamedDeclaration") && statement.source !== null && isTanStackQuery(statement.source.value);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@collective-intelligence/lint",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.4",
|
|
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": "14255a76dd7d6edd4bac3445df6b6d9fc312ca67"
|
|
52
52
|
}
|
|
@@ -3,7 +3,7 @@ name: ci-solution-structure
|
|
|
3
3
|
description: |
|
|
4
4
|
Collective Intelligence (CI) solution turborepo structure: tiers, package shape and composition.
|
|
5
5
|
Use when creating, moving, splitting or reviewing a solution workspace package, adding a package
|
|
6
|
-
subpath, declaring CI resources, Capabilities,
|
|
6
|
+
subpath, declaring CI resources, Access Capabilities, Access Profiles or Realtime Topics, or fixing
|
|
7
7
|
`turbo boundaries` or `ci-solution/*` lint errors.
|
|
8
8
|
---
|
|
9
9
|
|
|
@@ -16,7 +16,7 @@ import may skip tiers:
|
|
|
16
16
|
```text
|
|
17
17
|
apps/* composition roots: routes, app API, server root, deploy declaration
|
|
18
18
|
↓
|
|
19
|
-
packages/organization/<name> CI identity:
|
|
19
|
+
packages/organization/<name> CI identity: Access Profiles, grants, groups, External Apps
|
|
20
20
|
↓
|
|
21
21
|
packages/features/<name> one user-visible capability
|
|
22
22
|
↓
|
|
@@ -36,10 +36,11 @@ packages/tooling/<name> shared config and build tools; every tier imports
|
|
|
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
|
-
- Modules carry no product terms (domain nouns, product copy,
|
|
39
|
+
- Modules carry no product terms (domain nouns, product copy, profile names, Capability codes):
|
|
40
40
|
another product could use them unchanged.
|
|
41
|
-
- Each package declares its own CI resources
|
|
42
|
-
the organization package
|
|
41
|
+
- Each package declares its own CI resources, Access Capabilities and Knowledge Data Policies in
|
|
42
|
+
`./ci`. Only the organization package declares Access Profiles, their grants and the Max
|
|
43
|
+
Privileges of each External App.
|
|
43
44
|
- `apps/extensions` is a pure composition root: `src/index.ts` passes the organization package and
|
|
44
45
|
every package `./ci` to `declarePackage`.
|
|
45
46
|
- The CI SDKs own the realtime transport. A package contributes only Realtime Topic definitions, in
|
|
@@ -53,8 +54,8 @@ packages/tooling/<name> shared config and build tools; every tier imports
|
|
|
53
54
|
whether a new package is worth it, or compose a cross-domain need.
|
|
54
55
|
- [Package shape](references/package-shape.md): read when you add or change a subpath, `exports`, a
|
|
55
56
|
Capability or a Realtime Topic in a feature or entity package.
|
|
56
|
-
- [Composition](references/composition.md): read when you change the organization package,
|
|
57
|
-
|
|
57
|
+
- [Composition](references/composition.md): read when you change the organization package, Access
|
|
58
|
+
Profiles, grants, groups, External Apps or `apps/extensions`.
|
|
58
59
|
- [Enforcement](references/enforcement.md): read when you add a workspace, edit tier tags or the root
|
|
59
60
|
boundaries table, configure `@collective-intelligence/lint`, or fix a `turbo boundaries` or
|
|
60
61
|
`ci-solution/*` error.
|
|
@@ -76,11 +77,12 @@ packages/tooling/<name> shared config and build tools; every tier imports
|
|
|
76
77
|
`exports` entry, `exports` has no other entry, and every cross-package import targets an entity,
|
|
77
78
|
module or tooling package.
|
|
78
79
|
|
|
79
|
-
3. Read [Composition](references/composition.md). Declare the CI resources and
|
|
80
|
-
`./ci` and the Realtime Topics in `./headless`.
|
|
81
|
-
|
|
80
|
+
3. Read [Composition](references/composition.md). Declare the CI resources and Access Capabilities
|
|
81
|
+
in `./ci` and the Realtime Topics in `./headless`. Add the new Capabilities to Access Profiles
|
|
82
|
+
and to the Max Privileges of each External App that uses them in the organization package, and
|
|
83
|
+
add the `./ci` components to `apps/extensions`.
|
|
82
84
|
|
|
83
|
-
**Complete when:** every new Capability is
|
|
85
|
+
**Complete when:** every new Capability is held by at least one Access Profile or reported as
|
|
84
86
|
intentionally unassigned, `apps/extensions/src/index.ts` and `apps/extensions/package.json`
|
|
85
87
|
include the package, and the organization package `version` is bumped.
|
|
86
88
|
|
|
@@ -10,21 +10,33 @@ The solution deploys to CI as one Extension Package.
|
|
|
10
10
|
declaration. The FQN is a constant, because it cannot be a Package Variable;
|
|
11
11
|
- the Package Variables: origins and callback URLs, never credentials;
|
|
12
12
|
- the Organization settings;
|
|
13
|
-
- the
|
|
14
|
-
|
|
15
|
-
- one Organization Group per
|
|
16
|
-
|
|
17
|
-
|
|
13
|
+
- the Access Profiles (`declareAccessProfile`): each profile allows core capabilities, for example
|
|
14
|
+
`coreCapabilities.platform.knowledge`, and the capabilities of the feature and entity packages;
|
|
15
|
+
- one Organization Group per user profile, with a declared grant of the profile to the Group
|
|
16
|
+
(`declareAccessProfileGrant`);
|
|
17
|
+
- one External App per frontend (`declareExternalApplication`), with a `server` profile granted to
|
|
18
|
+
its server, an `anonymous` profile granted to its visitors when it has any, and its Max Privileges
|
|
19
|
+
(`declareAccessMaxPrivileges`). Without Max Privileges the app's user tokens read nothing.
|
|
18
20
|
|
|
19
|
-
It imports the
|
|
21
|
+
It imports the capability handles from each feature and entity `./ci`, so a profile names only
|
|
22
|
+
declared capabilities:
|
|
20
23
|
|
|
21
24
|
```ts
|
|
22
|
-
import
|
|
25
|
+
import {
|
|
26
|
+
access,
|
|
27
|
+
declareAccessProfile
|
|
28
|
+
} from "@collective-intelligence/extensions-sdk"
|
|
29
|
+
import { invoicing } from "@acme/invoicing/ci"
|
|
23
30
|
|
|
24
|
-
const
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
31
|
+
export const accountant = declareAccessProfile({
|
|
32
|
+
definition: {
|
|
33
|
+
audience: "user",
|
|
34
|
+
capabilities: [access.allow(invoicing.invoices, "manage")],
|
|
35
|
+
lifecycle: { deployMode: "upsert", readonly: true }
|
|
36
|
+
},
|
|
37
|
+
manifest: { fqn: "acme.organization.profiles.accountant", version: "1.0.0" },
|
|
38
|
+
presentation: { displayName: "Accountant" }
|
|
39
|
+
})
|
|
28
40
|
```
|
|
29
41
|
|
|
30
42
|
It exports what the deploy declaration needs, for example `packageManifest`, `variables` and
|
|
@@ -34,14 +34,14 @@ packages/features/invoicing/ @acme/invoicing
|
|
|
34
34
|
|
|
35
35
|
## Subpaths
|
|
36
36
|
|
|
37
|
-
| Subpath | Holds
|
|
38
|
-
| ----------- |
|
|
39
|
-
| `ci/` | Config-as-code CI resources declared with `@collective-intelligence/extensions-sdk` (`declareKnowledgeEntitySchema`, `
|
|
40
|
-
| `domain/` | Effect Schema models, branded ids, pure rules, domain errors. No runtime concerns.
|
|
41
|
-
| `api/` | The Effect `HttpApiGroup` contract: endpoints with payload, success and error schemas from `domain/`.
|
|
42
|
-
| `server/` | The handlers of the `api/` group and the Layer that provides them. Calls CI as the signed-in user.
|
|
43
|
-
| `headless/` | UI state without rendering: actors (UI state only; server data stays in queries), hooks, query keys, search sources, Realtime Topic definitions.
|
|
44
|
-
| `views/` | Wired screens and widgets built on the shared UI package, reading data through the typed client and TanStack Query.
|
|
37
|
+
| Subpath | Holds | Consumers |
|
|
38
|
+
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------- |
|
|
39
|
+
| `ci/` | Config-as-code CI resources declared with `@collective-intelligence/extensions-sdk` (`declareKnowledgeEntitySchema`, `declareAccessCapabilities`, `declareAccessKnowledgeDataPolicy` and others). | 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 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/`.
|
|
@@ -65,19 +65,22 @@ free.
|
|
|
65
65
|
|
|
66
66
|
## Capabilities
|
|
67
67
|
|
|
68
|
-
A package
|
|
68
|
+
A package declares its Access Capabilities in `ci/` and exports the handle:
|
|
69
69
|
|
|
70
70
|
```ts
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
71
|
+
import { declareAccessCapabilities } from "@collective-intelligence/extensions-sdk"
|
|
72
|
+
|
|
73
|
+
export const invoicing = declareAccessCapabilities({
|
|
74
|
+
definition: {
|
|
75
|
+
lifecycle: { deployMode: "upsert", readonly: true },
|
|
76
|
+
nodes: { approvals: { kind: "switch" }, invoices: { kind: "readManage" } }
|
|
77
|
+
},
|
|
78
|
+
manifest: { fqn: "acme.invoicing", version: "1.0.0" }
|
|
79
|
+
})
|
|
78
80
|
```
|
|
79
81
|
|
|
80
|
-
`server/` handlers and `views/` controls gate on these
|
|
82
|
+
`server/` handlers and `views/` controls gate on these capabilities; Knowledge Data Policies in
|
|
83
|
+
`ci/` name them as the capability that opens a schema.
|
|
81
84
|
|
|
82
85
|
## Realtime Topics
|
|
83
86
|
|
|
@@ -13,7 +13,8 @@ Classify in this order; the first match owns the code:
|
|
|
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
|
-
settings,
|
|
16
|
+
settings, Access Profiles and their grants to groups, Max Privileges, groups, External Apps,
|
|
17
|
+
and the audiences it passes into feature packages. See
|
|
17
18
|
[Composition](composition.md).
|
|
18
19
|
4. One business entity that two or more features need, with its own contract, CI resources, data
|
|
19
20
|
and entity views (for example the customer entity and a customer selector) → `entities`. Logic
|