@lucasacoutinho/archer 0.0.0-stage → 0.2.1

package/dist/vitest.d.cts

@@ -0,0 +1,37 @@
+import { TestOptions } from 'vitest';
+import { R as ReporterName } from './reporters-BbAXMpuW.cjs';
+import { A as ArcherOptions, a as ArchitectureSuite } from './suite-BwnPDCvU.cjs';
+export { S as Selector } from './suite-BwnPDCvU.cjs';
+
+interface ArchitectureCheckOptions {
+    readonly baseline?: string;
+    readonly config?: string;
+    readonly cwd?: string;
+    readonly failOnWarnings?: boolean;
+    readonly output?: string;
+    readonly reporter?: ReporterName;
+    readonly updateBaseline?: boolean;
+}
+
+interface ArchTestOptions extends ArcherOptions {
+    readonly test?: TestOptions;
+}
+interface ArcherVitestOptions extends Omit<ArchitectureCheckOptions, 'cwd' | 'updateBaseline'> {
+}
+interface ArcherVitestPlugin {
+    readonly enforce: 'pre';
+    readonly name: 'archer:architecture-check';
+    readonly configResolved: (config: {
+        readonly root: string;
+    }) => Promise<void>;
+}
+/**
+ * Runs Archer once while Vitest resolves its Vite configuration.
+ */
+declare function archer(options?: ArcherVitestOptions): ArcherVitestPlugin;
+/**
+ * Registers an architecture test in Vitest and returns its rule builder.
+ */
+declare function arch(name: string, options?: ArchTestOptions): ArchitectureSuite;
+
+export { type ArchTestOptions, ArcherOptions, type ArcherVitestOptions, type ArcherVitestPlugin, arch, archer };

package/dist/vitest.d.ts

@@ -0,0 +1,37 @@
+import { TestOptions } from 'vitest';
+import { R as ReporterName } from './reporters-xh-HQneS.js';
+import { A as ArcherOptions, a as ArchitectureSuite } from './suite-BwnPDCvU.js';
+export { S as Selector } from './suite-BwnPDCvU.js';
+
+interface ArchitectureCheckOptions {
+    readonly baseline?: string;
+    readonly config?: string;
+    readonly cwd?: string;
+    readonly failOnWarnings?: boolean;
+    readonly output?: string;
+    readonly reporter?: ReporterName;
+    readonly updateBaseline?: boolean;
+}
+
+interface ArchTestOptions extends ArcherOptions {
+    readonly test?: TestOptions;
+}
+interface ArcherVitestOptions extends Omit<ArchitectureCheckOptions, 'cwd' | 'updateBaseline'> {
+}
+interface ArcherVitestPlugin {
+    readonly enforce: 'pre';
+    readonly name: 'archer:architecture-check';
+    readonly configResolved: (config: {
+        readonly root: string;
+    }) => Promise<void>;
+}
+/**
+ * Runs Archer once while Vitest resolves its Vite configuration.
+ */
+declare function archer(options?: ArcherVitestOptions): ArcherVitestPlugin;
+/**
+ * Registers an architecture test in Vitest and returns its rule builder.
+ */
+declare function arch(name: string, options?: ArchTestOptions): ArchitectureSuite;
+
+export { type ArchTestOptions, ArcherOptions, type ArcherVitestOptions, type ArcherVitestPlugin, arch, archer };

package/dist/vitest.js

@@ -0,0 +1,139 @@
+import {
+  applyBaseline,
+  createBaseline,
+  readBaseline,
+  report,
+  writeBaseline
+} from "./chunk-ZZ6TR4PO.js";
+import {
+  ArchitectureSuite,
+  analyze
+} from "./chunk-2AKMBLHG.js";
+import {
+  ArchitectureError
+} from "./chunk-IDVLHNL2.js";
+
+// src/adapters/vitest/index.ts
+import { test } from "vitest";
+
+// src/application/check.ts
+import { existsSync } from "fs";
+import { mkdir, writeFile } from "fs/promises";
+import path from "path";
+import { createJiti } from "jiti";
+var CONFIG_NAMES = [
+  "archer.config.ts",
+  "archer.config.mts",
+  "archer.config.cts",
+  "archer.config.js",
+  "archer.config.mjs",
+  "archer.config.cjs"
+];
+var REPORTERS = /* @__PURE__ */ new Set([
+  "agent",
+  "dot",
+  "github",
+  "json",
+  "llm",
+  "pretty",
+  "sarif"
+]);
+function findConfig(cwd, explicit) {
+  if (explicit !== void 0) {
+    const resolved = path.resolve(cwd, explicit);
+    if (!existsSync(resolved)) throw new Error(`Archer config not found: ${resolved}`);
+    return resolved;
+  }
+  for (const name of CONFIG_NAMES) {
+    const candidate = path.join(cwd, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(`No Archer config found in ${cwd}. Run 'archer init' to create one.`);
+}
+async function loadConfig(fileName) {
+  const jiti = createJiti(fileName, { moduleCache: false });
+  const config = await jiti.import(fileName, { default: true });
+  if (typeof config !== "object" || config === null || !("rules" in config) || typeof config.rules !== "function") {
+    throw new TypeError(`Archer config '${fileName}' must export defineConfig({ rules() {} }).`);
+  }
+  return config;
+}
+async function writeReport(fileName, content) {
+  await mkdir(path.dirname(fileName), { recursive: true });
+  await writeFile(fileName, `${content}
+`, "utf8");
+}
+async function checkArchitecture(options = {}) {
+  const cwd = path.resolve(options.cwd ?? process.cwd());
+  const configPath = findConfig(cwd, options.config);
+  const config = await loadConfig(configPath);
+  if (config.reporter !== void 0 && !REPORTERS.has(config.reporter)) {
+    throw new TypeError(`Unknown reporter '${config.reporter}' in ${configPath}.`);
+  }
+  const configDirectory = path.dirname(configPath);
+  const root = path.resolve(configDirectory, config.root ?? ".");
+  const suite = new ArchitectureSuite({ ...config, root });
+  await config.rules(suite);
+  const graph = await analyze({ ...config, root });
+  const originalResult = await suite.check(graph);
+  const configuredBaseline = options.baseline ?? config.baseline;
+  const baselinePath = path.resolve(configDirectory, configuredBaseline ?? ".archer-baseline.json");
+  const updateBaseline = options.updateBaseline ?? false;
+  if (updateBaseline) await writeBaseline(baselinePath, createBaseline(originalResult));
+  if (!updateBaseline && configuredBaseline !== void 0 && !existsSync(baselinePath)) {
+    throw new Error(`Archer baseline not found: ${baselinePath}`);
+  }
+  const result = !updateBaseline && existsSync(baselinePath) ? applyBaseline(originalResult, await readBaseline(baselinePath)) : originalResult;
+  const reporter = options.reporter ?? config.reporter ?? "pretty";
+  const content = report(reporter, result, graph);
+  const configuredOutput = options.output ?? config.output;
+  const outputPath = configuredOutput === void 0 ? void 0 : path.resolve(configDirectory, configuredOutput);
+  if (outputPath !== void 0) await writeReport(outputPath, content);
+  return {
+    baselinePath,
+    code: result.ok && (!(options.failOnWarnings ?? false) || result.warnings === 0) ? 0 : 1,
+    content,
+    graph,
+    ...outputPath === void 0 ? {} : { outputPath },
+    result,
+    updatedBaseline: updateBaseline
+  };
+}
+
+// src/adapters/vitest/index.ts
+var ArcherVitestError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ArcherVitestError";
+  }
+};
+function archer(options = {}) {
+  let execution;
+  return {
+    enforce: "pre",
+    name: "archer:architecture-check",
+    configResolved(config) {
+      execution ??= checkArchitecture({ ...options, cwd: config.root }).then((result) => {
+        if (result.code !== 0) throw new ArcherVitestError(result.content);
+        if (result.outputPath === void 0) process.stdout.write(`${result.content}
+`);
+      });
+      return execution;
+    }
+  };
+}
+function arch(name, options = {}) {
+  const { test: testOptions, ...archerOptions } = options;
+  const suite = new ArchitectureSuite(archerOptions);
+  test(name, testOptions ?? {}, async () => {
+    const result = await suite.check();
+    if (!result.ok) {
+      throw new ArchitectureError(result);
+    }
+  });
+  return suite;
+}
+export {
+  arch,
+  archer
+};

package/package.json

@@ -1,6 +1,218 @@
 {
   "name": "@lucasacoutinho/archer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "Architecture tests for TypeScript and JavaScript projects",
+  "keywords": [
+    "architecture",
+    "architecture-testing",
+    "archunit",
+    "boundaries",
+    "bun",
+    "dependency-rules",
+    "javascript",
+    "jest",
+    "monorepo",
+    "typescript",
+    "vitest"
+  ],
+  "homepage": "https://github.com/lucasacoutinho/archer#readme",
+  "bugs": {
+    "url": "https://github.com/lucasacoutinho/archer/issues"
+  },
+  "license": "Apache-2.0",
+  "author": "Lucas Coutinho",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucasacoutinho/archer.git"
+  },
+  "bin": {
+    "archer": "dist/cli.js"
+  },
+  "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"
+      }
+    },
+    "./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"
+      }
+    }
+  },
+  "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",
+    "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"
+  },
+  "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"
+  },
+  "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"
+  }
+}

package/skills/archer/SKILL.md

@@ -0,0 +1,81 @@
+---
+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.
+---
+
+# 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.
+
+## Inspect the project
+
+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.
+
+## Set up Archer
+
+Install `@lucasacoutinho/archer` as a development dependency with the repository's package manager. Prefer the CLI for a runner-independent check:
+
+```ts
+import { defineConfig } 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')
+  },
+})
+```
+
+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.
+
+Use `arch()` when the check should be registered as a test:
+
+```ts
+import { arch } from '@lucasacoutinho/archer/vitest'
+
+arch('domain boundaries').expect('src/domain/**').not.toDependOn('src/infrastructure/**')
+```
+
+Replace `vitest` with `jest`, `bun`, or `node` for another adapter.
+
+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.
+
+## Write rules
+
+- 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.
+
+Read [references/rules.md](references/rules.md) for selectors, dependency modifiers, named layers, semantic expectations, and presets.
+
+## Diagnose and fix findings
+
+Run:
+
+```sh
+npx --no-install archer check --reporter agent
+```
+
+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.
+
+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.
+
+Use `--update-baseline` only for deliberate staged adoption in an existing codebase. Commit the baseline when the project treats it as policy.
+
+## Report the result
+
+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.

package/skills/archer/agents/openai.yaml

@@ -0,0 +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.'

package/skills/archer/references/rules.md

@@ -0,0 +1,87 @@
+# Archer rule reference
+
+## Selectors
+
+Use project-relative globs for source files. Dependency selectors also accept:
+
+| Selector        | Matches                                              |
+| --------------- | ---------------------------------------------------- |
+| `src/domain/**` | Resolved local files                                 |
+| `npm:react`     | A package and its subpaths                           |
+| `node:fs`       | A Node built-in                                      |
+| `bun:test`      | A Bun built-in                                       |
+| `unresolved:*`  | Imports TypeScript cannot resolve                    |
+| `dynamic:*`     | Computed imports or requires without a static target |
+
+Archer resolves aliases, project references, workspace packages, re-exports, type imports, CommonJS requires, and literal dynamic imports.
+
+## Dependency rules
+
+```ts
+archer
+  .expect('src/application/**')
+  .toDependOn('src/domain/**')
+  .not.toDependOn('src/web/**')
+  .toOnlyDependOn(['src/application/**', 'src/domain/**'])
+  .toBeDependedOnBy('src/http/**')
+  .toOnlyBeDependedOnBy(['src/http/**', 'src/jobs/**'])
+```
+
+Aliases include `toUse`, `toOnlyUse`, `toUseNothing`, `toBeUsed`, `toBeUsedIn`, and `toOnlyBeUsedIn`.
+
+Apply a modifier to the next dependency rule:
+
+```ts
+archer
+  .expect('src/application/**')
+  .typeDependencies()
+  .toOnlyDependOn('src/contracts/**')
+  .runtimeDependencies()
+  .not.toDependOn('src/testing/**')
+  .dynamicDependencies()
+  .not.toDependOn('src/admin/**')
+  .localDependencies()
+  .toOnlyDependOn(['src/application/**', 'src/domain/**'])
+  .toTransitivelyDependOn('src/domain/events.ts')
+```
+
+Use `includingDependencyKinds(...)`, `transitively()`, and `toTransitivelyBeDependedOnBy(...)` for other combinations.
+
+## Layers and cycles
+
+```ts
+const layers = archer.layers({
+  domain: 'src/domain/**',
+  application: 'src/application/**',
+  infrastructure: 'src/infrastructure/**',
+})
+
+layers.where('domain').mayNotDependOn('infrastructure')
+layers.where('application').mayOnlyDependOn('domain')
+layers.where('domain').mayOnlyBeUsedBy('application')
+layers.where('domain').exposeThrough('src/domain/index.ts')
+layers.toBeFreeOfCycles()
+
+archer.expect('src/**').toBeFreeOfFolderCycles(2)
+```
+
+## TypeScript-aware expectations
+
+- Kinds: `toBeClasses`, `toBeInterfaces`, `toBeEnums`, `toBeFunctions`, `toBeTypes`
+- Declarations: `toBeAbstract`, `toBeExported`, `toExtend`, `toImplement`, `toHaveDecorator`
+- Members: `toHaveReadonlyProperties`, `toHaveMethods`, `toHavePublicMethods`, `toHaveProtectedMethods`, `toHavePrivateMethods`, `toOnlyHavePublicMethods`
+- Modules: `toOnlyExport`, `toHaveResolvableDependencies`, `toBePublicApi`
+- Source: `toUseStrictEquality`, `toUseGlobals`, `toHavePrefix`, `toHaveSuffix`, `toHaveLineCountLessThan`
+- Imported calls: `toUseImportedSymbols('react', 'useEffect')`; aliases and namespace calls resolve to the original module export
+
+Negate supported rules with `.not`. Remove selected files with `.ignoring(...)`. Attach `.as(id)`, `.because(reason)`, and `.withSeverity('warning' | 'info' | 'error')` after a rule.
+
+## Presets and custom checks
+
+Built-in presets are `strict`, `node`, and `security`:
+
+```ts
+archer.preset('strict')
+```
+
+Use `toSatisfy(id, evaluator)` for selector-scoped custom rules or `archer.rule(id, evaluator)` for a graph-wide rule. Return structured `ArchitectureViolation` objects. Prefer built-in rules when they express the same constraint.