@drkmttr/adhere 0.2.2 → 0.3.0

package/README.md

@@ -9,10 +9,104 @@ report uses the same frame as `vp lint`.
 
 Deterministic rules (substring matches, type checks) belong in a normal linter.
 
+## Install
+
+```sh
+npm install --global @drkmttr/adhere   # or: bun add --global @drkmttr/adhere
+```
+
+To pin the version in a repo, for CI or scripts, add it as a dev dependency
+and run `npx adhere`. To try it without installing, run
+`npx @drkmttr/adhere` or `bunx @drkmttr/adhere`.
+
+`adhere` is a prebuilt executable for macOS and Linux on arm64 and x64 and for
+Windows on x64. It needs Node to start, and no Bun.
+
+adhere sends each file it judges to Jev at `api.typesafe.ai`, authenticated
+with a TypeSafe AI API key in `TYPESAFE_API_KEY`.
+
+## Quick start
+
+```sh
+adhere init                          # .adhere/config.ts and two example rules
+adhere validate                      # check the config and rules, without Jev
+echo ".adhere/cache/" >> .gitignore
+export TYPESAFE_API_KEY=...
+adhere lint                          # audit the working directory
+```
+
+Without a config or rules, `adhere lint --preset effect` audits against the
+built-in Effect rules. A finding looks like this:
+
+```text
+  × data/brand-ports (0.93): A port is a branded, range-checked integer, not a bare number.
+   ╭─[src/server.ts:4:1]
+ 4 │ const port: number = Number(process.env.PORT ?? 3000);
+   · ──────────────────────────────────────────────────────
+   ╰────
+  hint: const Port = Schema.Int.pipe(
+          Schema.check(Schema.isBetween({ minimum: 1, maximum: 65535 })),
+          Schema.brand("Port"),
+        );
+
+Found 1 error.
+42 files, 3 judged, 39 cached.
+```
+
+The header is the rule id, Jev's probability, and the rule's description. The
+hint is the rule's reference. The exit code is 0 when nothing is reported and 1
+when something is. It is also 1 when the run refuses, for example on an invalid
+config or rule file, a missing `TYPESAFE_API_KEY`, or an unknown command or
+flag; a refusal prints its reason.
+
+## Usage
+
+```sh
+adhere lint                    # audit the working directory
+adhere lint --preset effect    # add a built-in rule set; the config becomes optional
+adhere lint --threshold 0.8    # replace the config's threshold; per-rule thresholds still apply
+adhere validate                # load the config and rules without Jev, check for contradictions
+adhere init [--force]          # scaffold .adhere/config.ts and two example rules
+adhere skill                   # print the agent skill (below)
+```
+
+Bare `adhere` prints the help, which lists the commands, and
+`adhere <command> --help` lists a command's flags. `adhere --completions <shell>`
+prints a completion script.
+
+### What gets read
+
+`adhere lint` reads the `.ts` files under the working directory, except `.d.ts`,
+`.test.ts`, and config files. When the working directory contains `agents/`,
+`apps/`, or `packages/`, only those trees are read. Paths under
+`node_modules/`, `dist/`, `coverage/`, `vendor/`, `e2e/`, `references/`,
+`.adhere/`, `.agents/`, `.claude/`, `.direnv/`, `.alchemy/`, or `.vite/` are
+skipped. `.tsx` files are not read, and `.gitignore` is not consulted.
+
+### Init
+
+`adhere init` writes `.adhere/config.ts` and two example rules. It is safe to
+rerun: by default it reports existing files as skipped and does not clobber
+them. `--force` overwrites them. A config already at another accepted path is
+kept, and no second one is added, even with `--force`.
+
+### Validate
+
+`adhere validate` loads the config, rule files, and presets the way `lint`
+does, without calling Jev, so a file that fails to decode refuses here too, and
+it prints how many rules it loaded. `--preset` adds a built-in rule set, as for
+`lint`. It then checks the rules for local textual contradictions: it exits 1
+and prints the conflicting rule files when overlapping rule scopes contain
+opposite textual directives for the same topic, such as "Use service classes
+for IO" and "Do not use service classes for IO". Same-id nested rules are
+treated as intentional shadowing rather than contradictions.
+
 ## Config
 
-A config file in the working directory of the repo being audited, at one of
-these paths (keep one):
+A config file is optional. Without one, adhere reads the rule files in
+`.adhere/` and any `--preset`. A config names presets, sets the model and
+thresholds, or gives rules inline. It sits in the working directory of the
+repo being audited, at one of these paths (keep one):
 
 - `.adhere/config.ts`, the default, next to the rules
 - `adhere.config.ts`
@@ -40,9 +134,15 @@ type UserId = typeof UserId.Type
 ```
 
 The default export is decoded with Effect `Schema`. An invalid shape refuses
-the run. The `import type` is erased at runtime, so the file also loads under
-the native executable, where `@drkmttr/adhere` is not installed. With the
-package installed, `defineConfig({...})` does the same thing.
+the run. The `import type` is erased at runtime. `defineConfig({...})` from
+`@drkmttr/adhere` does the same thing as `satisfies Config`, and the executable
+supplies it whether or not the repo has the package installed; the editor's
+types come from the package as a dev dependency. A config can import other
+files by relative path, but no packages besides `@drkmttr/adhere`: the
+executable does not resolve `node_modules`.
+
+`rules` in the config, inline as above or as a directory (below), replaces the
+`.adhere/` rule files: none of them, root or nested, is read then.
 
 ### Rules as Markdown files
 
@@ -51,32 +151,6 @@ config and the cache (neither is read as a rule). The path without `.md` is the
 rule id, so `.adhere/data/brand-ports.md` is `data/brand-ports`. When that
 directory exists, it is read without any config.
 
-`.adhere/` is the default rather than `docs/adhere/` because it keeps
-everything adhere owns in one directory: the config and the cache are tool
-state, not documentation, and would stay in `.adhere/` anyway. A nested
-`.adhere/` also scopes its rules to the directory that contains it (below). The
-cost is visibility: a dot directory is hidden from `ls`, and from `rg` without
-`--hidden`. A repo that would rather keep its rules with the rest of its
-documentation can point `rules` at `docs/adhere/`:
-
-```ts
-export default { presets: ["effect"], rules: "./docs/adhere" } satisfies Config;
-```
-
-Rules read through `rules` apply project-wide; nested `.adhere/` directories
-are not read then. A config is otherwise needed only to name presets or set
-thresholds.
-
-Nested `.adhere/` directories are also discovered. A rule in
-`packages/api/.adhere/data/brand-ports.md` has the same id,
-`data/brand-ports`, but applies only to files under `packages/api/`. Root
-`.adhere/` rules apply project-wide. If a nested rule has the same id as a root
-rule, the nearest containing `.adhere/` shadows the less-specific rule for that
-subtree; outside that subtree, the root rule still applies. There is no broader
-priority system: presets are global, project rules override preset rules with
-the same id, and nested project rules override less-specific project rules with
-the same id for files in their subtree.
-
 A file is front matter, then a body. The first fenced code block in the body
 is the reference; prose around it renders on GitHub and is ignored. Without a
 fence, the whole body is the reference.
@@ -101,6 +175,30 @@ const Port = Schema.Int.pipe(
 validation refuses the run with its path in the message. `loadRules(directory)`
 from the package root does the same load for your own tooling.
 
+Nested `.adhere/` directories are also discovered. A rule in
+`packages/api/.adhere/data/brand-ports.md` has the same id,
+`data/brand-ports`, but applies only to files under `packages/api/`. Root
+`.adhere/` rules apply project-wide. If a nested rule has the same id as a root
+rule, the nearest containing `.adhere/` shadows the less-specific rule for that
+subtree; outside that subtree, the root rule still applies. There is no broader
+priority system: presets are global, project rules override preset rules with
+the same id, and nested project rules override less-specific project rules with
+the same id for files in their subtree.
+
+`.adhere/` is the default rather than `docs/adhere/` because it keeps
+everything adhere owns in one directory: the config and the cache are tool
+state, not documentation, and would stay in `.adhere/` anyway. A nested
+`.adhere/` also scopes its rules to the directory that contains it (above). The
+cost is visibility: a dot directory is hidden from `ls`, and from `rg` without
+`--hidden`. A repo that would rather keep its rules with the rest of its
+documentation can point `rules` at `docs/adhere/`:
+
+```ts
+export default { presets: ["effect"], rules: "./docs/adhere" } satisfies Config;
+```
+
+Rules read through `rules` apply project-wide.
+
 ### Presets
 
 A preset has the shape of a config without `presets`: `rules`, and optionally
@@ -118,56 +216,52 @@ order (a later preset wins), then the defaults `jev-latest` and `0.7`. A rule
 in `rules` replaces a preset rule with the same id. A rule's own `threshold`
 beats all of the above for that rule.
 
-## Install
-
-```sh
-npm install --global @drkmttr/adhere   # or: bun add --global @drkmttr/adhere
-```
-
-`adhere` is the native executable (below), compiled for macOS and Linux on
-arm64 and x64 and for Windows on x64. Each platform's is its own package,
-`@drkmttr/adhere-<platform>-<arch>`, and an optional dependency of
-`@drkmttr/adhere` that the install fetches only on that platform. The package's
-`bin/adhere.js` runs it with Node, so neither Bun nor adhere's runtime
-dependencies are needed.
-
-## Run
+## How a file is judged
 
-From a checkout, with Bun:
+1. One Jev request per file, with the file's numbered lines and every rule as
+   the state, and one `noul` (yes/no probability) question per rule. Every
+   question shares the state cost of the request.
+2. A second request only when at least one rule's probability is above its
+   threshold: one `choice` question per flagged rule over the file's non-blank
+   lines, which yields the line to report. A file with more than 255 non-blank
+   lines is located in two steps (a block of 20 lines, then a line inside it).
+   Files longer than 5100 lines are skipped and counted in the summary.
 
-```sh
-bun install
-bun link          # puts `adhere` on PATH
-adhere --preset effect
-```
+## Cache
 
-In a checkout no platform package is installed, so `bin/adhere.js` runs
-`src/main.ts` with Bun instead.
+Judgments are cached in `.adhere/cache/` (add it to `.gitignore`), one entry
+per file. An entry stores the file's content hash and, per rule, the
+probability, the located line, and a fingerprint of the rule's text and model.
+A changed file re-judges every rule for that file. An edited rule re-judges
+only that rule. A lowered threshold locates cached judgments that are newly
+above it without judging again. Entries depend on content, not on the
+machine, so restoring `.adhere/cache/` between CI runs skips unchanged files.
 
-`adhere` audits the working directory. When that directory contains `agents/`,
-`apps/`, or `packages/`, only those trees are read. Exit code 1 when there is
-at least one finding.
+`TYPESAFE_API_KEY` is read only when a request is about to be sent. A run
+where every file is cached needs no key and no network.
 
-Initialize a new project with a config and example rules:
+## Agent skill
 
-```sh
-adhere init
-adhere init --force  # overwrite the scaffold files if they already exist
-```
+[`skills/adhere/SKILL.md`](./skills/adhere/SKILL.md) teaches an agent to
+gather a repo's conventions into rule files, configure adhere, and calibrate
+thresholds. Install it with the [skills](https://github.com/vercel-labs/skills)
+CLI: `skills add darkmatter/adhere`. The binary carries the same file:
+`adhere skill` prints it, so `adhere skill > .agents/skills/adhere/SKILL.md`
+works without a checkout.
 
-The command is safe to rerun: by default it reports existing files as skipped
-and does not clobber them.
+## Development
 
-Check only this project's configured rules for local textual contradictions:
+From a checkout, with Bun:
 
 ```sh
-adhere contradictions
+bun install
+bun link          # puts `adhere` on PATH
+adhere lint --preset effect
 ```
 
-It exits 1 and prints the conflicting rule files when overlapping rule scopes
-contain opposite textual directives for the same topic, such as "Use service
-classes for IO" and "Do not use service classes for IO". Same-id nested rules
-are treated as intentional shadowing rather than contradictions.
+In a checkout no platform package is installed, so `bin/adhere.js` runs
+`src/main.ts` with Bun instead. `bun run typecheck` runs `tsc` and the linter,
+and `bun run test` runs the tests.
 
 ### Native executable
 
@@ -180,7 +274,12 @@ machine and still loads the repo's `config.ts` and Markdown rules from disk.
 into its package under `dist/npm/`
 ([`scripts/npm-packages.ts`](./scripts/npm-packages.ts)).
 
-## Release
+Each platform's executable is its own npm package,
+`@drkmttr/adhere-<platform>-<arch>`, limited by `os` and `cpu`, and an
+optional dependency of `@drkmttr/adhere`, so an install fetches only its own
+machine's. The package's `bin/adhere.js` finds it and runs it with Node.
+
+### Release
 
 Releases are cut by CI from pushed version tags. From a clean, up-to-date
 `main`, push the release tag:
@@ -202,40 +301,10 @@ The publish workflow verifies that `package.json` matches the release tag,
 builds the platform packages, and publishes each of them before
 `@drkmttr/adhere`, which it first lists them in as `optionalDependencies` at
 the same version. Every publish is `npm publish --access public --provenance`.
-No npm token is used, so a new platform package has to be published once by
-hand and given the trusted publisher on npmjs.com before the job can publish
-it. The publish workflow can also be run manually for an already-created
-release tag if a publish needs to be retried; it skips platform packages whose
-version is already on npm.
-
-## How a file is judged
-
-1. One Jev request per file, with the file's numbered lines and every rule as
-   the state, and one `noul` (yes/no probability) question per rule. Every
-   question shares the state cost of the request.
-2. A second request only when at least one rule's probability is above its
-   threshold: one `choice` question per flagged rule over the file's non-blank
-   lines, which yields the line to report. A file with more than 255 non-blank
-   lines is located in two steps (a block of 20 lines, then a line inside it).
-   Files longer than 5100 lines are skipped and counted in the summary.
-
-## Cache
-
-Judgments are cached in `.adhere/cache/` (add it to `.gitignore`), one entry
-per file. An entry stores the file's content hash and, per rule, the
-probability, the located line, and a fingerprint of the rule's text and model.
-A changed file re-judges every rule for that file. An edited rule re-judges
-only that rule. A lowered threshold locates cached judgments that are newly
-above it without judging again.
-
-`TYPESAFE_API_KEY` is read only when a request is about to be sent. A run
-where every file is cached needs no key and no network.
-
-## Agent skill
-
-[`skills/adhere/SKILL.md`](./skills/adhere/SKILL.md) teaches an agent to
-gather a repo's conventions into rule files, configure adhere, and calibrate
-thresholds. Install it with the [skills](https://github.com/vercel-labs/skills)
-CLI: `skills add darkmatter/adhere`. The binary carries the same file:
-`adhere skill` prints it, so `adhere skill > .agents/skills/adhere/SKILL.md`
-works without a checkout.
+No npm token is used, so a new package has to be published once by hand
+before it can be given trusted publishers on npmjs.com. npm checks the
+workflow that started the run, so every package has two: `release.yaml`, which
+calls the publish workflow for tag releases, and `publish.yaml`, for manual
+runs. The publish workflow can be run manually for an already-created release
+tag if a publish needs to be retried; it skips platform packages whose version
+is already on npm.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "private": false,
   "description": "Lints a repository against reference code in .adhere/, judged by Jev.",
   "repository": {
@@ -61,10 +61,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.2.2",
-    "@drkmttr/adhere-darwin-x64": "0.2.2",
-    "@drkmttr/adhere-linux-arm64": "0.2.2",
-    "@drkmttr/adhere-linux-x64": "0.2.2",
-    "@drkmttr/adhere-win32-x64": "0.2.2"
+    "@drkmttr/adhere-darwin-arm64": "0.3.0",
+    "@drkmttr/adhere-darwin-x64": "0.3.0",
+    "@drkmttr/adhere-linux-arm64": "0.3.0",
+    "@drkmttr/adhere-linux-x64": "0.3.0",
+    "@drkmttr/adhere-win32-x64": "0.3.0"
   }
 }

package/skills/adhere/SKILL.md

@@ -38,7 +38,7 @@ Keep rules about intent, shape, and placement:
 - "Business logic depends on a config service, not on `Config.*` reads."
 - "Domain errors are `Schema.TaggedError` classes, not thrown `Error`."
 
-Skip rules a preset already covers. Run `adhere --help` and read
+Skip rules a preset already covers. Run `adhere lint --help` and read
 `presets/effect/` in the adhere repo before writing Effect rules; extend with
 `presets: ["effect"]` and add only what is specific to this repo.
 
@@ -95,8 +95,9 @@ uncached files; in this org it comes from SOPS via `just shell`.
 ## 5. Run and calibrate
 
 ```sh
-adhere                     # or: adhere --preset effect
-adhere --threshold 0.9     # re-reads the cache, sends nothing
+adhere validate              # decodes the config and rules, checks contradictions
+adhere lint                  # or: adhere lint --preset effect
+adhere lint --threshold 0.9  # re-reads the cache, sends nothing
 ```
 
 Then, per rule, read the findings and decide:

package/src/cli.ts

@@ -6,7 +6,7 @@ import { render, runAudit } from "#workflows/audit.ts";
 import type { Overrides } from "#config.ts";
 import { findContradictions, formatContradictions } from "#contradictions.ts";
 import { initProject } from "#init.ts";
-import { presetNames } from "#presets.ts";
+import { type PresetName, presetNames } from "#presets.ts";
 import { globalRuleSet } from "#rules.ts";
 import {
   Console,
@@ -39,13 +39,6 @@ class ContradictionsReported extends Schema.TaggedError<ContradictionsReported>(
   readonly [Runtime.errorReported] = false;
 }
 
-class UsageReported extends Schema.TaggedError<UsageReported>()(
-  "UsageReported",
-  { message: Schema.String },
-) {
-  readonly [Runtime.errorReported] = false;
-}
-
 const preset = Flag.choice("preset", presetNames).pipe(
   Flag.optional,
   Flag.withDescription("Add a built-in rule set. With a preset, .adhere/config.ts is optional."),
@@ -58,6 +51,14 @@ const threshold = Flag.float("threshold").pipe(
   ),
 );
 
+const force = Flag.boolean("force").pipe(
+  Flag.withDefault(false),
+  Flag.withDescription("Overwrite existing scaffold files."),
+);
+
+const chosenPresets = (flag: Option.Option<PresetName>): ReadonlyArray<PresetName> =>
+  Option.isSome(flag) ? [flag.value] : [];
+
 export const auditLayer = (overrides: Overrides) =>
   Layer.mergeAll(
     SourceWalkerLive,
@@ -65,14 +66,8 @@ export const auditLayer = (overrides: Overrides) =>
     JevLive.pipe(Layer.provide(FetchHttpClient.layer)),
   ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)));
 
-/** `adhere skill`: the agent skill for writing rules, as shipped in the binary. */
-export const skillCommand = Command.make("skill", {}, () => Console.log(skill.trimEnd())).pipe(
-  Command.withDescription(
-    "Print the agent skill that gathers a repo's conventions into rules and configures adhere. Pipe it into .agents/skills/adhere/SKILL.md or hand it to an agent.",
-  ),
-);
-
-const audit = Command.make("adhere", { preset, threshold }, () =>
+/** `adhere lint`: the audit. */
+export const lintCommand = Command.make("lint", { preset, threshold }, () =>
   Effect.gen(function* () {
     const result = yield* runAudit;
     const stdio = yield* Stdio.Stdio;
@@ -90,85 +85,66 @@ const audit = Command.make("adhere", { preset, threshold }, () =>
   ),
   Command.provide((input) =>
     auditLayer({
-      presets: Option.isSome(input.preset) ? [input.preset.value] : [],
+      presets: chosenPresets(input.preset),
       threshold: Option.getOrUndefined(input.threshold),
     }),
   ),
 );
 
-const INIT_HELP = `Usage: adhere init [--force]
-
-Scaffold .adhere/config.ts and example Markdown rules.
-
-Options:
-  --force   Overwrite existing scaffold files
-  --help    Show this help
-
-Examples:
-  adhere init
-  adhere init --force`;
-
-const CONTRADICTIONS_HELP = `Usage: adhere contradictions
-
-Check this project's configured adhere rules for local textual contradictions.
-
-Examples:
-  adhere contradictions`;
-
-export const runInitCommand = (args: ReadonlyArray<string>) =>
+/**
+ * `adhere validate`: everything `lint` loads, without Jev. A config, rule file,
+ * or preset that does not decode refuses here the way it would refuse `lint`.
+ */
+export const validateCommand = Command.make("validate", { preset }, () =>
   Effect.gen(function* () {
-    if (args.includes("--help") || args.includes("-h")) {
-      yield* Console.log(INIT_HELP);
-      return;
-    }
-    const unknown = args.filter((arg) => arg !== "--force");
-    if (unknown.length > 0) {
-      yield* Console.error(`Unknown option for adhere init: ${unknown.join(", ")}`);
-      yield* Console.error(INIT_HELP);
-      return yield* UsageReported.make({ message: "invalid init arguments" });
+    const config = yield* AdhereConfig;
+    const path = yield* Path.Path;
+    const entries = config.scopedRules ?? globalRuleSet(config.rules, path.resolve());
+    const contradictions = findContradictions(entries);
+    const loaded = `${entries.length} ${entries.length === 1 ? "rule" : "rules"} loaded.`;
+    yield* Console.log([loaded, formatContradictions(contradictions)].join("\n"));
+    if (contradictions.length > 0) {
+      return yield* ContradictionsReported.make({ count: contradictions.length });
     }
+  }),
+).pipe(
+  Command.withDescription(
+    "Load the config, rule files, and presets the way lint does, without calling Jev, and check the rules for contradictions.",
+  ),
+  Command.provide((input) => AdhereConfigLive({ presets: chosenPresets(input.preset) })),
+);
+
+/** `adhere init`: the scaffold. */
+export const initCommand = Command.make("init", { force }, (input) =>
+  Effect.gen(function* () {
     const path = yield* Path.Path;
-    const result = yield* initProject(path.resolve(), {
-      force: args.includes("--force"),
-    });
+    const result = yield* initProject(path.resolve(), { force: input.force });
     const lines = [
-      result.created.length > 0
-        ? `created: ${result.created.join(", ")}`
-        : "created: none",
-      result.skipped.length > 0
-        ? `skipped: ${result.skipped.join(", ")}`
-        : "skipped: none",
+      result.created.length > 0 ? `created: ${result.created.join(", ")}` : "created: none",
+      result.skipped.length > 0 ? `skipped: ${result.skipped.join(", ")}` : "skipped: none",
     ];
     yield* Console.log(lines.join("\n"));
-  });
+  }),
+).pipe(Command.withDescription("Scaffold .adhere/config.ts and example Markdown rules."));
 
-export const runContradictionsCommand = (args: ReadonlyArray<string>) =>
-  Effect.gen(function* () {
-    if (args.includes("--help") || args.includes("-h")) {
-      yield* Console.log(CONTRADICTIONS_HELP);
-      return;
-    }
-    if (args.length > 0) {
-      yield* Console.error(
-        `Unknown option for adhere contradictions: ${args.join(", ")}`,
-      );
-      yield* Console.error(CONTRADICTIONS_HELP);
-      return yield* UsageReported.make({
-        message: "invalid contradictions arguments",
-      });
-    }
-    const config = yield* AdhereConfig;
-    const path = yield* Path.Path;
-    const root = path.resolve();
-    const entries = config.scopedRules ?? globalRuleSet(config.rules, root);
-    const contradictions = findContradictions(entries);
-    yield* Console.log(formatContradictions(contradictions));
-    if (contradictions.length > 0) {
-      return yield* ContradictionsReported.make({
-        count: contradictions.length,
-      });
-    }
-  });
+/** `adhere skill`: the agent skill for writing rules, as shipped in the binary. */
+export const skillCommand = Command.make("skill", {}, () => Console.log(skill.trimEnd())).pipe(
+  Command.withDescription(
+    "Print the agent skill that gathers a repo's conventions into rules and configures adhere. Pipe it into .agents/skills/adhere/SKILL.md or hand it to an agent.",
+  ),
+);
 
-/** The whole CLI: `adhere` audits, `adhere skill` prints the skill. */
-export const auditCommand = audit.pipe(Command.withSubcommands([skillCommand]));
+/** The whole CLI. Bare `adhere` prints its help. */
+export const cli = Command.make("adhere").pipe(
+  Command.withDescription("Lint a repository against reference code in .adhere/, judged by Jev."),
+  Command.withExamples([
+    { command: "adhere init", description: "Scaffold .adhere/config.ts and two example rules" },
+    { command: "adhere validate", description: "Check the config and rules without calling Jev" },
+    { command: "adhere lint", description: "Audit the working directory" },
+    {
+      command: "adhere lint --preset effect",
+      description: "Audit against the built-in Effect rules",
+    },
+  ]),
+  Command.withSubcommands([lintCommand, validateCommand, initCommand, skillCommand]),
+);

package/src/main.ts

@@ -1,21 +1,23 @@
 #!/usr/bin/env bun
-import { auditCommand, runContradictionsCommand, runInitCommand } from "#cli.ts";
-import { AdhereConfigLive } from "#services/AdhereConfig.ts";
+import { cli } from "#cli.ts";
+import * as adhere from "#index.ts";
 import { version } from "#version.ts";
 import { BunRuntime, BunServices } from "@effect/platform-bun";
+import { plugin } from "bun";
 import { Effect } from "effect";
 import { Command } from "effect/unstable/cli";
 
-const [subcommand, ...args] = Bun.argv.slice(2);
+// A config file may import `@drkmttr/adhere`, for `defineConfig`. The compiled
+// executable resolves no packages from disk, so it answers that import with
+// its own copy, whether or not the audited repo has the package installed.
+plugin({
+  name: "@drkmttr/adhere",
+  setup: (build) => {
+    build.module("@drkmttr/adhere", () => ({ exports: { ...adhere }, loader: "object" }));
+  },
+});
 
-const program =
-  subcommand === "init"
-    ? runInitCommand(args)
-    : subcommand === "contradictions"
-      ? runContradictionsCommand(args).pipe(Effect.provide(AdhereConfigLive({})))
-      : Command.run(auditCommand, { version });
-
-program.pipe(
+Command.run(cli, { version }).pipe(
   // oxlint-disable-next-line effecttsgo/strict-effect-provide -- this executable entrypoint supplies Bun's process services.
   Effect.provide(BunServices.layer),
   BunRuntime.runMain,

package/test/cli.test.ts

@@ -1,9 +1,13 @@
 import { execFile } from "node:child_process";
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { promisify } from "node:util";
 import packageJson from "../package.json";
 import { describe, expect, it } from "vite-plus/test";
 
 const execFileAsync = promisify(execFile);
+const main = join(process.cwd(), "src", "main.ts");
 
 describe("cli", () => {
   it("reports the package version", async () => {
@@ -14,4 +18,28 @@ describe("cli", () => {
     expect(stderr).toBe("");
     expect(stdout.trim()).toBe(`adhere v${packageJson.version}`);
   });
+
+  it("prints help listing every command when run bare", async () => {
+    const { stdout } = await execFileAsync("bun", [main], { cwd: process.cwd() });
+    const subcommands = stdout.slice(stdout.indexOf("SUBCOMMANDS"), stdout.indexOf("EXAMPLES"));
+
+    for (const name of ["lint", "validate", "init", "skill"]) {
+      expect(subcommands).toMatch(new RegExp(`^  ${name} `, "m"));
+    }
+  });
+
+  it("validates a repo's rules without calling Jev", async () => {
+    const root = join(tmpdir(), `adhere-validate-${Date.now()}`);
+    await mkdir(join(root, ".adhere"), { recursive: true });
+    await writeFile(
+      join(root, ".adhere", "ports.md"),
+      '---\ndescription: A port is a branded integer.\n---\n\nconst Port = Schema.Int.pipe(Schema.brand("Port"))\n',
+      "utf8",
+    );
+
+    const { stdout } = await execFileAsync("bun", [main, "validate"], { cwd: root });
+
+    expect(stdout).toContain("1 rule loaded.");
+    expect(stdout).toContain("No contradictions found among configured rules.");
+  });
 });