@drkmttr/adhere 0.12.0 → 0.13.0

package/skills/adhere-setup/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: adhere-setup
+description: Set adhere up in a repository with the user. Scan the repo for conventions a normal linter cannot check and draft them as rules, add fitting presets and rules from a shared org repo, let the user preview and choose which to import, validate them, walk through the first lint, and add adhere to CI. Use when a repo has no adhere rules yet, or the user asks to set up, adopt, or onboard adhere.
+---
+
+# Set up adhere in a repo
+
+You and the user go from no rules to adhere passing in CI. The user decides
+what gets imported, what it may cost, and what reaches GitHub; you do the
+reading, drafting, and running. The adhere skill, which `adhere skill`
+prints, is the reference for the rule format, the config, and tuning: read it
+before step 3.
+
+At each point marked **Ask**, stop and wait for the answer. Use a structured
+question tool if you have one; otherwise ask in plain text with numbered
+choices.
+
+## 1. Check the tools
+
+Use the package manager the repo already uses, for every command in this
+skill; never bring in another. Tell it by the lockfile beside `package.json`,
+as `adhere init` does: `bun.lock` or `bun.lockb` for bun, `pnpm-lock.yaml` for
+pnpm, `yarn.lock` for yarn, `package-lock.json` for npm. Without a lockfile,
+the `packageManager` field in `package.json` names it; with neither, **Ask**.
+
+| Manager | Add adhere                       | Run adhere         |
+| ------- | -------------------------------- | ------------------ |
+| bun     | `bun add -D @drkmttr/adhere`     | `bunx adhere`      |
+| pnpm    | `pnpm add -D @drkmttr/adhere`    | `pnpm exec adhere` |
+| yarn    | `yarn add -D @drkmttr/adhere`    | `yarn adhere`      |
+| npm     | `npm install -D @drkmttr/adhere` | `npx adhere`       |
+
+In a repo with a `package.json`, add adhere as a dev dependency with its
+manager, so the repo pins the version the team and CI run. From then on,
+wherever this skill says `adhere`, run it the manager's way, as in
+`pnpm exec adhere lint`.
+
+With pnpm, at a workspace root, add `--ignore-workspace-root-check`.
+
+In a repo without a `package.json`, use the `adhere` on PATH (`adhere
+--version`), or **Ask** before installing it globally with the manager the
+user has, such as `bun add --global @drkmttr/adhere`.
+
+Validate and lint need a TypeSafe AI API key: `TYPESAFE_API_KEY`, or one saved
+by `adhere login`, which the user runs; never ask for the key in chat or print
+it.
+
+## 2. Find candidates
+
+Gather candidates from three sources. Keep a note, for each, of where it came
+from and the evidence.
+
+**The repo.** Read, noting every "we always" and "never":
+
+- `AGENTS.md`, `CLAUDE.md`, `CONTRIBUTING.md`, convention sections of the
+  README, `docs/`, ADRs.
+- Lint and type configuration, to learn what is already enforced exactly.
+- Review feedback, when `gh` works: `gh pr list --state merged --limit 20`,
+  then `gh pr view <n> --comments` on a few. Repeated review comments are
+  unwritten rules.
+- The code: the module others copy, the canonical service, error type, and
+  test.
+
+Keep only conventions that need judgment: about intent, shape, or placement.
+Drop any a regex, an import check, or the type checker could flag every time,
+and note where it belongs instead. Drop any a preset below already covers.
+
+**Presets.** Match the stack: `typescript` for TypeScript, `react` for React,
+`security` for code that handles secrets, SQL, shell commands, or paths,
+`effect` for Effect, `alchemy` for alchemy stacks. Read their rules under
+`presets/` in the installed package or at
+https://github.com/darkmatter/adhere/tree/main/presets, to describe them and
+to avoid drafting duplicates.
+
+**A shared repo.** **Ask** whether the organization keeps adhere rules in a
+repo. If it does, `adhere list org/repo` prints its rules with their
+descriptions.
+
+## 3. Draft the repo's rules
+
+Write each repo candidate as a rule file, worded as the adhere skill says: one
+sentence with "must" and "never" (or "should" and "should not"), one `must`
+block of real code from the repo, and one `never` block, ideally a violation
+from the repo or its history.
+
+Write the drafts outside the repo, in a scratch directory such as
+`$(mktemp -d)/<topic>/<slug>/RULE.md`, so nothing lands in `.adhere/` before the
+user picks it.
+
+## 4. Preview and choose
+
+Show one numbered list of every candidate, grouped by source:
+
+```text
+From this repo
+  1. errors/tagged-errors      Domain errors must be Schema.TaggedError classes, never thrown Error.
+                               Evidence: AGENTS.md "Errors"; src/billing/errors.ts
+  2. services/config-service   Business logic must read config through ConfigService, never Config.* directly.
+                               Evidence: review comments on #412, #398
+Presets
+  3. typescript                11 rules: runtime checks at boundaries, no swallowed errors, ...
+  4. security                  4 rules: no secrets in output, parameterized SQL, ...
+From acme/standards
+  5. data/brand-ports          A port must be a branded, range-checked integer, never a bare number.
+Dropped as a linter's job
+  - "no default exports": eslint import/no-default-export
+```
+
+For a preset, offer the whole preset or its topics. Show a draft's full text
+when the user asks for it.
+
+**Ask** which to import: all, some by number, or none, and whether to change
+the wording of any. Revise drafts the user wants changed and show them again.
+
+## 5. Import the chosen rules
+
+- Without a config, run `adhere init`. It also writes two example rules under
+  `.adhere/rules/style/`; delete them unless the user chose them.
+- Copy each chosen draft to `.adhere/rules/<topic>/<slug>/RULE.md`.
+- Add chosen presets, or topics, to `presets` in `.adhere/config.ts`.
+- Install chosen shared rules: `adhere install org/repo/<id>` for each, or
+  `adhere install org/repo` for all of them. They land in `.adhere/rules/org/repo/`.
+- Add `exclude` globs for generated or vendored code the default skips miss.
+
+## 6. Validate
+
+```sh
+adhere validate
+```
+
+It reports rules worded against the tips, rules a linter could check, and
+contradictions between rules that apply to the same files. Fix the wording
+yourself. For a linter-checkable rule or a contradiction, **Ask** the user
+which to keep, and apply it. Run it again until it reports no contradictions.
+
+## 7. The first lint
+
+```sh
+adhere lint --limit 0
+```
+
+This shows the plan and judges nothing: files, rules, requests, and the
+estimated cost. Tell the user those numbers. On a large repo, offer to start
+with a subtree, such as `--filter 'src/**'`, or a `--limit`. **Ask** before
+sending, then run it:
+
+```sh
+adhere lint --yes
+```
+
+Walk the user through the report:
+
+1. How to read a finding: the rule id, the description, its confidence and
+   context scores, the underlined line, and the warning when the file may not
+   show enough.
+2. Findings grouped by rule, the highest probabilities first. Check a few from
+   each rule against the code, and say which look real and which do not.
+3. For each noisy rule, propose one change from the adhere skill's "Tuning a
+   rule": narrow the wording, scope it, raise its threshold, make it a
+   warning, or turn it off. **Ask**, apply what the user accepts, and run
+   lint again. Only the edited rules are judged again.
+
+CI fails on any error finding, so lint must exit 0 before step 8. **Ask** how
+to get there: fix the real findings now with the adhere-fix skill
+(`adhere skill fix`), make a rule a warning until its findings are fixed,
+or suppress false findings with `adhere-ignore` comments that give the reason.
+
+Commit `.adhere/` with the cache, so the team and CI reuse these judgments.
+Offer to add `.adhere/cache/** linguist-generated -diff` to `.gitattributes`.
+
+## 8. Add adhere to CI
+
+**Ask** before writing a workflow and before touching the repo's secrets.
+
+If the repo's CI already installs its dependencies, add adhere as a job or a
+step there, with the same setup, so it runs the pinned adhere the way the
+rest of CI runs its tools. Otherwise, for GitHub Actions, add
+`.github/workflows/adhere.yaml`:
+
+```yaml
+name: adhere
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      # Set up the repo's package manager and install, from the table below.
+      - run: pnpm exec adhere lint --yes # the manager's way of running adhere
+        env:
+          TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}
+```
+
+| Manager | Setup steps                                                                         | Install                                                      |
+| ------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| bun     | `uses: oven-sh/setup-bun@v2`                                                        | `bun install --frozen-lockfile`                              |
+| pnpm    | `uses: pnpm/action-setup@v4`, then `uses: actions/setup-node@v4` with `cache: pnpm` | `pnpm install --frozen-lockfile`                             |
+| yarn    | `uses: actions/setup-node@v4` with `cache: yarn`, then `run: corepack enable`       | `yarn install --immutable`, or `--frozen-lockfile` on Yarn 1 |
+| npm     | `uses: actions/setup-node@v4` with `cache: npm`                                     | `npm ci`                                                     |
+
+Pin the versions the repo already uses: bun's `bun-version`, Node's
+`node-version` from `.nvmrc` or `engines`, and pnpm's from `packageManager`,
+which `pnpm/action-setup` reads. In a repo without a `package.json`, set up
+the manager the user has and run adhere at the version they ran locally, as
+in `bunx @drkmttr/adhere@0.11.0 lint --yes`.
+
+Add `--deny-warnings` if the user wants warnings to fail the job too. Match
+the branch to the repo's default branch. For another CI system, write the
+same job: check out, install, run adhere's `lint --yes` with the key from a
+secret.
+
+The user adds the key as a secret: `gh secret set TYPESAFE_API_KEY`, which
+prompts for it, or in the repo's settings. Pull requests from forks get no
+secrets, so lint fails there on any file not in the cache.
+
+Where lint gates merges, anyone who can commit can also commit a cache file
+saying their code passes. To lint a pull request against the cache as merged,
+fetch the base branch and restore its cache before linting:
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- if: github.event_name == 'pull_request'
+  run: rm -rf .adhere/cache && git checkout origin/${{ github.base_ref }} -- .adhere/cache
+```
+
+This needs the cache committed on the base branch first.
+
+## 9. Report
+
+Tell the user:
+
+- the rules imported, by source, and where they are;
+- the presets and shared repo named in the config or installed;
+- the candidates dropped as a linter's job, with where each belongs;
+- the last lint's findings, and what was fixed, made a warning, or suppressed;
+- the CI workflow and whether the secret is set;
+- what is left for them: pushing, setting the secret, fixing remaining findings.

package/src/cli.ts

@@ -43,14 +43,15 @@ import {
   Stdio,
   Stream,
 } from "effect";
-import { Argument, Command, Flag, Prompt } from "effect/unstable/cli";
-import { FetchHttpClient } from "effect/unstable/http";
+import { Argument, Command, Flag, Prompt } from "effect/cli";
+import { FetchHttpClient } from "effect/http";
 // A Bun text import (https://bun.sh/docs/bundler/loaders#text): the file's
 // contents become a string at bundle time, so the compiled binary carries the
 // skill without an --asset flag. `skills/` sits beside `src/`, outside the `#`
 // import map, hence the relative path.
 import skill from "../skills/adhere/SKILL.md" with { type: "text" };
 import fixSkill from "../skills/adhere-fix/SKILL.md" with { type: "text" };
+import setupSkill from "../skills/adhere-setup/SKILL.md" with { type: "text" };
 
 class FindingsReported extends Schema.TaggedError<FindingsReported>()("FindingsReported", {
   count: Schema.Finite,
@@ -75,7 +76,7 @@ const presetsIn = (values: ReadonlyArray<string>): ReadonlyArray<string> =>
 const isPresetName = (name: string): name is PresetName =>
   (presetNames as ReadonlyArray<string>).includes(name);
 
-const preset = Flag.string("preset").pipe(
+const preset = Flag.String("preset").pipe(
   Flag.atLeast(0),
   Flag.filterMap(
     (values): Option.Option<ReadonlyArray<PresetName>> => {
@@ -93,21 +94,21 @@ const preset = Flag.string("preset").pipe(
   ),
 );
 
-const threshold = Flag.float("threshold").pipe(
+const threshold = Flag.Finite("threshold").pipe(
   Flag.optional,
   Flag.withDescription(
     "Report a rule when Jev's probability is above this value, 0 to 1. Replaces the config's threshold; per-rule thresholds still apply.",
   ),
 );
 
-const sufficiencyThreshold = Flag.float("sufficiency-threshold").pipe(
+const sufficiencyThreshold = Flag.Finite("sufficiency-threshold").pipe(
   Flag.optional,
   Flag.withDescription(
     "Warn on a finding when Jev's probability that the file shows enough to decide it is below this value, 0 to 1. Replaces the config's sufficiencyThreshold; the default is 0.6.",
   ),
 );
 
-const limit = Flag.integer("limit").pipe(
+const limit = Flag.Int("limit").pipe(
   Flag.filter(
     (checks) => checks >= 0,
     (checks) => `--limit is a number of checks, 0 or more, not ${checks}.`,
@@ -118,7 +119,7 @@ const limit = Flag.integer("limit").pipe(
   ),
 );
 
-const rpm = Flag.integer("rpm").pipe(
+const rpm = Flag.Int("rpm").pipe(
   Flag.filter(
     (requests) => requests > 0,
     (requests) => `--rpm is a number of requests a minute, more than 0, not ${requests}.`,
@@ -127,19 +128,19 @@ const rpm = Flag.integer("rpm").pipe(
   Flag.withDescription("Send at most this many requests to Jev a minute, evenly spaced."),
 );
 
-const filter = Flag.string("filter").pipe(
+const filter = Flag.String("filter").pipe(
   Flag.atLeast(0),
   Flag.withDescription(
     "Read only files whose path from the working directory matches this glob, such as 'src/**' or '**/*.service.ts'. Repeat it for more; a pattern starting with ! leaves out what it matches.",
   ),
 );
 
-const denyWarnings = Flag.boolean("deny-warnings").pipe(
+const denyWarnings = Flag.Boolean("deny-warnings").pipe(
   Flag.withDefault(false),
   Flag.withDescription("Fail the run on warnings as well as errors."),
 );
 
-const yes = Flag.boolean("yes").pipe(
+const yes = Flag.Boolean("yes").pipe(
   Flag.withAlias("y"),
   Flag.withDefault(false),
   Flag.withDescription(
@@ -212,7 +213,7 @@ const statusLayer = Layer.effect(Status)(
   }),
 );
 
-const force = Flag.boolean("force").pipe(
+const force = Flag.Boolean("force").pipe(
   Flag.withDefault(false),
   Flag.withDescription("Overwrite existing scaffold files."),
 );
@@ -239,7 +240,7 @@ export const lintCommand = Command.make(
       const interactive = (yield* stdio.stdinIsTerminal) && (yield* stdio.stdoutIsTerminal);
       if (plan.requests > 0 && interactive && !input.yes) {
         const send = yield* Prompt.run(
-          Prompt.confirm({ message: sendQuestion(plan), initial: true }),
+          Prompt.Confirm({ message: sendQuestion(plan), initial: true }),
         );
         if (!send) {
           yield* toStderr("Nothing sent.\n");
@@ -256,7 +257,14 @@ export const lintCommand = Command.make(
       const color = yield* stdio.stdoutIsTerminal;
       const path = yield* Path.Path;
       // One write: separate Console.log calls have interleaved out of order here.
-      yield* Console.log(render(result, { color, root: path.resolve() }).join("\n"));
+      yield* Console.log(
+        render(result, {
+          color,
+          root: path.resolve(),
+          threshold: plan.threshold,
+          sufficiencyThreshold: plan.sufficiencyThreshold,
+        }).join("\n"),
+      );
       // Only errors fail the run, unless --deny-warnings: a warning is for a nit or a noisy rule.
       const failed = failing(result.findings, input.denyWarnings);
       if (failed.length > 0) {
@@ -265,7 +273,7 @@ export const lintCommand = Command.make(
     }),
 ).pipe(
   Command.withDescription(
-    "Audit the working directory against the rules in .adhere/ or a preset, judged by Jev.",
+    "Audit the working directory against the rules in .adhere/rules/ or a preset, judged by Jev.",
   ),
   Command.provide((input) =>
     auditLayer(
@@ -335,14 +343,14 @@ const installLine = (install: Install): string => {
   }
 };
 
-const shared = Flag.string("shared").pipe(
+const shared = Flag.String("shared").pipe(
   Flag.filter(
     (repo) => /^[\w.-]+\/[\w.-]+$/.test(repo),
     (repo) => `--shared names a GitHub repo as org/repo, not ${repo}.`,
   ),
   Flag.optional,
   Flag.withDescription(
-    "Scaffold a repo of rules other repos copy with adhere install, named org/repo on GitHub: example rules, a README, a CI workflow that runs adhere validate, and an alchemy.run.ts that creates the repo and its TYPESAFE_API_KEY secret.",
+    "Scaffold a repo of rules other repos copy with adhere install, named org/repo on GitHub: example rules, a README, a CI workflow that runs adhere validate, and an alchemy.run.ts that creates the repo, public unless you make it private when asked, and its TYPESAFE_API_KEY secret.",
   ),
 );
 
@@ -350,8 +358,16 @@ const shared = Flag.string("shared").pipe(
 export const initCommand = Command.make("init", { force, shared }, (input) =>
   Effect.gen(function* () {
     const path = yield* Path.Path;
+    const stdio = yield* Stdio.Stdio;
+    // A shared repo is public unless the user, asked at a terminal, makes it private.
+    const interactive = (yield* stdio.stdinIsTerminal) && (yield* stdio.stdoutIsTerminal);
+    const makePrivate =
+      Option.isSome(input.shared) && interactive
+        ? yield* Prompt.run(Prompt.Confirm({ message: "Make the repo private?", initial: false }))
+        : false;
     const result = yield* initProject(path.resolve(), {
       force: input.force,
+      visibility: makePrivate ? "private" : "public",
       ...Option.match(input.shared, { onNone: () => ({}), onSome: (repo) => ({ shared: repo }) }),
     });
     const lines = [
@@ -367,17 +383,17 @@ export const initCommand = Command.make("init", { force, shared }, (input) =>
   ),
 );
 
-const source = Argument.string("source").pipe(
+const source = Argument.String("source").pipe(
   Argument.filterMap(
     (spec) => Option.fromNullishOr(parseSource(spec)),
     (spec) => `org/repo, then optionally a topic or rule and #ref, not ${spec}`,
   ),
   Argument.withDescription(
-    "A GitHub repo with rules in .adhere/, as org/repo, optionally followed by a topic or a rule, as in org/repo/data/brand-ports, and by #branch or #tag.",
+    "A GitHub repo with rules in .adhere/rules/, as org/repo, optionally followed by a topic or a rule, as in org/repo/data/brand-ports, and by #branch or #tag.",
   ),
 );
 
-/** `adhere list org/repo`: the rules another repo's `.adhere/` holds. */
+/** `adhere list org/repo`: the rules another repo's `.adhere/rules/` holds. */
 export const listCommand = Command.make("list", { source }, (input) =>
   Effect.gen(function* () {
     const rules = yield* listRules(input.source);
@@ -388,18 +404,18 @@ export const listCommand = Command.make("list", { source }, (input) =>
   }),
 ).pipe(
   Command.withDescription(
-    "List the rules in a GitHub repo's .adhere/, each with its description, for adhere install. Clones with git, so a private repo needs git's credentials for it.",
+    "List the rules in a GitHub repo's .adhere/rules/, each with its description, for adhere install. Clones with git, so a private repo needs git's credentials for it.",
   ),
 );
 
-/** `adhere install org/repo`: another repo's rules, copied into this one's `.adhere/`. */
+/** `adhere install org/repo`: another repo's rules, copied into this one's `.adhere/rules/`. */
 export const installCommand = Command.make(
   "install",
   {
     source,
-    force: Flag.boolean("force").pipe(
+    force: Flag.Boolean("force").pipe(
       Flag.withDefault(false),
-      Flag.withDescription("Overwrite rule files already in .adhere/."),
+      Flag.withDescription("Replace rules already in .adhere/rules/, directory and all."),
     ),
   },
   (input) =>
@@ -415,7 +431,7 @@ export const installCommand = Command.make(
     }),
 ).pipe(
   Command.withDescription(
-    "Copy the rules in a GitHub repo's .adhere/, or one topic or rule of them, into this repo's .adhere/<org>/<repo>/. They are this repo's own rules from then on, to edit or keep in step by hand. Existing files are skipped unless --force.",
+    "Copy the rules in a GitHub repo's .adhere/rules/, or one topic or rule of them, each its whole directory, into this repo's .adhere/rules/<org>/<repo>/. They are this repo's own rules from then on, to edit or keep in step by hand, and a copied RULE.ts runs whenever lint does. A rule already there is skipped unless --force.",
   ),
 );
 
@@ -426,7 +442,7 @@ export const installCommand = Command.make(
 const readApiKey = Effect.fn("login.readApiKey")(function* () {
   const stdio = yield* Stdio.Stdio;
   const typed: string = (yield* stdio.stdinIsTerminal)
-    ? Redacted.value(yield* Prompt.run(Prompt.password({ message: "TypeSafe AI API key" })))
+    ? Redacted.value(yield* Prompt.run(Prompt.Password({ message: "TypeSafe AI API key" })))
     : yield* stdio.stdin.pipe(
         Stream.decodeText(),
         Stream.mkString,
@@ -477,27 +493,27 @@ export const logoutCommand = Command.make("logout", {}, () =>
 );
 
 /** The agent skills the binary carries, by the name `adhere skill` takes. */
-const skills = { rules: skill, fix: fixSkill } as const;
+const skills = { docs: skill, setup: setupSkill, fix: fixSkill } as const;
 
-const skillName = Argument.choice("skill", ["rules", "fix"] as const).pipe(
-  Argument.withDefault("rules" as const),
+const skillName = Argument.Literals("skill", ["docs", "setup", "fix"] as const).pipe(
+  Argument.withDefault("docs" as const),
   Argument.withDescription(
-    "rules, the default, to gather a repo's conventions into rules and configure adhere; fix, to verify and fix the findings lint reports.",
+    "docs, the default, the reference for rules, the config, and reports; setup, to set adhere up in a repo with the user, through its first lint and CI; fix, to verify and fix the findings lint reports.",
   ),
 );
 
-/** `adhere skill [rules|fix]`: an agent skill, as shipped in the binary. */
+/** `adhere skill [docs|setup|fix]`: an agent skill, as shipped in the binary. */
 export const skillCommand = Command.make("skill", { name: skillName }, ({ name }) =>
   Console.log(skills[name].trimEnd()),
 ).pipe(
   Command.withDescription(
-    "Print an agent skill: by default the one that gathers a repo's conventions into rules and configures adhere, or with fix, the one that verifies and fixes lint's findings. Pipe it into .agents/skills/<name>/SKILL.md or hand it to an agent.",
+    "Print an agent skill: by default adhere's reference, for writing rules, configuring adhere, and reading reports; with setup, the one that sets adhere up in a repo with the user, from choosing rules through the first lint to CI; with fix, the one that verifies and fixes lint's findings. Pipe it into .agents/skills/<name>/SKILL.md or hand it to an agent.",
   ),
 );
 
 /** The whole CLI. Bare `adhere` prints its help. */
 export const cli = Command.make("adhere").pipe(
-  Command.withDescription("Lint a repository against the rules in .adhere/, judged by Jev."),
+  Command.withDescription("Lint a repository against the rules in .adhere/rules/, judged by Jev."),
   Command.withExamples([
     { command: "adhere init", description: "Scaffold .adhere/config.ts and two example rules" },
     {
@@ -508,7 +524,7 @@ export const cli = Command.make("adhere").pipe(
     { command: "adhere lint", description: "Audit the working directory" },
     {
       command: "adhere install org/repo",
-      description: "Copy another repo's .adhere/ rules into this one",
+      description: "Copy another repo's .adhere/rules/ into this one",
     },
     {
       command: "adhere lint --preset effect",

package/src/config.ts

@@ -4,6 +4,34 @@ import { Effect, Schema, SchemaTransformation } from "effect";
 
 export type RuleId = string;
 
+/** The state a request to Jev carries: the file's code as numbered sections, which every question reads. */
+export interface JevState {
+  readonly code: Readonly<Record<string, string>>;
+}
+
+/** The file a request is about, as a rule's hook gets it: its absolute path, and its text as written. */
+export interface JudgedFile {
+  readonly path: string;
+  readonly contents: string;
+}
+
+/**
+ * Bun's API, typed when the project has Bun's types. Read off `globalThis`,
+ * so this package's source type-checks in a project without them.
+ */
+type BunApi = typeof globalThis extends { Bun: infer B } ? B : unknown;
+
+/**
+ * A rule's hook on what Jev reads for it, run right before each request for
+ * the rule goes out: what it returns is spread over the request's state.
+ * Nothing it returns is checked, so it can replace `code` itself.
+ */
+export type AppendState = (
+  state: JevState,
+  file: JudgedFile,
+  bun: BunApi,
+) => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
+
 /**
  * A rule's examples, named in RFC 2119's words, which Jev reads as written. A
  * requirement shows code that `must` be written and code that must `never`
@@ -39,6 +67,16 @@ const RuleFields = Schema.Struct({
    * that breaks the rule is as it describes, and a yes to any drops the finding.
    */
   excludeIf: Schema.optionalKey(Schema.Array(Schema.String)),
+  /**
+   * A hook on the state Jev reads for the rule, in a rule written in
+   * TypeScript (see `AppendState`). The rule's questions go in requests of
+   * their own, so only they read what it adds.
+   */
+  appendState: Schema.optionalKey(
+    Schema.declare((value: unknown): value is AppendState => typeof value === "function", {
+      expected: "a function",
+    }),
+  ),
 });
 
 /** Before 0.7, a rule's examples were `reference` and `avoid`: read as `must` and `never`. */
@@ -137,8 +175,9 @@ export const AdhereConfig = Schema.Struct({
     Schema.withDecodingDefaultKey(Effect.succeed([])),
   ),
   /**
-   * A record of rules, or a directory path relative to the config file.
-   * Unset: `.adhere/` when that directory exists, otherwise no rules.
+   * A record of rules, or a directory path relative to the config file,
+   * which holds its rules as `.adhere/rules/` does. Unset: the rules in
+   * `.adhere/rules/`, and in any nested `.adhere/rules/`.
    */
   rules: Schema.optionalKey(Schema.Union([Schema.Record(Schema.String, Rule), Schema.String])),
   /**
@@ -161,8 +200,10 @@ export const AdhereConfig = Schema.Struct({
   includeComments: Schema.optionalKey(Schema.Boolean),
 });
 
-/** Where a repo keeps its rule files by default. The cache lives under it. */
+/** Where a repo keeps what adhere reads and writes: its config, its rules, and the cache. */
 export const ADHERE_DIRECTORY = ".adhere";
+/** Where a repo keeps its rules by default, one to a directory: `<id>/RULE.md` or `<id>/RULE.ts`. */
+export const RULES_DIRECTORY = `${ADHERE_DIRECTORY}/rules`;
 export const CACHE_DIRECTORY = `${ADHERE_DIRECTORY}/cache`;
 /** Where a config may live, relative to the working directory. Exactly one may exist. */
 export const CONFIG_FILES = [
@@ -210,6 +251,12 @@ export type Config = typeof AdhereConfig.Encoded;
 
 export const defineConfig = (config: Config) => config;
 
+/**
+ * Types a rule written in TypeScript, which a `.adhere/` file default-exports,
+ * and returns it as it is. It takes what a config's inline rule does.
+ */
+export const defineRule = (rule: typeof Rule.Encoded) => rule;
+
 /** A built-in rule set. Same shape as a config, minus `presets`. */
 export interface Preset {
   /**

package/src/index.ts

@@ -1,8 +1,10 @@
 export {
   type AdhereConfig,
+  type AppendState,
   type Config,
   ConfigUnavailable,
   defineConfig,
+  defineRule,
   type Preset,
   type Rule,
   type RuleId,