@collective-intelligence/lint 0.0.0-stage → 0.1.21

package/README.md

@@ -1,3 +1,172 @@
-# Temporary Holding Version
+# @collective-intelligence/lint
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+```sh
+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:
+
+```ts
+import { recommended } from "@collective-intelligence/lint"
+import { defineConfig } from "oxlint"
+
+export default defineConfig({
+  extends: [recommended]
+})
+```
+
+To change one rule, set it after the extend:
+
+```ts
+export default defineConfig({
+  extends: [recommended],
+  rules: { "ci-solution/subpath-index": "warn" }
+})
+```
+
+### Selected rules
+
+Load the plugin and enable only the rules you want:
+
+```ts
+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:
+
+```json
+{
+  "jsPlugins": ["@collective-intelligence/lint"],
+  "rules": { "ci-solution/package-entrypoint": "error" }
+}
+```
+
+The `RuleName` type lists every rule name.
+
+## Rules
+
+| Rule                             | Enforces                                                                                   | Group              |
+| -------------------------------- | ------------------------------------------------------------------------------------------ | ------------------ |
+| `ci-solution/package-entrypoint` | An import of another package targets an entrypoint declared in its `package.json` exports. | Package boundaries |
+| `ci-solution/subpath-imports`    | Imports between subpath folders follow the allowed direction.                              | Solution layout    |
+| `ci-solution/subpath-entrypoint` | An import from another subpath folder targets the folder or its index file.                | Solution layout    |
+| `ci-solution/subpath-index`      | Every subpath folder has an `index.ts` or `index.tsx`.                                     | Solution layout    |
+
+### 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.
+
+```ts
+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:
+
+```text
+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`
+
+| Folder      | Must not import                         |
+| ----------- | --------------------------------------- |
+| `domain/`   | `server/`, `views/`, `headless/`, `ci/` |
+| `ci/`       | `views/`, `headless/`                   |
+| `headless/` | `server/`                               |
+| `views/`    | `server/`                               |
+| `api/`      | no limit                                |
+| `server/`   | no limit                                |
+
+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.
+
+```ts
+// 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.
+
+## 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. `moduleSpecifiers`
+     (`src/rule.ts`) builds a visitor that checks every module specifier.
+
+   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.

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { Plugin } from "@oxlint/plugins";
+import { rules } from "./rules/index.ts";
+declare const plugin: Plugin;
+export type RuleName = `ci-solution/${keyof typeof rules}`;
+export interface RecommendedConfig {
+    jsPlugins: string[];
+    rules: Record<RuleName, "error">;
+}
+export declare const recommended: RecommendedConfig;
+export default plugin;

package/dist/index.js

@@ -0,0 +1,354 @@
+// src/index.ts
+import { definePlugin } from "@oxlint/plugins";
+
+// src/rules/package-entrypoint/package-entrypoint.ts
+import { defineRule } from "@oxlint/plugins";
+import path2 from "node:path";
+
+// src/rule.ts
+var isStringLiteral = (node) => node?.type === "Literal" && String(node.value) === node.value;
+var moduleSpecifiers = (check) => {
+  const visit = (node) => {
+    if (isStringLiteral(node)) {
+      check(node);
+    }
+  };
+  return {
+    CallExpression: (node) => {
+      if (node.callee.type === "Identifier" && node.callee.name === "require" && node.arguments.length === 1) {
+        visit(node.arguments[0] ?? null);
+      }
+    },
+    ExportAllDeclaration: (node) => {
+      visit(node.source);
+    },
+    ExportNamedDeclaration: (node) => {
+      visit(node.source);
+    },
+    ImportDeclaration: (node) => {
+      visit(node.source);
+    },
+    ImportExpression: (node) => {
+      visit(node.source);
+    }
+  };
+};
+
+// src/workspace/package-exports.ts
+var parseExports = (exports) => {
+  const subpaths = exports instanceof Object && !Array.isArray(exports) ? Object.entries(exports) : [];
+  return subpaths.some(([key]) => key.startsWith(".")) ? new Map(subpaths.map(([key, target]) => [key, target !== null])) : new Map([[".", exports !== null]]);
+};
+var packageInfo = (root, fields) => ({
+  exports: fields.exports === undefined ? null : parseExports(fields.exports),
+  name: fields.name ?? null,
+  root
+});
+var parsePackageSpecifier = (specifier) => {
+  if (/^(?:[./#]|[a-z][a-z\d+.-]*:)/iu.test(specifier)) {
+    return null;
+  }
+  const parts = specifier.split("/");
+  const nameLength = specifier.startsWith("@") ? 2 : 1;
+  return {
+    name: parts.slice(0, nameLength).join("/"),
+    subpath: parts.slice(nameLength).join("/")
+  };
+};
+var matchPattern = (exports, key) => {
+  let best = null;
+  for (const [pattern, exported] of exports) {
+    const star = pattern.indexOf("*");
+    const prefix = pattern.slice(0, star);
+    const suffix = pattern.slice(star + 1);
+    if (star !== -1 && key.length >= pattern.length && key.startsWith(prefix) && key.endsWith(suffix) && (best === null || prefix.length > best.prefix)) {
+      best = { exported, prefix: prefix.length };
+    }
+  }
+  return best?.exported === true;
+};
+var declaresEntrypoint = (target, subpath) => {
+  if (target.exports === null) {
+    return subpath !== "src" && !subpath.startsWith("src/");
+  }
+  const key = subpath === "" ? "." : `./${subpath}`;
+  return target.exports.get(key) ?? matchPattern(target.exports, key);
+};
+
+// src/workspace/workspace.ts
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+var readPackage = (root) => {
+  const file = path.join(root, "package.json");
+  if (!existsSync(file)) {
+    return null;
+  }
+  const fields = JSON.parse(readFileSync(file, "utf-8"));
+  return packageInfo(root, fields);
+};
+var owners = new Map;
+var installed = new Map;
+var packageOf = (target) => {
+  const cached = owners.get(target);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const parent = path.dirname(target);
+  const owner = readPackage(target) ?? (parent === target ? null : packageOf(parent));
+  owners.set(target, owner);
+  return owner;
+};
+var installedPackage = (directory, name) => {
+  const key = `${directory}\x00${name}`;
+  const cached = installed.get(key);
+  if (cached !== undefined) {
+    return cached;
+  }
+  const parent = path.dirname(directory);
+  const found = readPackage(path.join(directory, "node_modules", name)) ?? (parent === directory ? null : installedPackage(parent, name));
+  installed.set(key, found);
+  return found;
+};
+
+// src/rules/package-entrypoint/package-entrypoint.ts
+var packageName = (target) => target.name ?? path2.basename(target.root);
+var packageEntrypoint = {
+  group: "package-boundaries",
+  rule: defineRule({
+    create(context) {
+      const directory = path2.dirname(context.filename);
+      const owner = packageOf(directory);
+      if (owner === null) {
+        return {};
+      }
+      return moduleSpecifiers((node) => {
+        const specifier = node.value;
+        if (specifier.startsWith(".")) {
+          const target = packageOf(path2.resolve(directory, specifier));
+          if (target !== null && target.root !== owner.root) {
+            context.report({
+              data: { name: packageName(target), specifier },
+              messageId: "relative",
+              node
+            });
+          }
+          return;
+        }
+        const parsed = parsePackageSpecifier(specifier);
+        if (parsed === null) {
+          return;
+        }
+        const target = parsed.name === owner.name ? owner : installedPackage(directory, parsed.name);
+        if (target !== null && !declaresEntrypoint(target, parsed.subpath)) {
+          context.report({
+            data: { name: parsed.name, specifier },
+            messageId: "undeclared",
+            node
+          });
+        }
+      });
+    },
+    meta: {
+      docs: {
+        description: "Require imports of another package to target an entrypoint declared in its package.json exports."
+      },
+      messages: {
+        relative: "`{{specifier}}` reaches into package `{{name}}` through a relative path. Import it by its package name and a declared entrypoint.",
+        undeclared: "`{{specifier}}` is not a declared entrypoint of `{{name}}`. Import the package root or a subpath listed in its package.json exports."
+      },
+      type: "problem"
+    }
+  })
+};
+
+// src/rules/subpath-entrypoint/subpath-entrypoint.ts
+import { defineRule as defineRule2 } from "@oxlint/plugins";
+import path4 from "node:path";
+
+// src/workspace/layout.ts
+import path3 from "node:path";
+var SUBPATHS = [
+  "ci",
+  "domain",
+  "api",
+  "server",
+  "headless",
+  "views"
+];
+var isSubpath = (folder) => SUBPATHS.some((subpath) => subpath === folder);
+var subpathOfSegments = (segments) => {
+  const [folder] = segments ?? [];
+  return isSubpath(folder) ? folder : null;
+};
+var sourceSegments = (root, target) => {
+  const relative = path3.relative(path3.join(root, "src"), target);
+  return relative === "" || relative.startsWith("..") || path3.isAbsolute(relative) ? null : relative.split(path3.sep);
+};
+var isSubpathEntrypoint = (segments) => {
+  const [, file] = segments;
+  return segments.length === 1 || segments.length === 2 && path3.parse(file ?? "").name === "index";
+};
+var layoutFile = (filename) => {
+  const owner = packageOf(path3.dirname(filename));
+  const segments = owner && sourceSegments(owner.root, filename);
+  const subpath = segments && segments.length > 1 ? subpathOfSegments(segments) : null;
+  return owner && subpath ? { owner, subpath } : null;
+};
+
+// src/rules/subpath-entrypoint/subpath-entrypoint.ts
+var subpathEntrypoint = {
+  group: "solution-layout",
+  rule: defineRule2({
+    create(context) {
+      const directory = path4.dirname(context.filename);
+      const owner = packageOf(directory);
+      const source = owner === null ? null : sourceSegments(owner.root, context.filename);
+      if (owner === null || source === null) {
+        return {};
+      }
+      const sourceSubpath = source.length > 1 ? subpathOfSegments(source) : null;
+      return moduleSpecifiers((node) => {
+        if (!node.value.startsWith(".")) {
+          return;
+        }
+        const target = sourceSegments(owner.root, path4.resolve(directory, node.value));
+        const targetSubpath = subpathOfSegments(target);
+        if (target !== null && targetSubpath !== null && targetSubpath !== sourceSubpath && !isSubpathEntrypoint(target)) {
+          context.report({
+            data: { specifier: node.value, target: targetSubpath },
+            messageId: "deep",
+            node
+          });
+        }
+      });
+    },
+    meta: {
+      docs: {
+        description: "Require imports from another subpath to target the subpath folder or its index file."
+      },
+      messages: {
+        deep: "`{{specifier}}` reaches past the `{{target}}/` entrypoint. Import the subpath folder, which resolves to its index.ts or index.tsx."
+      },
+      type: "problem"
+    }
+  })
+};
+
+// src/rules/subpath-imports/subpath-imports.ts
+import { defineRule as defineRule3 } from "@oxlint/plugins";
+import path5 from "node:path";
+var FORBIDDEN_IMPORTS = {
+  api: [],
+  ci: ["views", "headless"],
+  domain: ["server", "views", "headless", "ci"],
+  headless: ["server"],
+  server: [],
+  views: ["server"]
+};
+var subpathImports = {
+  group: "solution-layout",
+  rule: defineRule3({
+    create(context) {
+      const file = layoutFile(context.filename);
+      if (file === null) {
+        return {};
+      }
+      const { owner, subpath } = file;
+      const directory = path5.dirname(context.filename);
+      const forbidden = FORBIDDEN_IMPORTS[subpath];
+      const targetSubpath = (specifier) => {
+        if (specifier.startsWith(".")) {
+          return subpathOfSegments(sourceSegments(owner.root, path5.resolve(directory, specifier)));
+        }
+        const parsed = parsePackageSpecifier(specifier);
+        return parsed !== null && parsed.name === owner.name ? subpathOfSegments(parsed.subpath.split("/")) : null;
+      };
+      return moduleSpecifiers((node) => {
+        const target = targetSubpath(node.value);
+        if (target !== null && forbidden.includes(target)) {
+          context.report({
+            data: {
+              forbidden: forbidden.map((name) => `\`${name}/\``).join(", "),
+              source: subpath,
+              specifier: node.value,
+              target
+            },
+            messageId: "forbidden",
+            node
+          });
+        }
+      });
+    },
+    meta: {
+      docs: {
+        description: "Disallow imports between subpaths that break the solution package layout direction."
+      },
+      messages: {
+        forbidden: "`{{specifier}}` imports `{{target}}/` from `{{source}}/`. `{{source}}/` must not import {{forbidden}}."
+      },
+      type: "problem"
+    }
+  })
+};
+
+// src/rules/subpath-index/subpath-index.ts
+import { defineRule as defineRule4 } from "@oxlint/plugins";
+import { existsSync as existsSync2 } from "node:fs";
+import path6 from "node:path";
+var INDEX_FILES = ["index.ts", "index.tsx"];
+var subpathIndex = {
+  group: "solution-layout",
+  rule: defineRule4({
+    create(context) {
+      const file = layoutFile(context.filename);
+      if (file === null) {
+        return {};
+      }
+      const folder = path6.join(file.owner.root, "src", file.subpath);
+      if (INDEX_FILES.some((name) => existsSync2(path6.join(folder, name)))) {
+        return {};
+      }
+      return {
+        Program: (node) => {
+          context.report({
+            data: { subpath: file.subpath },
+            messageId: "missing",
+            node
+          });
+        }
+      };
+    },
+    meta: {
+      docs: {
+        description: "Require every subpath folder to have an index.ts or index.tsx entrypoint."
+      },
+      messages: {
+        missing: "Subpath folder `src/{{subpath}}/` has no index.ts or index.tsx entrypoint."
+      },
+      type: "problem"
+    }
+  })
+};
+
+// src/rules/index.ts
+var rules = {
+  "package-entrypoint": packageEntrypoint,
+  "subpath-entrypoint": subpathEntrypoint,
+  "subpath-imports": subpathImports,
+  "subpath-index": subpathIndex
+};
+
+// src/index.ts
+var plugin = definePlugin({
+  meta: { name: "ci-solution" },
+  rules: Object.fromEntries(Object.entries(rules).map(([name, { rule }]) => [name, rule]))
+});
+var recommended = {
+  jsPlugins: ["@collective-intelligence/lint"],
+  rules: Object.fromEntries(Object.keys(rules).map((name) => [`ci-solution/${name}`, "error"]))
+};
+var src_default = plugin;
+export {
+  src_default as default,
+  recommended
+};

package/dist/rule.d.ts

@@ -0,0 +1,7 @@
+import type { ESTree, Rule, Visitor } from "@oxlint/plugins";
+export type RuleGroup = "package-boundaries" | "solution-layout";
+export interface LintRule {
+    readonly group: RuleGroup;
+    readonly rule: Rule;
+}
+export declare const moduleSpecifiers: (check: (literal: ESTree.StringLiteral) => void) => Visitor;

package/dist/rules/index.d.ts

@@ -0,0 +1,7 @@
+import type { LintRule } from "../rule.ts";
+export declare const rules: {
+    readonly "package-entrypoint": LintRule;
+    readonly "subpath-entrypoint": LintRule;
+    readonly "subpath-imports": LintRule;
+    readonly "subpath-index": LintRule;
+};

package/dist/rules/package-entrypoint/package-entrypoint.d.ts

@@ -0,0 +1,2 @@
+import type { LintRule } from "../../rule.ts";
+export declare const packageEntrypoint: LintRule;

package/dist/rules/subpath-entrypoint/subpath-entrypoint.d.ts

@@ -0,0 +1,2 @@
+import type { LintRule } from "../../rule.ts";
+export declare const subpathEntrypoint: LintRule;

package/dist/rules/subpath-imports/subpath-imports.d.ts

@@ -0,0 +1,2 @@
+import type { LintRule } from "../../rule.ts";
+export declare const subpathImports: LintRule;

package/dist/rules/subpath-index/subpath-index.d.ts

@@ -0,0 +1,2 @@
+import type { LintRule } from "../../rule.ts";
+export declare const subpathIndex: LintRule;

package/dist/workspace/layout.d.ts

@@ -0,0 +1,11 @@
+import type { PackageInfo } from "./package-exports.ts";
+export declare const SUBPATHS: readonly ["ci", "domain", "api", "server", "headless", "views"];
+export type Subpath = (typeof SUBPATHS)[number];
+export declare const subpathOfSegments: (segments: readonly string[] | null) => Subpath | null;
+export declare const sourceSegments: (root: string, target: string) => readonly string[] | null;
+export declare const isSubpathEntrypoint: (segments: readonly string[]) => boolean;
+export interface LayoutFile {
+    readonly owner: PackageInfo;
+    readonly subpath: Subpath;
+}
+export declare const layoutFile: (filename: string) => LayoutFile | null;

package/dist/workspace/package-exports.d.ts

@@ -0,0 +1,19 @@
+export type ExportsField = string | null | readonly ExportsField[] | {
+    readonly [key: string]: ExportsField;
+};
+export interface Manifest {
+    readonly exports?: ExportsField;
+    readonly name?: string;
+}
+export interface PackageInfo {
+    readonly exports: ReadonlyMap<string, boolean> | null;
+    readonly name: string | null;
+    readonly root: string;
+}
+export declare const packageInfo: (root: string, fields: Manifest) => PackageInfo;
+export interface PackageSpecifier {
+    readonly name: string;
+    readonly subpath: string;
+}
+export declare const parsePackageSpecifier: (specifier: string) => PackageSpecifier | null;
+export declare const declaresEntrypoint: (target: PackageInfo, subpath: string) => boolean;

package/dist/workspace/workspace.d.ts

@@ -0,0 +1,3 @@
+import type { PackageInfo } from "./package-exports.ts";
+export declare const packageOf: (target: string) => PackageInfo | null;
+export declare const installedPackage: (directory: string, name: string) => PackageInfo | null;

package/package.json

@@ -1,6 +1,50 @@
 {
   "name": "@collective-intelligence/lint",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.21",
+  "description": "Oxlint plugin with the Collective Intelligence lint rules: package boundaries and solution package layout.",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "ci-source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "bun tools/build.ts",
+    "test": "bun test src && bun run test:pack",
+    "test:pack": "bun run build && bun tools/test-pack.ts",
+    "test:unit": "bun test src",
+    "format": "oxfmt --write .",
+    "format:check": "oxfmt --check .",
+    "format:check:staged": "oxfmt --check",
+    "lint:staged": "oxlint --no-error-on-unmatched-pattern",
+    "prepack": "bun run build",
+    "type-check": "bun check",
+    "lint": "oxlint src test tools"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@oxlint/plugins": "^1.85.0"
+  },
+  "peerDependencies": {
+    "oxlint": ">=1.82.0"
+  },
+  "devDependencies": {
+    "bun-types": "^1.4.2",
+    "oxfmt": "0.66.0",
+    "oxlint": "1.82.0",
+    "typescript": "7.0.2",
+    "ultracite": "7.10.7"
+  }
+}