@lucasacoutinho/archer 0.2.1 → 0.3.0

package/package.json

@@ -1,19 +1,13 @@
 {
   "name": "@lucasacoutinho/archer",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Architecture tests for TypeScript and JavaScript projects",
   "keywords": [
     "architecture",
     "architecture-testing",
-    "archunit",
     "boundaries",
-    "bun",
     "dependency-rules",
-    "javascript",
-    "jest",
-    "monorepo",
-    "typescript",
-    "vitest"
+    "typescript"
   ],
   "homepage": "https://github.com/lucasacoutinho/archer#readme",
   "bugs": {
@@ -25,194 +19,52 @@
     "type": "git",
     "url": "git+https://github.com/lucasacoutinho/archer.git"
   },
-  "bin": {
-    "archer": "dist/cli.js"
-  },
+  "type": "module",
   "files": [
     "dist",
     "skills",
-    "README.md",
     "LICENSE",
     "NOTICE"
   ],
-  "type": "module",
-  "sideEffects": [
-    "./dist/bun/plugin.*",
-    "./dist/jest/plugin.*",
-    "./dist/vitest/plugin.*"
-  ],
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "typesVersions": {
-    "*": {
-      "vitest": [
-        "dist/vitest.d.ts"
-      ],
-      "vitest/plugin": [
-        "dist/vitest/plugin.d.ts"
-      ],
-      "jest": [
-        "dist/jest.d.ts"
-      ],
-      "jest/plugin": [
-        "dist/jest/plugin.d.ts"
-      ],
-      "bun": [
-        "dist/bun.d.ts"
-      ],
-      "bun/plugin": [
-        "dist/bun/plugin.d.ts"
-      ],
-      "node": [
-        "dist/node.d.ts"
-      ],
-      "*": [
-        "dist/index.d.ts"
-      ]
-    }
-  },
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
-    },
-    "./vitest": {
-      "import": {
-        "types": "./dist/vitest.d.ts",
-        "default": "./dist/vitest.js"
-      },
-      "require": {
-        "types": "./dist/vitest.d.cts",
-        "default": "./dist/vitest.cjs"
-      }
-    },
-    "./vitest/plugin": {
-      "import": {
-        "types": "./dist/vitest/plugin.d.ts",
-        "default": "./dist/vitest/plugin.js"
-      },
-      "require": {
-        "types": "./dist/vitest/plugin.d.cts",
-        "default": "./dist/vitest/plugin.cjs"
-      }
-    },
-    "./jest": {
-      "import": {
-        "types": "./dist/jest.d.ts",
-        "default": "./dist/jest.js"
-      },
-      "require": {
-        "types": "./dist/jest.d.cts",
-        "default": "./dist/jest.cjs"
-      }
-    },
-    "./jest/plugin": {
-      "import": {
-        "types": "./dist/jest/plugin.d.ts",
-        "default": "./dist/jest/plugin.js"
-      },
-      "require": {
-        "types": "./dist/jest/plugin.d.cts",
-        "default": "./dist/jest/plugin.cjs"
-      }
-    },
-    "./bun": {
-      "import": {
-        "types": "./dist/bun.d.ts",
-        "default": "./dist/bun.js"
-      },
-      "require": {
-        "types": "./dist/bun.d.cts",
-        "default": "./dist/bun.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
-    "./bun/plugin": {
-      "import": {
-        "types": "./dist/bun/plugin.d.ts",
-        "default": "./dist/bun/plugin.js"
-      },
-      "require": {
-        "types": "./dist/bun/plugin.d.cts",
-        "default": "./dist/bun/plugin.cjs"
-      }
-    },
-    "./node": {
-      "import": {
-        "types": "./dist/node.d.ts",
-        "default": "./dist/node.js"
-      },
-      "require": {
-        "types": "./dist/node.d.cts",
-        "default": "./dist/node.cjs"
-      }
+    "./effect": {
+      "types": "./dist/effect.d.ts",
+      "default": "./dist/effect.js"
     }
   },
+  "bin": {
+    "archer": "dist/cli/main.js"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=22.18.0"
+  },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "tsup",
-    "check": "npm run fmt:check && npm run lint && npm run typecheck && npm test && npm run test:adapters && npm run build",
-    "check:package": "npm run build && publint && attw --pack .",
-    "fmt": "oxfmt --write .",
-    "fmt:check": "oxfmt --check .",
-    "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
-    "prepublishOnly": "npm run check",
-    "release:check": "npm run check && npm run check:package && npm audit --omit=dev && npm pack --dry-run",
+    "prepare": "effect-tsgo patch --typescript --no-oxlint",
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json && sh scripts/check-declarations.sh",
     "test": "vitest run",
-    "test:adapters": "npm run build && npm run test:jest && npm run test:node && npm run test:bun && npm run test:cli && npm run test:dogfood",
-    "test:bun": "bun test test/runners/bun-adapter.test.mjs",
-    "test:cli": "node --test test/runners/cli.test.mjs",
-    "test:dogfood": "node dist/cli.js check --config archer.config.ts",
-    "test:jest": "jest --runInBand --runTestsByPath test/runners/jest-adapter.test.cjs",
-    "test:node": "node --test test/runners/node-adapter.test.mjs",
-    "test:tia": "vitest run --config vitest.tia.config.ts",
-    "test:tia:verify": "node config/run-tiacore.mjs verify --output .tia/verification.json -- npm run test:tia",
-    "typecheck": "tsc --noEmit"
+    "smoke:bun": "bun scripts/bun-smoke.mjs",
+    "lean": "sh scripts/lean-audit.sh",
+    "check": "npm run lean && npm run typecheck && npm test && npm run build && npm run dogfood",
+    "dogfood": "node dist/cli/main.js check"
   },
   "dependencies": {
-    "chokidar": "^5.0.0",
-    "commander": "^14.0.3",
-    "jiti": "^2.7.0",
-    "picomatch": "^4.0.3",
-    "tinyglobby": "^0.2.15",
-    "typescript": "^5.9.0"
+    "@effect/platform-node": "4.0.6",
+    "effect": "4.0.6",
+    "typescript": "7.0.2"
   },
   "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.2",
-    "@jest/globals": "^30.4.1",
-    "@types/bun": "^1.3.14",
-    "@types/node": "^24.0.0",
-    "@types/picomatch": "^4.0.2",
-    "jest": "^30.4.2",
-    "oxfmt": "^0.61.0",
-    "oxlint": "^1.76.0",
-    "publint": "^0.3.12",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.0",
-    "vitest": "^4.0.0"
-  },
-  "peerDependencies": {
-    "@jest/globals": ">=29.0.0 <31.0.0",
-    "vitest": ">=3.0.0 <5.0.0"
-  },
-  "peerDependenciesMeta": {
-    "@jest/globals": {
-      "optional": true
-    },
-    "vitest": {
-      "optional": true
-    }
-  },
-  "engines": {
-    "node": ">=20.0.0"
+    "@effect/tsgo": "0.56.1",
+    "@effect/vitest": "4.0.6",
+    "@types/node": "22.20.5",
+    "vitest": "5.0.5"
   }
 }

package/skills/archer/SKILL.md

@@ -1,81 +1,163 @@
 ---
 name: archer
-description: Add, configure, run, and repair Archer architecture tests for JavaScript and TypeScript projects. Use when an agent needs to enforce module boundaries, named layers, dependency direction, public entrypoints, cycles, declaration conventions, or import rules; integrate Archer with its CLI, Vitest, Jest, Bun, or node:test; or interpret and fix Archer violations.
+description: Set up, run, and fix architecture rules in TypeScript and JavaScript repositories with Archer (@lucasacoutinho/archer). Covers archer.config.ts (layers, stack, allow, publicApis, r.* rules), `archer check -r agent`, repairing violations in source without weakening the policy, baselines for adopting Archer on existing debt, and the one-line architecture test. Use when the user wants to enforce layers, module boundaries, dependency direction, import cycles, or public entrypoints, when the repo has an archer.config.* file, or when `archer check` or an architecture test reports findings. Do not use for ESLint import rules or other dependency linters.
 ---
 
 # Archer
 
-Use Archer to make architectural constraints executable. Prefer rules that describe an existing design decision and produce a specific source change when they fail.
+Archer turns architecture decisions into rules that fail the build. A rule is plain data in `archer.config.ts`. `archer check` analyzes the project with TypeScript and reports every violation with its import site.
 
-## Inspect the project
+The rules are the user's policy. When a rule fails, change the source.
 
-1. Read `package.json`, workspace configuration, and relevant `tsconfig` files.
-2. Find existing `archer.config.*` and architecture tests before adding another entrypoint.
-3. Identify real dependency directions from imports. Do not infer layers from folder names alone when the code says otherwise.
-4. Read the installed Archer README or declarations when its version may differ from this skill.
+## Ground rules
 
-## Set up Archer
+- Fix findings in source. Do not delete or loosen a rule, lower a severity, widen `allow`, add a `{ not: ... }` exclusion, set `localOnly`, narrow `kinds`, set `allowComputed`, or record a baseline to get a green check.
+- Make any of those changes only when the user asks for it. If a finding looks wrong or the rule looks outdated, say so and propose the change.
+- Never claim a boundary holds when Archer could not prove it. Say what it could not see (see "Computed imports").
 
-Install `@lucasacoutinho/archer` as a development dependency with the repository's package manager. Prefer the CLI for a runner-independent check:
+## Inspect first
+
+1. Look for `archer.config.{ts,mts,js,mjs}`, `.archer-baseline`, and an existing architecture test. Update what exists instead of adding a second entrypoint.
+2. Read `package.json` and the tsconfig files. Archer analyzes only the files that the tsconfigs in `projects` list (default `tsconfig.json`). A file outside them is invisible to every rule, so list each package's tsconfig in a monorepo.
+3. Read real imports before choosing layers. Folder names suggest layers, but the imports show which directions the code already follows. Ask the user when the intended direction is not clear.
+4. If the installed version may differ from this skill, read `node_modules/@lucasacoutinho/archer/dist/index.d.ts`.
+
+## Set up
+
+Install `@lucasacoutinho/archer` as a dev dependency with the repo's package manager. It needs Node 22.18 or later. Run `npx archer init` (or the package manager's local-exec equivalent) to write a starter `archer.config.ts`, then edit it to match the repo:
 
 ```ts
-import { defineConfig } from '@lucasacoutinho/archer'
+import { defineConfig, presets, r } from "@lucasacoutinho/archer"
 
 export default defineConfig({
-  rules(archer) {
-    archer
-      .expect('src/domain/**')
-      .not.toDependOn('src/infrastructure/**')
-      .as('boundaries/domain-isolation')
-      .because('Domain code must remain independent of adapters.')
-
-    archer.expect('src/**').toBeFreeOfCycles().as('dependencies/no-cycles')
+  layers: {
+    web: "src/web",
+    application: "src/application",
+    domain: "src/domain",
+    infrastructure: "src/infrastructure",
   },
+  stack: ["web", "application", "domain"],
+  allow: { infrastructure: ["application", "domain"] },
+  publicApis: { domain: "src/domain/index.ts" },
+  rules: [
+    ...presets.recommended,
+    r.forbid("domain/pure", "layer:domain", ["npm:*", "node:*"], {
+      reason: "The domain stays free of frameworks and I/O.",
+    }),
+  ],
 })
 ```
 
-Run the locally installed binary. With npm, use `npx --no-install archer check`; use the package manager's equivalent local-exec command elsewhere. Add that command to CI after it passes locally.
+- `layers` names a selector per layer. Rules refer to it as `layer:name`.
+- `stack` lists layers from top to bottom. Each layer may import the layers listed after it.
+- `allow` adds layers a layer may import beyond its position in the stack.
+- `publicApis` names, per layer, the entry files that other layers must import through.
+- `rules` takes `r.*` constructors. Every rule needs an id that is unique and stays stable, because findings and baselines key on it.
+- `projects`, `root`, `baseline`, and `failOnWarnings` are described in [references/rules.md](references/rules.md), together with every `r.*` constructor and the selector grammar. Open it when writing or reading a rule.
 
-Use `arch()` when the check should be registered as a test:
+Layer rules constrain only direct imports of local files that belong to another declared layer. They ignore packages, built-ins, files outside every layer, and computed imports. Use `r.forbid` or `r.onlyDependOn` with `npm:*` or `node:*` for those. A layer named in neither `stack` nor `allow` has no limits of its own, but constrained layers may not import it unless `allow` says so, so put shared code at the bottom of `stack`.
 
-```ts
-import { arch } from '@lucasacoutinho/archer/vitest'
+The starter config names `src/app`, which may not exist. A rule whose subject matches no file passes, and so does the generated `layer/<name>` rule of an empty layer. Both are listed in `emptySubjects` in the summary line. Read that list after every run, and fix a non-empty one unless the code is meant to appear later.
 
-arch('domain boundaries').expect('src/domain/**').not.toDependOn('src/infrastructure/**')
+A dependency rule whose target names files by a glob but selects none is listed in `emptyObjects`. That is almost always a mistyped path. A target that names only packages is never listed, so for package targets run the new rule against a minimal case (see "Test a rule without the filesystem" in the reference).
+
+If the first run shows many violations, check the layer order and selectors before you blame the code.
+
+## Run
+
+```sh
+npx archer check -r agent
 ```
 
-Replace `vitest` with `jest`, `bun`, or `node` for another adapter.
+The command exits 0 when the verdict is `pass` and 1 when it is `fail`. It exits 2 when it cannot check, including on an unknown flag or value. The output has one `finding` line per violation and a `summary` line last:
 
-Use the matcher plugin when a project prefers `expect` assertions. Add `@lucasacoutinho/archer/vitest/plugin` to Vitest `setupFiles`, `@lucasacoutinho/archer/jest/plugin` to Jest `setupFilesAfterEnv`, or `@lucasacoutinho/archer/bun/plugin` to Bun's test `preload`. Then await `expect(archer).toRespectArchitecture()` in a dedicated architecture test.
+```text
+finding id="layer/domain|/src/domain/order.ts|dependency|static|../infrastructure/db.ts|file|/src/infrastructure/db.ts" severity=error rule="layer/domain" subject="src/domain/order.ts" at="src/domain/order.ts:1:25" message="imports src/infrastructure/db.ts ('../infrastructure/db.ts')"
+summary verdict=fail errors=1 warnings=0 infos=0 suppressed=0 stale=0 files=2 dependencies=1 emptySubjects=[] emptyObjects=[]
+```
 
-## Write rules
+- `id` is the fingerprint: rule, file, and what was found, with no line numbers or wording. It survives moving lines but changes when the specifier or target changes, so a finding is fixed when its `id` no longer appears. A file that repeats one import produces several lines with the same `id`.
+- `severity`: `error` fails the check, `warning` fails it only with `failOnWarnings: true`, `info` never does.
+- `rule` is a rule id from the config, or a generated `layer/<name>` or `public-api/<layer>`.
+- `subject` is the file that breaks the rule.
+- `at` is `file:line:column` of the import, call, or declaration. Findings about a whole file (missing dependency, export, file name, line count) have no `at`.
+- `message` says what Archer found. `reason` is the rule's stated reason, when it has one. Read it before you choose a fix.
+- In the summary, `suppressed` counts findings the baseline hides, `stale` counts baseline entries that no finding matches, `emptySubjects` lists rule ids that select no file, and `emptyObjects` lists dependency rules whose file-glob target selects nothing.
 
-- Start with high-confidence boundaries, cycles, and public entrypoints.
-- Give durable rules an ID with `.as()` and record the reason with `.because()`.
-- Use `.localDependencies()` for layer allow-lists so npm and platform modules do not need repetition.
-- Use dependency-kind modifiers when type-only, runtime, or dynamic coupling has different meaning.
-- Treat `dynamic:unknown` as unproven. Do not allow it just to make a check pass.
-- Avoid broad ignores. Narrow an exception to the smallest selector and explain it.
+Other flags:
 
-Read [references/rules.md](references/rules.md) for selectors, dependency modifiers, named layers, semantic expectations, and presets.
+- `-c <file>` picks a config.
+- `-o <file>` writes the report to a file.
+- `-w` re-runs on change.
+- `--ignore-baseline` reports baselined findings too.
+- `--graph <file>` checks a graph saved with `archer graph -o <file>`. The other reporters are `pretty` (the default), `json`, `sarif`, `github`, and `dot`.
 
-## Diagnose and fix findings
+Exit code 2 means Archer could not check at all, and the message says why. Typical causes:
 
-Run:
+- **Invalid configuration, with a list of issues.** A field has the wrong shape. A selector does not parse (`[a-z]`, `a//b`, unbalanced braces, a bad `npm:` name). A layer is named like an integer such as `"0"`. A `layers` or `publicApis` selector uses `layer:`.
+- **Invalid configuration, with one reason.** A rule, `stack`, `allow`, or `publicApis` refers to an unknown layer. Two rules share an id, and a generated `layer/<name>` counts. Or the config produces no rules at all.
+- **No configuration file.** No `archer.config.*` is in the current directory. Pass `-c`.
+- **No tsconfig, or one that does not parse.** A tsconfig in `projects` is missing or invalid. Check `projects` and `root`.
 
-```sh
-npx --no-install archer check --reporter agent
+## Fix findings
+
+Read the summary line first. Then take findings by rule, open the file at `at`, read `reason`, and change the code. After each batch, re-run `archer check -r agent`, then the repo's typecheck and tests.
+
+| Finding | Usual fix |
+| --- | --- |
+| `layer/*`, `r.forbid`, `r.onlyDependOn`: "imports X" | Move the code into a layer that may own it. Or invert the dependency: put an interface in the lower layer, implement it in the higher one, and pass the implementation in. Deleting the import is a fix only when the code does not need it. |
+| `public-api/*` | Import through the layer's entry file. If the symbol belongs to the public surface, export it from that entry file. |
+| `archer/acyclic`: "is part of a dependency cycle: a.ts → b.ts → a.ts" | Move what both sides need into a third file that neither imports back. Every file in a cycle gets its own finding, so one fix clears several. |
+| Transitive rule: "depends on x.ts through a.ts → b.ts → x.ts" | Cut the chain at the link that crosses the boundary. `at` is the first import in the chain, and the wrong link may be further down. |
+| "does not satisfy the rule's requirement" | A `require`-style rule found nothing. Add the dependency, dependent, or call it asks for. |
+| Declarations, exports, calls, file names, line counts | Change the declaration, narrow the exports, replace the call, rename the file, or split it. |
+| Custom rule | The message is whatever the rule's check wrote. Read the check in the config. |
+
+A fix that moves a file changes which layer it belongs to, so check that the new location is the one the layer selectors expect.
+
+### Computed imports
+
+An `import(expr)` or `require(expr)` with a non-literal specifier has no static target, so Archer fails closed. `r.forbid` and `r.onlyDependOn` report it whatever the rule's object is, because it might load anything. `r.require` is never satisfied by one. `archer/resolvable`, which `presets.recommended` includes, reports it too. Layer rules skip it, because they follow local files only.
+
+Replace the computed specifier with literals, so every target is analyzed and checked against the layers:
+
+```ts
+const locales = {
+  en: () => import("./locales/en.ts"),
+  pt: () => import("./locales/pt.ts"),
+}
 ```
 
-The first line contains the status and counts. Each remaining line is one finding with location, severity, rule ID, message, and any dependency, source, reason, or import chain.
+If the dynamic load is deliberate, such as a plugin loader, tell the user. The usual policy for that is a narrow `r.resolvable(..., { allowComputed: true, reason })` on that one file, plus excluding the file from the subjects of the other rules that flag it. Apply that only after the user agrees, and name the file as unverified in your report.
+
+## Baselines
+
+A baseline is for adopting Archer in a codebase that already has violations. Use it only when the user agrees to accept the current debt.
+
+1. Run `npx archer check -r agent`, fix what is cheap, and confirm that every remaining finding is debt the user accepts.
+2. Run `npx archer baseline record`. It replaces `.archer-baseline` (the `baseline` field sets the path) with the fingerprints of all current findings. Commit the file.
+3. From then on, the baselined findings are hidden and counted in `suppressed`. A new error still fails the check.
+4. As the debt gets fixed, `stale` grows. Run `npx archer baseline prune` to drop entries that no finding matches. It never adds an entry.
+
+One entry hides every finding with that `id`, so a second copy of an already baselined import in the same file is hidden too. Do not run `record` to clear a failing check, and do not edit the baseline by hand. Renaming a rule id orphans that rule's entries, and its old findings come back.
+
+## Add the test
+
+Add one test next to the repo's other tests, written for its runner:
+
+```ts
+import { assertArchitecture, dispose } from "@lucasacoutinho/archer"
+import { afterAll, test } from "vitest"
+
+afterAll(dispose)
+
+test("architecture", () => assertArchitecture(), 60_000)
+```
 
-1. Open the reported file and follow the import chain when present.
-2. Fix the source dependency or declaration that violates the stated rule.
-3. Re-run the narrow Archer command, then the repository's normal checks.
-4. Do not weaken a rule, add an ignore, or update the baseline unless the user explicitly approves that policy change.
+`assertArchitecture` runs the whole check and rejects with an `ArchitectureError` when the verdict is `fail`. The error message is the pretty report, and `error.report` holds the data. It takes `{ config, cwd }`: `config` is a file path or an inline config, and `cwd` defaults to the process directory, so pass it when the runner starts elsewhere. Analysis can take a while on a large repo, so raise the runner's timeout. `dispose` stops the TypeScript server that the first run started, as Archer's own test does.
 
-Use `--update-baseline` only for deliberate staged adoption in an existing codebase. Commit the baseline when the project treats it as policy.
+Add `archer check` to the repo's CI or a `package.json` script when the user wants the check outside the test run.
 
-## Report the result
+## Report
 
-State which rules or files changed and include the final Archer summary. Separate source fixes from rule-policy changes. If computed imports, runtime injection, or generated code prevent static proof, name that limitation instead of claiming the boundary passed.
+List the findings you fixed and the ones that remain, by `rule` and `id`. Report policy changes (rules, baseline, config) separately from source fixes, and say whether the user asked for them. Name anything Archer could not see: computed imports, files outside the tsconfigs, rules in `emptySubjects` or `emptyObjects`. End with the final `summary` line.

package/skills/archer/agents/openai.yaml

@@ -1,4 +1,4 @@
 interface:
   display_name: 'Archer architecture tests'
-  short_description: 'Add and enforce TypeScript architecture rules'
-  default_prompt: 'Use $archer to add architecture tests to this TypeScript project and fix any reported violations.'
+  short_description: 'Add and enforce TypeScript and JavaScript architecture rules'
+  default_prompt: 'Use $archer to set up Archer in this repository, run the architecture check, and fix any findings in source without weakening the rules.'