@collective-intelligence/lint

The Collective Intelligence lint rules, as one Oxlint plugin. Every CI lint rule lives in this package. The plugin is named ci-solution, so each rule is enabled as ci-solution/<rule>.

Install

bun add -d oxlint @collective-intelligence/lint

The plugin needs oxlint 1.82.0 or later.

Use

All rules

Extend the recommended config in oxlint.config.ts. It loads the plugin and enables every rule as an error:

import { recommended } from "@collective-intelligence/lint"
import { defineConfig } from "oxlint"

export default defineConfig({
  extends: [recommended]
})

To change one rule, set it after the extend:

export default defineConfig({
  extends: [recommended],
  rules: { "ci-solution/subpath-index": "warn" }
})

Selected rules

Load the plugin and enable only the rules you want:

import { defineConfig } from "oxlint"

export default defineConfig({
  jsPlugins: ["@collective-intelligence/lint"],
  rules: {
    "ci-solution/package-entrypoint": "error",
    "ci-solution/subpath-imports": "error"
  }
})

A JSON config works the same way:

{
  "jsPlugins": ["@collective-intelligence/lint"],
  "rules": { "ci-solution/package-entrypoint": "error" }
}

The RuleName type lists every rule name.

Agent skill

The package ships the agent skill ci-solution-structure at skills/ci-solution-structure/SKILL.md. In a Harness Intelligence repository, the collective-intelligence pack installs the skill and adds the plugin with ci-solution/package-entrypoint to the managed lint config.

Rules

Package boundaries

A workspace holds packages that import each other. These rules keep each package behind its declared public entrypoints.

package-entrypoint

Import another package through its root (@scope/pkg) or a subpath listed in its package.json exports (@scope/pkg/views). * patterns and null exclusions follow Node resolution. The rule finds the package through node_modules from the importing file, so workspace packages must be linked by the package manager.

import { invoiceTotal } from "@acme/billing" // valid
import { invoiceTable } from "@acme/billing/views" // valid when "./views" is exported
import { rate } from "@acme/billing/src/domain/rates" // reported
import { rate } from "../../billing/src/domain/rates" // reported: relative path into another package

A package without an exports field accepts every subpath except src/. Packages that cannot be found are not checked.

Solution layout

A solution package can split its sources into subpath folders:

src/
  ci/        Collective Intelligence entity and capability declarations
  domain/    domain model, free of runtime concerns
  api/       API contracts
  server/    server handlers and runtime wiring
  headless/  UI state without rendering
  views/     rendered UI

These rules keep those folders apart.

subpath-imports

The rule checks relative imports and imports through the package's own name (@acme/billing/server from src/views/).

subpath-entrypoint

An import from another subpath folder targets the folder or its index file. Imports inside one subpath folder are free.

// src/views/table.ts
import { invoiceTotal } from "../domain" // valid
import { invoiceTotal } from "../domain/index.ts" // valid
import { rate } from "../domain/rates" // reported

subpath-index

Every subpath folder under src/ has an index.ts or index.tsx entrypoint. The rule reports each file in a folder that has neither.

Effect convention

An app keeps its side effects in XState machines: each side effect is a fromEffect actor, views read data through TanStack Query, and writes refresh those reads through the SDK QueryCache. These rules check the parts of that convention that imports and calls show.

effect-subpath

A Collective Intelligence SDK (@collective-intelligence/*) exposes its Effect API at <sdk>/effect and <sdk>/effect/<adapter>. The rule reports an SDK path that names Effect elsewhere: a <sdk>-effect package, or an effect segment below another subpath. It also reports each SDK path that the release after 0.2.0 removes, with its replacement:

import { CiClient } from "@collective-intelligence/external-apps-client-sdk/effect" // valid
import { createClient } from "@collective-intelligence/external-apps-client-sdk" // valid
import { Realtime } from "@collective-intelligence/external-apps-client-sdk/realtime/effect" // reported
import { CiRuntime } from "@collective-intelligence/external-apps-server-sdk/runtime/effect" // reported: removed

no-run-in-view

A view module is a .tsx or .jsx file, or a file in the views/ subpath of a solution package. The rule reports a call of the global fetch (also globalThis.fetch and window.fetch) and each use of an Effect run function (runPromise, runSync, runFork and the other run* functions of Effect and ManagedRuntime):

• a read from any object, called or passed as a value: Effect.runPromise(x), runtime.runSync(x), x.pipe(Effect.runPromise);
• a key in a destructuring pattern: const { runFork } = runtime;
• a named import from effect, effect/* or @effect/*: import { runPromise } from "effect/Effect".

A constant name in brackets or quotes counts too: window["fetch"](url), Effect[`runSync`](x) and const { "runFork": fork } = runtime are reported. A local binding named fetch, globalThis or window, a method such as cache.fetch, a name in brackets that only runtime gives (Effect[key]) and an object literal key such as { runPromise: run } are not reported. To allow the calls in view tests, turn the rule off for the test files in an overrides entry.

effect-actors

The rule reports each fromPromise, fromCallback, fromObservable and fromEventObservable that an import, a re-export or a namespace import (XState.fromPromise, XState["fromPromise"], const { fromPromise } = XState) takes from xstate or xstate/*. Make side-effect actors 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 hosted Studio Widget. Machines and fromTransition actors have no side effects and are not reported. A local name that shadows the namespace import, such as a parameter named XState, is not reported.

effect-writes

The rule reports each useMutation that an import, a re-export or a namespace import (ReactQuery.useMutation, ReactQuery["useMutation"], const { useMutation } = ReactQuery) takes from @tanstack/react-query. 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 hosted Studio Widget; after the write, the actor refreshes reads through the QueryCache of the same entrypoint (invalidate, setData).

The rule checks every module. useMutation runs only during a React render, so a module that takes it is a view, a hook or a helper of one of them.

useQuery and the other reads are not reported, and neither are useMutationState and useIsMutating: they only read the state of a useMutation. A useMutation from another library, such as @apollo/client, is not reported. The entity hooks of @collective-intelligence/external-apps-client-sdk-react/resources (useEntityCreate, useEntityUpdate, useEntityDelete) are not reported: the SDK writes and refreshes its own entity reads.

The rule checks no query key. An app that builds the SDK's "ci-entities" key by hand, for example in invalidateQueries, is not reported: the SDK owns that key for its entity reads but exports no key or refresh function for them yet, so a report would have no supported fix.

Adding a rule

Each rule is a plain Oxlint rule in its own folder, src/rules/<rule>/:

1. Write src/rules/<rule>/<rule>.ts. Export a LintRule (src/rule.ts) with:

   • group: the rule group in the table above (add a group to RuleGroup when no group fits);
   • rule: the rule from defineRule of @oxlint/plugins, with a messages entry in meta for each finding. src/rule.ts holds the shared helpers: moduleSpecifiers builds a visitor that checks every module specifier, staticPropertyName reads a constant property name, and declaredVariable finds the variable that a name refers to.

   A rule reads the workspace through src/workspace/: packageOf and installedPackage find package manifests, declaresEntrypoint checks exports, and layoutFile finds the subpath of a file.

2. Add one line to the registry, src/rules/index.ts. The plugin, the recommended config and the RuleName type follow from it.

3. Write src/rules/<rule>/<rule>.test.ts against the fixture workspace in test/fixtures/workspace/, and add fixture files for the new cases. Add the new diagnostics to the expectations of src/index.test.ts.

4. Add the rule to the table above, and to CHANGELOG.md.

Oxlint calls rule visitors synchronously, so a rule reads files with the synchronous node:fs API: it cannot wait for a promise or a timer. The workspace lookups cache each folder they visit, so each package.json is read once per plugin load.