@collective-intelligence/lint 0.3.6 → 0.3.8

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
@@ -79,6 +79,7 @@ the `collective-intelligence` pack installs the skill and adds the plugin with
79
79
  | `ci-solution/subpath-imports` | Imports between subpath folders follow the allowed direction. | Solution layout |
80
80
  | `ci-solution/subpath-entrypoint` | An import from another subpath folder targets the folder or its index file. | Solution layout |
81
81
  | `ci-solution/subpath-index` | Every subpath folder has an `index.ts` or `index.tsx`. | Solution layout |
82
+ | `ci-solution/workspace-layout` | Every workspace sits at `apps/<name>` or `packages/<tier>/<name>` of its workspace root. | Solution layout |
82
83
  | `ci-solution/effect-subpath` | An SDK Effect API comes from the SDK's `/effect` subpath; removed SDK paths are reported. | Effect convention |
83
84
  | `ci-solution/no-run-in-view` | A view module calls no `fetch` and runs no Effect. | Effect convention |
84
85
  | `ci-solution/effect-actors` | XState side-effect actors are `fromEffect` actors. | Effect convention |
@@ -154,6 +155,28 @@ import { rate } from "../domain/rates" // reported
154
155
  Every subpath folder under `src/` has an `index.ts` or `index.tsx` entrypoint.
155
156
  The rule reports each file in a folder that has neither.
156
157
 
158
+ #### `workspace-layout`
159
+
160
+ A solution repository is one flat workspace. Below its workspace root, every
161
+ workspace sits at `apps/<name>` or `packages/<tier>/<name>`, with tier
162
+ `organization`, `features`, `entities`, `modules` or `tooling`. The workspace
163
+ root is the nearest folder above the package whose `package.json` declares
164
+ `workspaces`. For a package anywhere else, the rule reports each linted file
165
+ once:
166
+
167
+ ```text
168
+ apps/web valid
169
+ packages/features/leads valid
170
+ packages/leads reported: no tier folder
171
+ packages/foundation/leads reported: unknown tier
172
+ apps/portal/packages/features/tickets reported: a solution nested in an app
173
+ ```
174
+
175
+ Packages without a workspace root above them, and the root package itself, are
176
+ not checked. The rule sees only linted files: a repository test checks the root
177
+ `workspaces` globs, packages that no glob finds and the tier tags (see the
178
+ `ci-solution-structure` skill).
179
+
157
180
  ### Effect convention
158
181
 
159
182
  An app keeps its side effects in XState machines: each side effect is a
@@ -259,7 +282,8 @@ Each rule is a plain Oxlint rule in its own folder, `src/rules/<rule>/`:
259
282
  `declaredVariable` finds the variable that a name refers to.
260
283
 
261
284
  A rule reads the workspace through `src/workspace/`: `packageOf` and
262
- `installedPackage` find package manifests, `declaresEntrypoint` checks
285
+ `installedPackage` find package manifests, `workspaceRootOf` finds the
286
+ workspace root above a package, `declaresEntrypoint` checks
263
287
  `exports`, and `layoutFile` finds the subpath of a file.
264
288
 
265
289
  2. Add one line to the registry, `src/rules/index.ts`. The plugin, the
package/dist/index.js CHANGED
@@ -143,7 +143,8 @@ var parseExports = (exports) => {
143
143
  var packageInfo = (root, fields) => ({
144
144
  exports: fields.exports === undefined ? null : parseExports(fields.exports),
145
145
  name: fields.name ?? null,
146
- root
146
+ root,
147
+ workspaceRoot: fields.workspaces !== undefined
147
148
  });
148
149
  var parsePackageSpecifier = (specifier) => {
149
150
  if (/^(?:[./#]|[a-z][a-z\d+.-]*:)/iu.test(specifier)) {
@@ -335,6 +336,14 @@ var installedPackage = (directory, name) => {
335
336
  installed.set(key, found);
336
337
  return found;
337
338
  };
339
+ var workspaceRootOf = (root) => {
340
+ const parent = path.dirname(root);
341
+ const ancestor = parent === root ? null : packageOf(parent);
342
+ if (ancestor === null || ancestor.workspaceRoot) {
343
+ return ancestor;
344
+ }
345
+ return workspaceRootOf(ancestor.root);
346
+ };
338
347
 
339
348
  // src/workspace/layout.ts
340
349
  var SUBPATHS = [
@@ -632,6 +641,56 @@ var subpathIndex = {
632
641
  })
633
642
  };
634
643
 
644
+ // src/rules/workspace-layout/workspace-layout.ts
645
+ import { defineRule as defineRule9 } from "@oxlint/plugins";
646
+ import path7 from "node:path";
647
+ var TIERS = [
648
+ "organization",
649
+ "features",
650
+ "entities",
651
+ "modules",
652
+ "tooling"
653
+ ];
654
+ var isTier = (folder) => TIERS.some((tier) => tier === folder);
655
+ var isAllowedPlace = (segments) => {
656
+ const [top, second] = segments;
657
+ return top === "apps" && segments.length === 2 || top === "packages" && segments.length === 3 && isTier(second);
658
+ };
659
+ var workspaceLayout = {
660
+ group: "solution-layout",
661
+ rule: defineRule9({
662
+ create(context) {
663
+ const owner = packageOf(path7.dirname(context.filename));
664
+ const workspaceRoot = owner && workspaceRootOf(owner.root);
665
+ if (owner === null || workspaceRoot === null) {
666
+ return {};
667
+ }
668
+ const segments = path7.relative(workspaceRoot.root, owner.root).split(path7.sep);
669
+ if (isAllowedPlace(segments)) {
670
+ return {};
671
+ }
672
+ return {
673
+ Program: (node) => {
674
+ context.report({
675
+ data: { place: segments.join("/") },
676
+ messageId: "misplaced",
677
+ node
678
+ });
679
+ }
680
+ };
681
+ },
682
+ meta: {
683
+ docs: {
684
+ description: "Require every workspace to sit at apps/<name> or packages/<tier>/<name> of its workspace root."
685
+ },
686
+ messages: {
687
+ misplaced: `Workspace \`{{place}}\` is not at \`apps/<name>\` or \`packages/<tier>/<name>\` (tier: ${TIERS.join(", ")}) of its workspace root. Move it to one of these places.`
688
+ },
689
+ type: "problem"
690
+ }
691
+ })
692
+ };
693
+
635
694
  // src/rules/index.ts
636
695
  var rules = {
637
696
  "effect-actors": effectActors,
@@ -641,7 +700,8 @@ var rules = {
641
700
  "package-entrypoint": packageEntrypoint,
642
701
  "subpath-entrypoint": subpathEntrypoint,
643
702
  "subpath-imports": subpathImports,
644
- "subpath-index": subpathIndex
703
+ "subpath-index": subpathIndex,
704
+ "workspace-layout": workspaceLayout
645
705
  };
646
706
 
647
707
  // src/index.ts
@@ -8,4 +8,5 @@ export declare const rules: {
8
8
  readonly "subpath-entrypoint": LintRule;
9
9
  readonly "subpath-imports": LintRule;
10
10
  readonly "subpath-index": LintRule;
11
+ readonly "workspace-layout": LintRule;
11
12
  };
@@ -0,0 +1,3 @@
1
+ import type { LintRule } from "../../rule.ts";
2
+ export declare const TIERS: readonly ["organization", "features", "entities", "modules", "tooling"];
3
+ export declare const workspaceLayout: LintRule;
@@ -4,11 +4,15 @@ export type ExportsField = string | null | readonly ExportsField[] | {
4
4
  export interface Manifest {
5
5
  readonly exports?: ExportsField;
6
6
  readonly name?: string;
7
+ readonly workspaces?: readonly string[] | {
8
+ readonly packages?: readonly string[];
9
+ };
7
10
  }
8
11
  export interface PackageInfo {
9
12
  readonly exports: ReadonlyMap<string, boolean> | null;
10
13
  readonly name: string | null;
11
14
  readonly root: string;
15
+ readonly workspaceRoot: boolean;
12
16
  }
13
17
  export declare const packageInfo: (root: string, fields: Manifest) => PackageInfo;
14
18
  export interface PackageSpecifier {
@@ -1,3 +1,4 @@
1
1
  import type { PackageInfo } from "./package-exports.ts";
2
2
  export declare const packageOf: (target: string) => PackageInfo | null;
3
3
  export declare const installedPackage: (directory: string, name: string) => PackageInfo | null;
4
+ export declare const workspaceRootOf: (root: string) => PackageInfo | null;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@collective-intelligence/lint",
3
- "version": "0.3.6",
3
+ "version": "0.3.8",
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": "37985618c3be2c13cfffea453ec295c0c3a9b0b6"
51
+ "gitHead": "d7c921799df228a99d1adbb7ba8be2010460e445"
52
52
  }
@@ -4,13 +4,13 @@ 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
6
  subpath, declaring CI resources, Access Capabilities, Access Profiles or Realtime Topics, or fixing
7
- `turbo boundaries` or `ci-solution/*` lint errors.
7
+ `turbo boundaries`, `ci-solution/*` lint or workspace layout test errors.
8
8
  ---
9
9
 
10
10
  # CI Solution Structure
11
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
12
+ A CI solution is one flat turborepo. Each app lives at `apps/<name>`, each package at
13
+ `packages/<tier>/<name>`, and each workspace has exactly one tier. Imports follow the Stable Dependencies Principle and point down the arrows; an
14
14
  import may skip tiers:
15
15
 
16
16
  ```text
@@ -29,6 +29,12 @@ packages/tooling/<name> shared config and build tools; every tier imports
29
29
 
30
30
  ## Invariants
31
31
 
32
+ - The root `package.json` workspace globs are exactly `["apps/*", "packages/*/*"]`, and the root is
33
+ the only workspace root. Every workspace sits at `apps/<name>` or `packages/<tier>/<name>` with
34
+ tier `organization`, `features`, `entities`, `modules` or `tooling`. Code from a nested solution,
35
+ a flat `packages/<name>` or another tier folder moves into one of these two places.
36
+ - Shared logic and the source of truth live in `packages/`. An app composes packages and keeps only
37
+ its routes, app API, server root and deploy declaration.
32
38
  - Package names are flat: `packages/features/invoicing` is `@acme/invoicing`. Only the folder shows
33
39
  the tier.
34
40
  - Inside one tier, only modules and tooling packages import each other. A feature reaches another
@@ -41,12 +47,13 @@ packages/tooling/<name> shared config and build tools; every tier imports
41
47
  - Each package declares its own CI resources, Access Capabilities and Knowledge Data Policies in
42
48
  `./ci`. Only the organization package declares Access Profiles, their grants and the Max
43
49
  Privileges of each External App.
44
- - `apps/extensions` is a pure composition root: `src/index.ts` passes the organization package and
45
- every package `./ci` to `declarePackage`.
50
+ - `apps/extensions` is a pure composition root: `src/index.ts` passes the organization components and
51
+ every package `./ci` to `declarePackage`. Its one own declaration is a hosted frontend
52
+ contribution, whose `load` imports the entry `src/studio.ts` next to it.
46
53
  - The CI SDKs own the realtime transport. A package contributes only Realtime Topic definitions, in
47
54
  `./headless`.
48
- - Every workspace has a `turbo.json` with exactly one `tier:*` tag; `turbo boundaries` checks only
49
- tagged workspaces.
55
+ - Every workspace has a `turbo.json` with exactly the `tier:*` tag its folder implies (`tier:app` for
56
+ `apps/*`); `turbo boundaries` checks only tagged workspaces.
50
57
 
51
58
  ## References
52
59
 
@@ -57,8 +64,8 @@ packages/tooling/<name> shared config and build tools; every tier imports
57
64
  - [Composition](references/composition.md): read when you change the organization package, Access
58
65
  Profiles, grants, groups, External Apps or `apps/extensions`.
59
66
  - [Enforcement](references/enforcement.md): read when you add a workspace, edit tier tags or the root
60
- boundaries table, configure `@collective-intelligence/lint`, or fix a `turbo boundaries` or
61
- `ci-solution/*` error.
67
+ boundaries table, set up the workspace layout guard, configure `@collective-intelligence/lint`, or
68
+ fix a `turbo boundaries`, `ci-solution/*` or workspace layout test error.
62
69
 
63
70
  ## Workflow: add a feature package
64
71
 
@@ -17,9 +17,14 @@ The solution deploys to CI as one Extension Package.
17
17
  - one External App per frontend (`declareExternalApplication`), with a `server` profile granted to
18
18
  its server, an `anonymous` profile granted to its visitors when it has any, and its Max Privileges
19
19
  (`declareAccessMaxPrivileges`). Without Max Privileges the app's user tokens read nothing.
20
+ - the Studio apps that place views of several packages on one page, such as a desk that lists an
21
+ entity and shows a feature widget. A Studio app composes across domains and takes an organization
22
+ Group as its `audience`, so it sits above the features;
23
+ - the Studio frontend catalog (`loadFrontendCatalog`): one `declareFrontendPackage` under the package
24
+ identity that gathers the Studio renderers each feature `./ci` exports.
20
25
 
21
- It imports the capability handles from each feature and entity `./ci`, so a profile names only
22
- declared capabilities:
26
+ It imports the capability handles, or their FQN constants, from each feature and entity `./ci`, so a
27
+ profile names only declared capabilities:
23
28
 
24
29
  ```ts
25
30
  import {
@@ -39,12 +44,15 @@ export const accountant = declareAccessProfile({
39
44
  })
40
45
  ```
41
46
 
42
- It exports what the deploy declaration needs, for example `packageManifest`, `variables` and
43
- `organizationComponents` (the components in deploy order).
47
+ It exports what the deploy declaration needs, for example `packageManifest`, `variables`,
48
+ `organizationComponents` (its components in deploy order) and the handles that package factories
49
+ take, such as the domain or the External App.
44
50
 
45
51
  ## `apps/extensions`
46
52
 
47
- `apps/extensions/src` holds only `index.ts` and the media files it deploys:
53
+ `apps/extensions/src` holds only `index.ts`, the media files it deploys and the entry of a hosted
54
+ frontend contribution. `index.ts` lists every component in deploy order, each after the components
55
+ it references, so package capabilities come before the profiles that grant them:
48
56
 
49
57
  ```ts
50
58
  import { declarePackage } from "@collective-intelligence/extensions-sdk"
@@ -58,9 +66,9 @@ import {
58
66
 
59
67
  export default declarePackage({
60
68
  components: [
61
- ...organizationComponents,
62
69
  ...customerComponents,
63
- ...invoicingComponents
70
+ ...invoicingComponents,
71
+ ...organizationComponents
64
72
  ],
65
73
  manifest: packageManifest,
66
74
  variables
@@ -73,3 +81,8 @@ export default declarePackage({
73
81
  the SDK host modules stay external. Code that `./ci` pulls in ships in that asset.
74
82
  - Package Media paths such as `media/logo.png` resolve next to the declaration module, so media files
75
83
  stay in `apps/extensions/src/media`.
84
+ - A hosted frontend contribution (`declareFrontendCatalogContribution`) is the one declaration that
85
+ `apps/extensions` owns. `ci package build` resolves a relative `load` import against the
86
+ declaration file, so the contribution sits in `index.ts` with
87
+ `load: async () => await import("./studio")`, and `src/studio.ts` only re-exports the catalog
88
+ loader of the organization package: the build ships every export of that module to the browser.
@@ -1,7 +1,9 @@
1
1
  # Enforcement
2
2
 
3
- `turbo boundaries` checks the direction between packages. `@collective-intelligence/lint` checks the
4
- folders and imports inside and into a package.
3
+ `turbo boundaries` checks the direction between packages. `@collective-intelligence/lint` checks where
4
+ each package sits and the folders and imports inside and into a package. The
5
+ [workspace layout guard](#workspace-layout-guard) checks the rest: the root globs, packages that no
6
+ glob finds, the tier tags and the `check` script.
5
7
 
6
8
  ## `turbo boundaries`
7
9
 
@@ -37,17 +39,43 @@ allow themselves.
37
39
  it as an undeclared dependency.
38
40
  - `turbo boundaries` also reports an import of a file outside the package directory and an import of
39
41
  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, entity → entity and entity → feature.
45
- - Run `turbo boundaries` in the repository `check` script.
42
+ - An untagged workspace, or a `package.json` that no root glob finds, has no rule, so
43
+ `turbo boundaries` never checks its imports. The workspace layout guard closes that gap.
46
44
 
47
45
  Read the error `` Package `@acme/a` found without any tag listed in allowlist for `@acme/b` `` as:
48
46
  `@acme/b` imports `@acme/a` against the direction. Move the shared part down a tier, or compose both
49
47
  packages in the app (see [Tiers](tiers.md#cross-domain-composition)).
50
48
 
49
+ ### Workspace layout guard
50
+
51
+ Every solution repository runs one Bun test, `packages/tooling/config/src/workspace-layout.test.ts`.
52
+ Copy it from the next-effect-app template (the same path in
53
+ `collective-intelligence-solutions/next-effect-app`; in ci-app,
54
+ `examples/next-effect-app/packages/tooling/config/src/workspace-layout.test.ts`) and replace any
55
+ older workspace tier or boundaries test with it. It asserts:
56
+
57
+ - the root `workspaces` globs are exactly `["apps/*", "packages/*/*"]`;
58
+ - every tracked `package.json` is the root or a workspace those globs find; only agent tooling
59
+ (dot folders), fixtures and templates are exempt, so a nested root fails;
60
+ - each workspace `turbo.json` extends `//` and has exactly the tier tag its folder implies: `tier:app`
61
+ for `apps/*`, `tier:<tier>` for `packages/<tier>/*`;
62
+ - the `tier:*` rules of the root `boundaries.tags` allow exactly the tiers of the diagram in
63
+ [SKILL.md](../SKILL.md); extra non-tier tags and single-package allows may sit next to them;
64
+ - the root `check` script runs `turbo boundaries`;
65
+ - `turbo boundaries` rejects feature → feature, entity → entity and entity → feature on a throwaway
66
+ fixture workspace with the real root table.
67
+
68
+ Wire it so that it runs on every change:
69
+
70
+ - `packages/tooling/config/package.json` has `"test": "bun test src"` and `@types/bun`, so
71
+ `turbo run test` runs the guard.
72
+ - The root `check` script runs `turbo boundaries` after its other checks, such as
73
+ `ultracite check && turbo boundaries`.
74
+ - The CI workflow runs `bun run check` and the tests.
75
+
76
+ Keep a repository-specific assertion, such as a deny rule on an extra tag, as an extra test in the
77
+ same file.
78
+
51
79
  ### Migrating from `foundation`
52
80
 
53
81
  Earlier versions named the business-agnostic tier `foundation` and the shared domain tier
@@ -89,6 +117,7 @@ XState machines and out of views:
89
117
  | `ci-solution/subpath-imports` | The [subpath direction](package-shape.md#subpath-direction). |
90
118
  | `ci-solution/subpath-entrypoint` | An import into another subpath targets the folder or its `index` file. |
91
119
  | `ci-solution/subpath-index` | Every subpath folder under `src/` has an `index.ts` or `index.tsx`. |
120
+ | `ci-solution/workspace-layout` | Each workspace sits at `apps/<name>` or `packages/<tier>/<name>` of its root. |
92
121
  | `ci-solution/effect-subpath` | An SDK Effect API comes from `<sdk>/effect`; removed SDK paths are errors. |
93
122
  | `ci-solution/no-run-in-view` | A view module (`.tsx`, `.jsx`, `views/`) calls no `fetch` and runs no Effect. |
94
123
  | `ci-solution/effect-actors` | XState side-effect actors are `fromEffect`, not `fromPromise` or `fromCallback`. |