@collective-intelligence/lint 0.2.1 → 0.2.3
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 +34 -4
- package/dist/index.js +95 -42
- package/dist/rule.d.ts +2 -0
- package/dist/rules/effect-writes/effect-writes.d.ts +2 -0
- package/dist/rules/index.d.ts +1 -0
- package/dist/workspace/layout.d.ts +1 -0
- 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/enforcement.md +1 -0
- package/skills/ci-solution-structure/references/package-shape.md +20 -17
package/README.md
CHANGED
|
@@ -82,6 +82,7 @@ the `collective-intelligence` pack installs the skill and adds the plugin with
|
|
|
82
82
|
| `ci-solution/effect-subpath` | An SDK Effect API comes from the SDK's `/effect` subpath; removed SDK paths are reported. | Effect convention |
|
|
83
83
|
| `ci-solution/no-run-in-view` | A view module calls no `fetch` and runs no Effect. | Effect convention |
|
|
84
84
|
| `ci-solution/effect-actors` | XState side-effect actors are `fromEffect` actors. | Effect convention |
|
|
85
|
+
| `ci-solution/effect-writes` | No module takes TanStack Query `useMutation`; writes run in `fromEffect` actors. | Effect convention |
|
|
85
86
|
|
|
86
87
|
### Package boundaries
|
|
87
88
|
|
|
@@ -156,7 +157,8 @@ The rule reports each file in a folder that has neither.
|
|
|
156
157
|
### Effect convention
|
|
157
158
|
|
|
158
159
|
An app keeps its side effects in XState machines: each side effect is a
|
|
159
|
-
`fromEffect` actor,
|
|
160
|
+
`fromEffect` actor, views read data through TanStack Query, and writes refresh
|
|
161
|
+
those reads through the SDK `QueryCache`. These rules
|
|
160
162
|
check the parts of that convention that imports and calls show.
|
|
161
163
|
|
|
162
164
|
#### `effect-subpath`
|
|
@@ -207,13 +209,41 @@ entry.
|
|
|
207
209
|
|
|
208
210
|
The rule reports each `fromPromise`, `fromCallback`, `fromObservable` and
|
|
209
211
|
`fromEventObservable` that an import, a re-export or a namespace import
|
|
210
|
-
(`XState.fromPromise`, `XState["fromPromise"]
|
|
211
|
-
`xstate/*`. Make side-effect actors with `fromEffect` from
|
|
212
|
-
`@collective-intelligence/external-apps-client-sdk-react/effect
|
|
212
|
+
(`XState.fromPromise`, `XState["fromPromise"]`,
|
|
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` in a detached
|
|
215
|
+
app, or from `@collective-intelligence/extensions-sdk-frontend-react/effect` in
|
|
216
|
+
a hosted Studio Widget. Machines and
|
|
213
217
|
`fromTransition` actors have no side effects and are not reported. A local name
|
|
214
218
|
that shadows the namespace import, such as a parameter named `XState`, is not
|
|
215
219
|
reported.
|
|
216
220
|
|
|
221
|
+
#### `effect-writes`
|
|
222
|
+
|
|
223
|
+
The rule reports each `useMutation` that an import, a re-export or a namespace
|
|
224
|
+
import (`ReactQuery.useMutation`, `ReactQuery["useMutation"]`,
|
|
225
|
+
`const { useMutation } = ReactQuery`) takes from `@tanstack/react-query`. Write through a `fromEffect` actor from
|
|
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`).
|
|
230
|
+
|
|
231
|
+
The rule checks every module. `useMutation` runs only during a React render,
|
|
232
|
+
so a module that takes it is a view, a hook or a helper of one of them.
|
|
233
|
+
|
|
234
|
+
`useQuery` and the other reads are not reported, and neither are
|
|
235
|
+
`useMutationState` and `useIsMutating`: they only read the state of a
|
|
236
|
+
`useMutation`. A `useMutation` from another library, such as
|
|
237
|
+
`@apollo/client`, is not reported. The entity hooks of
|
|
238
|
+
`@collective-intelligence/external-apps-client-sdk-react/resources`
|
|
239
|
+
(`useEntityCreate`, `useEntityUpdate`, `useEntityDelete`) are not reported:
|
|
240
|
+
the SDK writes and refreshes its own entity reads.
|
|
241
|
+
|
|
242
|
+
The rule checks no query key. An app that builds the SDK's `"ci-entities"`
|
|
243
|
+
key by hand, for example in `invalidateQueries`, is not reported: the SDK
|
|
244
|
+
owns that key for its entity reads but exports no key or refresh function for
|
|
245
|
+
them yet, so a report would have no supported fix.
|
|
246
|
+
|
|
217
247
|
## Adding a rule
|
|
218
248
|
|
|
219
249
|
Each rule is a plain Oxlint rule in its own folder, `src/rules/<rule>/`:
|
package/dist/index.js
CHANGED
|
@@ -53,6 +53,48 @@ var moduleSpecifiers = (check) => {
|
|
|
53
53
|
}
|
|
54
54
|
};
|
|
55
55
|
};
|
|
56
|
+
var moduleExportName = (node) => node.type === "Literal" ? node.value : node.name;
|
|
57
|
+
var moduleMembers = (sourceCode, isModule, check) => {
|
|
58
|
+
const isNamespace = (node) => {
|
|
59
|
+
if (node?.type !== "Identifier") {
|
|
60
|
+
return false;
|
|
61
|
+
}
|
|
62
|
+
const variable = declaredVariable(sourceCode, node);
|
|
63
|
+
return variable !== null && variable.defs.some(({ node: definition }) => definition.type === "ImportNamespaceSpecifier" && definition.parent.type === "ImportDeclaration" && isModule(definition.parent.source.value));
|
|
64
|
+
};
|
|
65
|
+
return {
|
|
66
|
+
ExportNamedDeclaration: (node) => {
|
|
67
|
+
if (node.source !== null && isModule(node.source.value)) {
|
|
68
|
+
for (const specifier of node.specifiers) {
|
|
69
|
+
check(specifier, moduleExportName(specifier.local));
|
|
70
|
+
}
|
|
71
|
+
}
|
|
72
|
+
},
|
|
73
|
+
ImportDeclaration: (node) => {
|
|
74
|
+
if (isModule(node.source.value)) {
|
|
75
|
+
for (const specifier of node.specifiers) {
|
|
76
|
+
if (specifier.type === "ImportSpecifier") {
|
|
77
|
+
check(specifier, moduleExportName(specifier.imported));
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
},
|
|
82
|
+
MemberExpression: (node) => {
|
|
83
|
+
if (isNamespace(node.object)) {
|
|
84
|
+
check(node, staticPropertyName(node.property, node.computed));
|
|
85
|
+
}
|
|
86
|
+
},
|
|
87
|
+
VariableDeclarator: (node) => {
|
|
88
|
+
if (node.id.type === "ObjectPattern" && isNamespace(node.init)) {
|
|
89
|
+
for (const property of node.id.properties) {
|
|
90
|
+
if (property.type === "Property") {
|
|
91
|
+
check(property, staticPropertyName(property.key, property.computed));
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
};
|
|
97
|
+
};
|
|
56
98
|
|
|
57
99
|
// src/rules/effect-actors/effect-actors.ts
|
|
58
100
|
var SIDE_EFFECT_ACTORS = new Set([
|
|
@@ -62,11 +104,9 @@ var SIDE_EFFECT_ACTORS = new Set([
|
|
|
62
104
|
"fromPromise"
|
|
63
105
|
]);
|
|
64
106
|
var messages = {
|
|
65
|
-
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."
|
|
66
108
|
};
|
|
67
109
|
var isXState = (source) => source === "xstate" || source.startsWith("xstate/");
|
|
68
|
-
var nameOf = (node) => node.type === "Literal" ? node.value : node.name;
|
|
69
|
-
var isXStateNamespace = (variable) => variable !== null && variable.defs.some(({ node }) => node.type === "ImportNamespaceSpecifier" && node.parent.type === "ImportDeclaration" && isXState(node.parent.source.value));
|
|
70
110
|
var effectActors = {
|
|
71
111
|
group: "effect-convention",
|
|
72
112
|
rule: defineRule({
|
|
@@ -80,29 +120,7 @@ var effectActors = {
|
|
|
80
120
|
});
|
|
81
121
|
}
|
|
82
122
|
};
|
|
83
|
-
return
|
|
84
|
-
ExportNamedDeclaration: (node) => {
|
|
85
|
-
if (node.source !== null && isXState(node.source.value)) {
|
|
86
|
-
for (const specifier of node.specifiers) {
|
|
87
|
-
check(specifier, nameOf(specifier.local));
|
|
88
|
-
}
|
|
89
|
-
}
|
|
90
|
-
},
|
|
91
|
-
ImportDeclaration: (node) => {
|
|
92
|
-
if (isXState(node.source.value)) {
|
|
93
|
-
for (const specifier of node.specifiers) {
|
|
94
|
-
if (specifier.type === "ImportSpecifier") {
|
|
95
|
-
check(specifier, nameOf(specifier.imported));
|
|
96
|
-
}
|
|
97
|
-
}
|
|
98
|
-
}
|
|
99
|
-
},
|
|
100
|
-
MemberExpression: (node) => {
|
|
101
|
-
if (node.object.type === "Identifier" && isXStateNamespace(declaredVariable(context.sourceCode, node.object))) {
|
|
102
|
-
check(node, staticPropertyName(node.property, node.computed));
|
|
103
|
-
}
|
|
104
|
-
}
|
|
105
|
-
};
|
|
123
|
+
return moduleMembers(context.sourceCode, isXState, check);
|
|
106
124
|
},
|
|
107
125
|
meta: {
|
|
108
126
|
docs: {
|
|
@@ -189,9 +207,9 @@ var MOVED = new Map([
|
|
|
189
207
|
]
|
|
190
208
|
]);
|
|
191
209
|
var messages2 = {
|
|
210
|
+
outsideEffect: "`{{specifier}}` imports an SDK Effect API from outside its `/effect` subpath. Import `{{replacement}}`.",
|
|
192
211
|
removed: "`{{specifier}}` is removed after 0.2.0. Import `{{replacement}}`.",
|
|
193
|
-
removedMoved: "`{{specifier}}` is removed after 0.2.0. Import {{names}} from `{{moved}}`, and each other name from `{{replacement}}`."
|
|
194
|
-
outsideEffect: "`{{specifier}}` imports an SDK Effect API from outside its `/effect` subpath. Import `{{replacement}}`."
|
|
212
|
+
removedMoved: "`{{specifier}}` is removed after 0.2.0. Import {{names}} from `{{moved}}`, and each other name from `{{replacement}}`."
|
|
195
213
|
};
|
|
196
214
|
var effectSubpathFor = (specifier) => {
|
|
197
215
|
const parsed = parsePackageSpecifier(specifier);
|
|
@@ -243,8 +261,42 @@ var effectSubpath = {
|
|
|
243
261
|
})
|
|
244
262
|
};
|
|
245
263
|
|
|
246
|
-
// src/rules/
|
|
264
|
+
// src/rules/effect-writes/effect-writes.ts
|
|
247
265
|
import { defineRule as defineRule3 } from "@oxlint/plugins";
|
|
266
|
+
var messages3 = {
|
|
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
|
+
};
|
|
269
|
+
var isTanStackQuery = (source) => source === "@tanstack/react-query";
|
|
270
|
+
var takesTanStackQuery = (statement) => (statement.type === "ImportDeclaration" || statement.type === "ExportNamedDeclaration") && statement.source !== null && isTanStackQuery(statement.source.value);
|
|
271
|
+
var effectWrites = {
|
|
272
|
+
group: "effect-convention",
|
|
273
|
+
rule: defineRule3({
|
|
274
|
+
create(context) {
|
|
275
|
+
const program = context.sourceCode.ast;
|
|
276
|
+
if (!program.body.some(takesTanStackQuery)) {
|
|
277
|
+
return {};
|
|
278
|
+
}
|
|
279
|
+
return moduleMembers(context.sourceCode, isTanStackQuery, (node, name) => {
|
|
280
|
+
if (name === "useMutation") {
|
|
281
|
+
context.report({
|
|
282
|
+
messageId: "mutationHook",
|
|
283
|
+
node
|
|
284
|
+
});
|
|
285
|
+
}
|
|
286
|
+
});
|
|
287
|
+
},
|
|
288
|
+
meta: {
|
|
289
|
+
docs: {
|
|
290
|
+
description: "Disallow TanStack Query `useMutation`; writes run in `fromEffect` actors."
|
|
291
|
+
},
|
|
292
|
+
messages: messages3,
|
|
293
|
+
type: "problem"
|
|
294
|
+
}
|
|
295
|
+
})
|
|
296
|
+
};
|
|
297
|
+
|
|
298
|
+
// src/rules/no-run-in-view/no-run-in-view.ts
|
|
299
|
+
import { defineRule as defineRule4 } from "@oxlint/plugins";
|
|
248
300
|
|
|
249
301
|
// src/workspace/layout.ts
|
|
250
302
|
import path2 from "node:path";
|
|
@@ -312,21 +364,21 @@ var layoutFile = (filename) => {
|
|
|
312
364
|
const subpath = segments && segments.length > 1 ? subpathOfSegments(segments) : null;
|
|
313
365
|
return owner && subpath ? { owner, subpath } : null;
|
|
314
366
|
};
|
|
367
|
+
var JSX_FILE = /\.[jt]sx$/u;
|
|
368
|
+
var isViewModule = (filename) => JSX_FILE.test(filename) || layoutFile(filename)?.subpath === "views";
|
|
315
369
|
|
|
316
370
|
// src/rules/no-run-in-view/no-run-in-view.ts
|
|
317
|
-
var JSX_FILE = /\.[jt]sx$/u;
|
|
318
371
|
var RUN_FUNCTION = /^run(?:Callback|Fork|Promise|PromiseExit|Sync|SyncExit)(?:With)?$/u;
|
|
319
372
|
var FETCH_OBJECTS = ["globalThis", "window"];
|
|
320
373
|
var isRunFunction = (name) => name !== null && RUN_FUNCTION.test(name);
|
|
321
374
|
var isEffectModule = (source) => source === "effect" || source.startsWith("effect/") || source.startsWith("@effect/");
|
|
322
|
-
var
|
|
375
|
+
var messages4 = {
|
|
323
376
|
fetch: "A view module calls `fetch`. Read data with TanStack Query, or call the API in a `fromEffect` actor.",
|
|
324
377
|
run: "A view module runs an Effect with `{{name}}`. Run the Effect in a `fromEffect` actor."
|
|
325
378
|
};
|
|
326
|
-
var isViewModule = (filename) => JSX_FILE.test(filename) || layoutFile(filename)?.subpath === "views";
|
|
327
379
|
var noRunInView = {
|
|
328
380
|
group: "effect-convention",
|
|
329
|
-
rule:
|
|
381
|
+
rule: defineRule4({
|
|
330
382
|
create(context) {
|
|
331
383
|
if (!isViewModule(context.filename)) {
|
|
332
384
|
return {};
|
|
@@ -384,19 +436,19 @@ var noRunInView = {
|
|
|
384
436
|
docs: {
|
|
385
437
|
description: "Disallow `fetch` calls and Effect run functions in view modules; side effects run in `fromEffect` actors."
|
|
386
438
|
},
|
|
387
|
-
messages:
|
|
439
|
+
messages: messages4,
|
|
388
440
|
type: "problem"
|
|
389
441
|
}
|
|
390
442
|
})
|
|
391
443
|
};
|
|
392
444
|
|
|
393
445
|
// src/rules/package-entrypoint/package-entrypoint.ts
|
|
394
|
-
import { defineRule as
|
|
446
|
+
import { defineRule as defineRule5 } from "@oxlint/plugins";
|
|
395
447
|
import path3 from "node:path";
|
|
396
448
|
var packageName = (target) => target.name ?? path3.basename(target.root);
|
|
397
449
|
var packageEntrypoint = {
|
|
398
450
|
group: "package-boundaries",
|
|
399
|
-
rule:
|
|
451
|
+
rule: defineRule5({
|
|
400
452
|
create(context) {
|
|
401
453
|
const directory = path3.dirname(context.filename);
|
|
402
454
|
const owner = packageOf(directory);
|
|
@@ -444,11 +496,11 @@ var packageEntrypoint = {
|
|
|
444
496
|
};
|
|
445
497
|
|
|
446
498
|
// src/rules/subpath-entrypoint/subpath-entrypoint.ts
|
|
447
|
-
import { defineRule as
|
|
499
|
+
import { defineRule as defineRule6 } from "@oxlint/plugins";
|
|
448
500
|
import path4 from "node:path";
|
|
449
501
|
var subpathEntrypoint = {
|
|
450
502
|
group: "solution-layout",
|
|
451
|
-
rule:
|
|
503
|
+
rule: defineRule6({
|
|
452
504
|
create(context) {
|
|
453
505
|
const directory = path4.dirname(context.filename);
|
|
454
506
|
const owner = packageOf(directory);
|
|
@@ -485,7 +537,7 @@ var subpathEntrypoint = {
|
|
|
485
537
|
};
|
|
486
538
|
|
|
487
539
|
// src/rules/subpath-imports/subpath-imports.ts
|
|
488
|
-
import { defineRule as
|
|
540
|
+
import { defineRule as defineRule7 } from "@oxlint/plugins";
|
|
489
541
|
import path5 from "node:path";
|
|
490
542
|
var FORBIDDEN_IMPORTS = {
|
|
491
543
|
api: [],
|
|
@@ -497,7 +549,7 @@ var FORBIDDEN_IMPORTS = {
|
|
|
497
549
|
};
|
|
498
550
|
var subpathImports = {
|
|
499
551
|
group: "solution-layout",
|
|
500
|
-
rule:
|
|
552
|
+
rule: defineRule7({
|
|
501
553
|
create(context) {
|
|
502
554
|
const file = layoutFile(context.filename);
|
|
503
555
|
if (file === null) {
|
|
@@ -542,13 +594,13 @@ var subpathImports = {
|
|
|
542
594
|
};
|
|
543
595
|
|
|
544
596
|
// src/rules/subpath-index/subpath-index.ts
|
|
545
|
-
import { defineRule as
|
|
597
|
+
import { defineRule as defineRule8 } from "@oxlint/plugins";
|
|
546
598
|
import { existsSync as existsSync2 } from "node:fs";
|
|
547
599
|
import path6 from "node:path";
|
|
548
600
|
var INDEX_FILES = ["index.ts", "index.tsx"];
|
|
549
601
|
var subpathIndex = {
|
|
550
602
|
group: "solution-layout",
|
|
551
|
-
rule:
|
|
603
|
+
rule: defineRule8({
|
|
552
604
|
create(context) {
|
|
553
605
|
const file = layoutFile(context.filename);
|
|
554
606
|
if (file === null) {
|
|
@@ -584,6 +636,7 @@ var subpathIndex = {
|
|
|
584
636
|
var rules = {
|
|
585
637
|
"effect-actors": effectActors,
|
|
586
638
|
"effect-subpath": effectSubpath,
|
|
639
|
+
"effect-writes": effectWrites,
|
|
587
640
|
"no-run-in-view": noRunInView,
|
|
588
641
|
"package-entrypoint": packageEntrypoint,
|
|
589
642
|
"subpath-entrypoint": subpathEntrypoint,
|
package/dist/rule.d.ts
CHANGED
|
@@ -7,3 +7,5 @@ export interface LintRule {
|
|
|
7
7
|
export declare const staticPropertyName: (key: ESTree.PropertyKey, computed: boolean) => string | null;
|
|
8
8
|
export declare const declaredVariable: (sourceCode: SourceCode, node: ESTree.IdentifierReference) => Variable | null;
|
|
9
9
|
export declare const moduleSpecifiers: (check: (literal: ESTree.StringLiteral) => void) => Visitor;
|
|
10
|
+
export declare const moduleExportName: (node: ESTree.ModuleExportName) => string;
|
|
11
|
+
export declare const moduleMembers: (sourceCode: SourceCode, isModule: (source: string) => boolean, check: (node: ESTree.Node, name: string | null) => void) => Visitor;
|
package/dist/rules/index.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ import type { LintRule } from "../rule.ts";
|
|
|
2
2
|
export declare const rules: {
|
|
3
3
|
readonly "effect-actors": LintRule;
|
|
4
4
|
readonly "effect-subpath": LintRule;
|
|
5
|
+
readonly "effect-writes": LintRule;
|
|
5
6
|
readonly "no-run-in-view": LintRule;
|
|
6
7
|
readonly "package-entrypoint": LintRule;
|
|
7
8
|
readonly "subpath-entrypoint": LintRule;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@collective-intelligence/lint",
|
|
3
|
-
"version": "0.2.
|
|
3
|
+
"version": "0.2.3",
|
|
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": "1718b80bc8d0ba696d78ac8f5f905c8dc46fe0c5"
|
|
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
|
|
@@ -92,6 +92,7 @@ XState machines and out of views:
|
|
|
92
92
|
| `ci-solution/effect-subpath` | An SDK Effect API comes from `<sdk>/effect`; removed SDK paths are errors. |
|
|
93
93
|
| `ci-solution/no-run-in-view` | A view module (`.tsx`, `.jsx`, `views/`) calls no `fetch` and runs no Effect. |
|
|
94
94
|
| `ci-solution/effect-actors` | XState side-effect actors are `fromEffect`, not `fromPromise` or `fromCallback`. |
|
|
95
|
+
| `ci-solution/effect-writes` | No module takes TanStack Query `useMutation`; writes are `fromEffect` actors. |
|
|
95
96
|
|
|
96
97
|
`package-entrypoint` finds each package through `node_modules`, so the package manager must link the
|
|
97
98
|
workspace packages. The package documentation is the authority for rule options.
|
|
@@ -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
|
|