@drkmttr/adhere 0.14.0 → 0.17.5

package/skills/adhere-setup/SKILL.md

@@ -37,10 +37,23 @@ wherever this skill says `adhere`, run it the manager's way, as in
 
 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 the executable from the latest
-release (`adhere-Windows-x86_64.exe` on Windows), which needs no Node or
-package manager:
+Default lint enables `workspacePackages`, `symbols`, and `references`, and
+starts native TypeScript only during execution, after confirmation, when
+pending judgments or cached findings needing location require context. It discovers each
+file's configured project, including package projects under solution roots,
+and falls back to inferred context for unconfigured or excluded files. No root
+`tsconfig.json` or literal root file-list membership is required; do not block
+setup on either. `.adhere/tsconfig.json` only types the config and rules.
+Planning, `--limit 0`, version, help, skills, and validate do not start the
+compiler.
+
+In a repo without a `package.json`, inspect any `adhere` on PATH with
+`adhere --version`, then **Ask** whether to use the npm/Bun package launcher
+for the full default or a raw executable with deliberately reduced context.
+The raw release (`adhere-Windows-x86_64.exe` on Windows) needs no Node or
+package manager, but its lint requires explicit config `reads: []` or
+`reads: ["workspacePackages"]`. Do not silently disable readers to make it
+work. Only fetch it after the user chooses that alternative:
 
 ```sh
 curl -fsSL --create-dirs -o ~/.local/bin/adhere \
@@ -48,9 +61,9 @@ curl -fsSL --create-dirs -o ~/.local/bin/adhere \
 chmod +x ~/.local/bin/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.
+Validate and lint's paid requests 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. Compiler-free planning with `--limit 0` needs no key.
 
 ## 2. Find candidates
 
@@ -124,7 +137,12 @@ the wording of any. Revise drafts the user wants changed and show them again.
 - 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`.
+- Add chosen presets, or topics, to `presets` in `.adhere/config.ts`. Presets
+  use the audit-wide readers; they do not own or override `reads`.
+- Leave `reads` omitted for the full default. Do not add `reads: []` to the
+  normal setup recommendation or as a workaround for missing compiler
+  resources. Only set an explicit replacement array if the user chooses to
+  disable or limit readers.
 - 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.
@@ -146,15 +164,115 @@ which to keep, and apply it. Run it again until it reports no contradictions.
 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:
+This shows a compiler-free plan and judges nothing: overall files/rules/cache
+check metrics, and files deferred for a later run. Planning reads/counts/hashes
+own code and checks cached answers; `--limit 0` skips budgeting, native reads,
+and HTTP execution. A positive limit counts files needing requests, not rule
+checks. Only selected files' pending rules and cached-location work are budgeted;
+deferred/waiting counts are files, which can later be found too large. Planning never calls
+`SourceReads` or resolves native symbols/references. Explain the output/prompt
+caveat: estimates omit native context and hook-added data, so actual tokens,
+cost, and request splits may be higher. Source reload/hash work is bounded to
+8 files; plans retain compact metadata, not all source text. Files are reloaded
+for execution; if normalized code or ignore
+directives changed since planning, rerun rather than using the old plan.
+
+Tell the user that compiler type/docs strings and outgoing declaration snippets add
+source/documentation sharing and token cost by default, including complete
+scopes from files outside the audit filter. Whole declaration bodies can use more
+tokens than fixed-line excerpts; budget overflow skips the file instead of
+capping bodies to seven lines or silently truncating them. Compiler-provided
+documentation and JSDoc tags can remain even when ordinary code comments are
+stripped; omitting `symbols` disables type/docs context and omitting
+`references` disables snippets. The global workspace catalog is not sent: only
+this file's matched literal imports appear under canonical package keys.
+Offer an explicit reader subset or code-only opt-out if they want less context;
+never apply one silently. Neither reader selection nor dependency/shared-context
+changes invalidate cached judgments. If they want fresh answers under changed
+context, **Ask** before clearing `.adhere/cache/`; do not clear it automatically.
+
+On a large repo, offer a subtree such as `--filter 'src/**'`, or a file cap
+such as `--limit 100`: the first 100 files needing requests in path order, with
+all pending rules per selected file. Judging plus cached-unlocated work in one
+file uses one slot; a cached-locate-only file also counts. Fully cached and
+already-located files report without using slots. After the cap, both judge and
+locate work wait. Known cheap-budget skips refill from later files, but native
+or HTTP-size skips after selection consume a slot without runtime refill.
+
+Explain that a file cap is not an HTTP-request or token/cost cap: each file can
+produce judge, locate, split-batch, and private hook requests. **Ask** before
+sending, then run the command below with only the user's chosen filter/file cap:
 
 ```sh
 adhere lint --yes
 ```
 
+`SourceReads.prepare(paths)` registers eligible-path metadata only, with no
+file I/O, compiler/SDK import, spawn, snapshot, or semantic query, even for a large list.
+Only after confirmation do pending judgments or cached findings still needing
+location trigger actual per-file native reads just before judge/locate. Native
+transactions are serial through one permit; HTTP execution remains concurrent
+at 8. Returned context is reused locally and full budgets are enforced before
+HTTP, with oversized files skipped and no silent truncation. Shared state plus
+one question must fit 32k tokens and state plus all questions must fit 64k per
+request, with 1k reserved for overhead. The SDK may still parse a full selected
+project, and additional monorepo programs may increase startup time and memory.
+
+`symbols` remains `Record<string, string>`: compiler-rendered distinct type
+blocks for same-name binding/narrowing contexts, with compiler documentation
+and JSDoc tags once per canonical symbol per file. It does not promise literal
+IDE labels or selected-call overload presentation. Symbol/type queries are
+batched, and independent SDK requests are chunked to at most 8 within the single
+active native document/snapshot; HTTP work remains concurrent at 8. `references` maps used names to canonical outgoing declarations
+by pathname, selecting the smallest complete AST scope without extra surrounding
+lines. Functions include full bodies; arrow/object initializer variables include
+whole variable statements with `export const` and semicolons. Methods, getters,
+and setters include their whole member, not the entire class; classes,
+interfaces, and type aliases include the whole declaration. Repeated/overlapping
+scopes merge and disjoint scopes join with `…`. This is syntactic scope selection,
+not recursive helper-call expansion: helpers called by an imported function are
+not automatically expanded. Scopes preserve indentation and the comment/directive
+policy, including associated JSDoc when `includeComments` is true; compiler
+docs/tags in `symbols` remain available regardless. Current-file, declaration-file, `node_modules`, and
+outside-root exclusions are unchanged. There are no incoming callers, counts, structured locations,
+unresolved lists, full-file collection, or completeness markers.
+
+The first actual read lazily starts one native TypeScript LSP process with its
+public SDK API pipe; both are pinned to exactly `7.1.0-dev.20261009.1` and must
+match. This prerelease contains the tuple-reference serialization fix from
+[microsoft/TypeScript#64080](https://github.com/microsoft/TypeScript/issues/64080). `NativeLsp` owns lifecycle only and makes
+no `textDocument/hover` calls. Each read uses the passed as-written text after
+normalized-code/ignore active-plan validation, opens only that document at
+version 1, uses `textDocument/documentSymbol` as its readiness barrier, and calls
+the public, parameterless `API.getCurrentLanguageServerSnapshot()`.
+Success closes the document, disposes that snapshot under a guarded phase, and
+clears AST caches; native failure closes the session under the watchdog.
+
+Keep dependencies/configs stable: only current-read text is pinned, not every
+registered file or an immutable global audit snapshot. Warm compiler project
+graphs can still be large and slow to load; neither total memory nor payload
+size is constant, and contexts may still exceed model budgets.
+
+SDK/write phases and LSP requests have 30-second deadlines and reject on compiler
+exit. Queued readers can be interrupted; the active owner is uninterruptible
+for resource safety. A stalled phase is bounded and cleanup adds a 2-second
+`SIGKILL` watchdog. These are phase/cleanup bounds, not a whole-audit timeout.
+
+If the user explicitly chose a cache refresh, run from the audited working
+directory, using the repo's package launcher as above:
+
+```sh
+rm -rf .adhere/cache
+adhere lint --limit 0
+```
+
+Show the fresh counts/cache plan; `--limit 0` skips budgeting. For selected
+execution work, explain that its estimate omits native context and may understate
+cost/splits, then **Ask** before paid execution. Deleting the cache removes judgments and linter tallies; it can cause
+new paid requests. Use this explicitly if the user wants to compare fresh
+compiler type/docs and declaration payloads with older cached answers. A change in `B.ts` does not
+otherwise invalidate cached judgments for an unchanged importing `A.ts`.
+
 Walk the user through the report:
 
 1. How to read a finding: the rule id, the description, its confidence and
@@ -165,7 +283,8 @@ Walk the user through the report:
 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.
+   lint again. With unchanged own code and model, only the edited rules are
+   judged again; dependency/context changes alone are not tracked.
 
 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
@@ -212,9 +331,16 @@ jobs:
 
 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`, skip the
-setup and install, and fetch the executable at the version the user ran
-locally:
+which `pnpm/action-setup` reads. Keep optional dependencies enabled so adhere's
+platform package and its compiler dependency are installed. Existing project
+configs and dependencies supply configured context when available; files with
+no configured project or excluded from one use inferred context. Do not require
+or generate a root `tsconfig.json` merely to make default lint run. In a repo
+without a `package.json`, use the package launcher for the full default.
+Only skip setup/install and fetch the raw executable if the user explicitly
+chose and committed `reads: []` or `reads: ["workspacePackages"]` locally.
+That is a reduced-context alternative, not an equivalent default installation.
+Fetch the executable at the version the user ran:
 
 ```yaml
 - run: |

package/src/cli.ts

@@ -1,7 +1,13 @@
 import { AdhereConfig, AdhereConfigLive } from "#services/AdhereConfig.ts";
 import { AuditCacheLive } from "#services/AuditCache.ts";
-import { Credentials, CredentialsLive, CredentialsUnavailable } from "#services/Credentials.ts";
+import {
+  Credentials,
+  CredentialsLive,
+  CredentialsUnavailable,
+  KEYS,
+} from "#services/Credentials.ts";
 import { JevLive } from "#services/Jev.http.ts";
+import { SourceReadsLive } from "#services/SourceReads.ts";
 import { SourceWalkerLive } from "#services/SourceWalker.ts";
 import { Status } from "#services/Status.ts";
 import {
@@ -26,6 +32,7 @@ import { type Install, initProject } from "#init.ts";
 import { installRules, listRules, parseSource } from "#install.ts";
 import { formatLinterCheck, tallyProjectRules } from "#mechanical.ts";
 import { type PresetName, presetNames } from "#presets.ts";
+import type { SavedKey } from "#providers/provider.ts";
 import { globalRuleSet } from "#rules.ts";
 import { formatStrays, straysAmong } from "#wording.ts";
 import {
@@ -44,7 +51,6 @@ import {
   Stream,
 } from "effect";
 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 `#`
@@ -110,12 +116,12 @@ const sufficiencyThreshold = Flag.Finite("sufficiency-threshold").pipe(
 
 const limit = Flag.Int("limit").pipe(
   Flag.filter(
-    (checks) => checks >= 0,
-    (checks) => `--limit is a number of checks, 0 or more, not ${checks}.`,
+    (files) => files >= 0,
+    (files) => `--limit is a number of files, 0 or more, not ${files}.`,
   ),
   Flag.optional,
   Flag.withDescription(
-    "Judge at most this many checks. The rest wait for a later run, which picks up where this one stopped, since judgments are cached. --limit 0 shows the plan and judges nothing.",
+    "Process at most this many files needing requests, in path order, including every pending rule per selected file. Fully cached and located files do not count. A file can send multiple requests. --limit 0 shows the plan without resolving native reads or sending requests.",
   ),
 );
 
@@ -221,8 +227,9 @@ const force = Flag.Boolean("force").pipe(
 export const auditLayer = (flags: Flags, filter: ReadonlyArray<string> = []) =>
   Layer.mergeAll(
     SourceWalkerLive(filter),
+    SourceReadsLive(),
     AuditCacheLive,
-    JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
+    JevLive.pipe(Layer.provide(CredentialsLive)),
   ).pipe(Layer.provideMerge(AdhereConfigLive(flags)), Layer.provideMerge(statusLayer));
 
 /** `adhere lint`: the audit. */
@@ -235,10 +242,19 @@ export const lintCommand = Command.make(
       const plan = yield* planAudit({ limit: Option.getOrUndefined(input.limit) });
       const limits = { filter: input.filter, rpm: Option.getOrUndefined(input.rpm) };
       yield* toStderr(`${describePlan(plan, limits).join("\n")}\n`);
+      if (plan.planOnly === true) {
+        // Planning still knows the live content keys, so a complete walk can prune without sending.
+        if (input.filter.length === 0) yield* pruneCache(plan);
+        return;
+      }
       // A prompt draws on stdout, so it needs a terminal at both ends: none when
       // the report is redirected, or in CI.
       const interactive = (yield* stdio.stdinIsTerminal) && (yield* stdio.stdoutIsTerminal);
-      if (plan.requests > 0 && interactive && !input.yes) {
+      if (
+        (plan.requests > 0 || (plan.cachedLocateRequests ?? 0) > 0) &&
+        interactive &&
+        !input.yes
+      ) {
         const send = yield* Prompt.run(
           Prompt.Confirm({ message: sendQuestion(plan), initial: true }),
         );
@@ -263,6 +279,7 @@ export const lintCommand = Command.make(
           root: path.resolve(),
           threshold: plan.threshold,
           sufficiencyThreshold: plan.sufficiencyThreshold,
+          ...(plan.provider === undefined ? {} : { provider: plan.provider }),
         }).join("\n"),
       );
       // Only errors fail the run, unless --deny-warnings: a warning is for a nit or a noisy rule.
@@ -290,10 +307,10 @@ export const lintCommand = Command.make(
 
 /** Jev, with the key `lint` uses, and the config it reads the model and threshold from. */
 export const validateLayer = (flags: Flags) =>
-  Layer.merge(
-    JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
-    AuditCacheLive,
-  ).pipe(Layer.provideMerge(AdhereConfigLive(flags)), Layer.provideMerge(statusLayer));
+  Layer.merge(JevLive.pipe(Layer.provide(CredentialsLive)), AuditCacheLive).pipe(
+    Layer.provideMerge(AdhereConfigLive(flags)),
+    Layer.provideMerge(statusLayer),
+  );
 
 /**
  * `adhere validate`: everything `lint` loads, then how each rule's wording
@@ -439,10 +456,10 @@ export const installCommand = Command.make(
  * The key typed at a masked prompt, or piped in: `adhere login < key.txt`.
  * Whitespace around it, like the newline a pipe ends with, is dropped.
  */
-const readApiKey = Effect.fn("login.readApiKey")(function* () {
+const readApiKey = Effect.fn("login.readApiKey")(function* (label: string) {
   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: label })))
     : yield* stdio.stdin.pipe(
         Stream.decodeText(),
         Stream.mkString,
@@ -461,33 +478,49 @@ const readApiKey = Effect.fn("login.readApiKey")(function* () {
   return Redacted.make(key);
 });
 
-/** `adhere login`: save the API key, so a run needs no TYPESAFE_API_KEY. */
-export const loginCommand = Command.make("login", {}, () =>
+/** `--openai`: the OpenAI key, for the `openai` provider, in place of TypeSafe AI's. */
+const openaiKey = Flag.Boolean("openai").pipe(
+  Flag.withDefault(false),
+  Flag.withDescription(
+    "The OpenAI API key, for a config whose provider is openai(), in place of the TypeSafe AI key Jev asks with.",
+  ),
+);
+
+/** Which saved key a command means, and how it names it: TypeSafe AI's by default. */
+const keyOf = (openai: boolean) => {
+  const name: SavedKey = openai ? "openai" : "typesafe";
+  return { name, ...KEYS[name] };
+};
+
+/** `adhere login`: save an API key, so a run needs no TYPESAFE_API_KEY, or with `--openai`, no OPENAI_API_KEY. */
+export const loginCommand = Command.make("login", { openai: openaiKey }, ({ openai }) =>
   Effect.gen(function* () {
+    const { name, label, said } = keyOf(openai);
     const credentials = yield* Credentials;
-    yield* credentials.save(yield* readApiKey());
-    yield* Console.log(`Saved the API key to ${yield* credentials.file}.`);
+    yield* credentials.save(name, yield* readApiKey(label));
+    yield* Console.log(`Saved the ${said} to ${yield* credentials.file}.`);
   }),
 ).pipe(
   Command.withDescription(
-    "Save a TypeSafe AI API key in ~/.config/adhere ($XDG_CONFIG_HOME/adhere when set), readable only by you, so lint runs without TYPESAFE_API_KEY. Prompts for the key, or reads it from stdin when piped.",
+    "Save a TypeSafe AI API key in ~/.config/adhere ($XDG_CONFIG_HOME/adhere when set), readable only by you, so lint runs without TYPESAFE_API_KEY. With --openai, save an OpenAI API key beside it instead, for the openai provider. Prompts for the key, or reads it from stdin when piped.",
   ),
   Command.provide(CredentialsLive),
 );
 
-/** `adhere logout`: delete the saved API key. */
-export const logoutCommand = Command.make("logout", {}, () =>
+/** `adhere logout`: delete a saved API key. */
+export const logoutCommand = Command.make("logout", { openai: openaiKey }, ({ openai }) =>
   Effect.gen(function* () {
+    const { name, said } = keyOf(openai);
     const credentials = yield* Credentials;
     const file = yield* credentials.file;
-    const removed = yield* credentials.remove;
+    const removed = yield* credentials.remove(name);
     yield* Console.log(
-      removed ? `Deleted the API key saved in ${file}.` : `No API key is saved in ${file}.`,
+      removed ? `Deleted the ${said} saved in ${file}.` : `No ${said} is saved in ${file}.`,
     );
   }),
 ).pipe(
   Command.withDescription(
-    "Delete the API key adhere login saved. TYPESAFE_API_KEY, when set, still applies.",
+    "Delete the API key adhere login saved, or with --openai, the OpenAI one. TYPESAFE_API_KEY or OPENAI_API_KEY, when set, still applies.",
   ),
   Command.provide(CredentialsLive),
 );

package/src/config.ts

@@ -1,12 +1,17 @@
 import { type PresetName, presetNames } from "#presets.ts";
+import { type Provider, SAVED_KEYS } from "#providers/provider.ts";
 import type { RuleSet } from "#rules.ts";
-import { Effect, Schema, SchemaTransformation } from "effect";
+import { Effect, Predicate, 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. */
+/** Shared context prepared for a file's requests; it does not affect cache validity. */
+export type ReadState = Readonly<Record<string, unknown>>;
+
+/** The file's numbered sections and the context enabled by its config. */
 export interface JevState {
   readonly code: Readonly<Record<string, string>>;
+  readonly [key: string]: unknown;
 }
 
 /** The file a request is about, as a rule's hook gets it: its absolute path, and its text as written. */
@@ -15,6 +20,21 @@ export interface JudgedFile {
   readonly contents: string;
 }
 
+/**
+ * A config's provider, as `Provider` in `providers/provider.ts` describes it:
+ * a model, and how to ask it. Checked rather than copied, so a class keeps
+ * what its `ask` reads off `this`.
+ */
+const ProviderSchema = Schema.declare(
+  (value: unknown): value is Provider =>
+    Predicate.hasProperty(value, "model") &&
+    Predicate.isString(value.model) &&
+    Predicate.hasProperty(value, "ask") &&
+    Predicate.isFunction(value.ask) &&
+    (!Predicate.hasProperty(value, "savedKey") || SAVED_KEYS.some((key) => key === value.savedKey)),
+  { expected: "a provider: a model, and a function to ask it" },
+);
+
 /**
  * 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.
@@ -33,13 +53,15 @@ export type AppendState = (
 ) => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
 
 /**
- * What a rule can have Jev read beside the code, each by the name of the key
- * the state carries it under, which the rule's description can name in
- * backticks. `workspacePackages` is the workspace's packages: each one's name
- * with its directory, so a rule can tell an import of the repository's own
- * package from an installed one's.
+ * What the config can have Jev read beside each file's code, shared by all
+ * its rules. Each name is the key the state carries it under, which a rule's
+ * description can name in backticks. `workspacePackages` maps only workspace
+ * packages imported by this file to their directories. `symbols` maps names
+ * to native compiler types, with documentation and JSDoc tags shared across variants.
+ * `references` maps used names to complete AST declaration scopes by
+ * repo-relative path, rather than fixed line windows or full related files.
  */
-export const Reads = Schema.Array(Schema.Literals(["workspacePackages"]));
+export const Reads = Schema.Array(Schema.Literals(["workspacePackages", "symbols", "references"]));
 
 /**
  * A rule's examples, named in RFC 2119's words, which Jev reads as written. A
@@ -83,12 +105,6 @@ 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)),
-  /**
-   * What Jev reads for the rule beside the code, by name (see `Reads`). The
-   * rule's questions go in requests of their own, so only they read it, and
-   * a change to what is read judges the rule again.
-   */
-  reads: Schema.optionalKey(Reads),
   /**
    * 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
@@ -106,6 +122,12 @@ export const Rule = Schema.Struct({
   ...RuleFields.fields,
   reference: Schema.optionalKey(Schema.String),
   avoid: Schema.optionalKey(Schema.String),
+  // Guard the removed key instead of silently dropping it as an excess property.
+  reads: Schema.optionalKey(
+    Schema.declare((_value: unknown): _value is never => false, {
+      expected: "no rule-level reads; move reads to the top level of defineConfig({...})",
+    }),
+  ),
 })
   .pipe(
     Schema.decodeTo(
@@ -179,6 +201,8 @@ export const AdhereConfig = Schema.Struct({
    * The model id sent to typesafe. Defaults to "jev-latest"
    */
   model: Schema.optionalKey(Schema.String),
+  /** Where the questions go in place of TypeSafe's Jev, with its own model (see `Provider`). */
+  provider: Schema.optionalKey(ProviderSchema),
   /**
    * The minimum confidence threshold for a positive match. Defaults to 0.8
    */
@@ -196,6 +220,8 @@ export const AdhereConfig = Schema.Struct({
   presets: Schema.Array(Schema.Literals(presetNames)).pipe(
     Schema.withDecodingDefaultKey(Effect.succeed([])),
   ),
+  /** Shared context for every audited file and all its rules. Unset: all built-in reads; []: code only. */
+  reads: Schema.optionalKey(Reads),
   /**
    * 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
@@ -303,10 +329,13 @@ export type Loaded<T extends { readonly rules?: unknown }> = Omit<T, "rules"> &
 export const DEFAULT_MODEL = "jev-latest";
 export const DEFAULT_THRESHOLD = 0.8;
 export const DEFAULT_SUFFICIENCY_THRESHOLD = 0.6;
+export const DEFAULT_READS: typeof Reads.Type = ["workspacePackages", "symbols", "references"];
 
 /** A config with its presets folded in and every default applied. */
 export interface ResolvedConfig {
   readonly model: string;
+  /** Where the questions go in place of Jev; `model` is its model. */
+  readonly provider?: Provider;
   readonly threshold: number;
   /** Below this, a finding's sufficiency adds a warning to it. */
   readonly sufficiencyThreshold: number;
@@ -318,9 +347,11 @@ export interface ResolvedConfig {
   readonly exclude?: ReadonlyArray<string>;
   /** Whether Jev reads every comment; unset, only the `@adhere` notes. */
   readonly includeComments?: boolean;
+  /** Built-in context shared by every rule, with the default applied. */
+  readonly reads: typeof Reads.Type;
   /**
    * The workspace's packages, each name with its directory from the working
-   * directory, read from its manifests on every run, when a rule's `reads`
+   * directory, read from its manifests on every run when the config's reads
    * names them.
    */
   readonly workspacePackages?: Readonly<Record<string, string>>;
@@ -370,7 +401,8 @@ export const resolveConfig = (
   const last = <K extends "model" | "threshold">(key: K) =>
     applied.map((preset) => preset[key]).findLast((value) => value !== undefined);
   return {
-    model: config.model ?? last("model") ?? DEFAULT_MODEL,
+    model: config.provider?.model ?? config.model ?? last("model") ?? DEFAULT_MODEL,
+    ...(config.provider === undefined ? {} : { provider: config.provider }),
     threshold: flags.threshold ?? config.threshold ?? last("threshold") ?? DEFAULT_THRESHOLD,
     sufficiencyThreshold:
       flags.sufficiencyThreshold ?? config.sufficiencyThreshold ?? DEFAULT_SUFFICIENCY_THRESHOLD,
@@ -378,6 +410,7 @@ export const resolveConfig = (
     ...(flags.rpm === undefined ? {} : { rpm: flags.rpm }),
     ...(config.exclude === undefined ? {} : { exclude: config.exclude }),
     ...(config.includeComments === undefined ? {} : { includeComments: config.includeComments }),
+    reads: config.reads ?? DEFAULT_READS,
   };
 };
 

package/src/index.ts

@@ -12,6 +12,20 @@ export {
   type RuleSource,
 } from "#config.ts";
 export { findContradictions, formatContradictions, type Contradiction } from "#contradictions.ts";
+export { cloudflare, type CloudflareOptions } from "#providers/cloudflare.ts";
+export { jev, type JevOptions } from "#providers/jev.ts";
+export { openai, type OpenAIOptions } from "#providers/openai.ts";
+export {
+  type Answered,
+  type AskOptions,
+  ContextOverflow,
+  type Provider,
+  type Question,
+  RequestBlocked,
+  RequestFailed,
+  type SavedKey,
+  type State,
+} from "#providers/provider.ts";
 export { initProject, type InitOptions, type InitResult, type Install } from "#init.ts";
 export { parseRuleMarkdown } from "#markdown.ts";
 export { type PresetName, presetNames } from "#presets.ts";

package/src/markdown.ts

@@ -1,4 +1,4 @@
-import { ConfigUnavailable, type Example, Reads, type Rule } from "#config.ts";
+import { ConfigUnavailable, type Example, type Rule } from "#config.ts";
 import { Effect, Schema } from "effect";
 
 /**
@@ -34,8 +34,7 @@ import { Effect, Schema } from "effect";
  * `warning` reports the rule's findings as warnings, which do not fail a run.
  * `appliesTo` and `excludeIf`, the rule's scope, are JSON arrays of strings on
  * one line, as in `excludeIf: ["a type that mirrors a third-party format"]`.
- * So is `reads`, of the names of what Jev reads for the rule beside the code,
- * as in `reads: ["workspacePackages"]`.
+
  */
 const Matchers = Schema.fromJsonString(Schema.Array(Schema.String));
 
@@ -46,7 +45,6 @@ const FrontMatter = Schema.Struct({
   level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
   appliesTo: Schema.optionalKey(Matchers),
   excludeIf: Schema.optionalKey(Matchers),
-  reads: Schema.optionalKey(Schema.fromJsonString(Reads)),
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -209,7 +207,13 @@ export const parseRuleMarkdown = (
         message: `${file}: a rule starts with front matter between --- lines`,
       });
     }
-    const front = yield* Schema.decodeUnknownEffect(FrontMatter)(parseFrontMatter(match[1])).pipe(
+    const fields = parseFrontMatter(match[1]);
+    if (Object.hasOwn(fields, "reads")) {
+      return yield* ConfigUnavailable.make({
+        message: `${file}: move reads from the rule's front matter to the top level of defineConfig({...}) in your config file.`,
+      });
+    }
+    const front = yield* Schema.decodeUnknownEffect(FrontMatter)(fields).pipe(
       Effect.mapError((problem) =>
         ConfigUnavailable.make({ message: `${file}: ${problem.message}` }),
       ),