@drkmttr/adhere 0.18.0 → 0.21.2

package/src/cli.ts

@@ -24,12 +24,18 @@ import {
   type Progress,
   progressAfter,
   progressLine,
+  renderJson,
+  renderMarkdown,
+  renderRuleReports,
   sendQuestion,
 } from "#workflows/format.ts";
 import type { Flags } from "#config.ts";
 import { findContradictions, formatContradictions } from "#contradictions.ts";
+import { createRule } from "#create/wizard.ts";
+import { AGENTS } from "#create/agents.ts";
 import { type Install, initProject } from "#init.ts";
 import { installRules, listRules, parseSource } from "#install.ts";
+import { renderInstructions } from "#instructions.ts";
 import { formatLinterCheck, tallyProjectRules } from "#mechanical.ts";
 import { type PresetName, presetNames } from "#presets.ts";
 import type { SavedKey } from "#providers/provider.ts";
@@ -39,6 +45,7 @@ import {
   Console,
   Effect,
   Exit,
+  FileSystem,
   Layer,
   LogLevel,
   Option,
@@ -49,8 +56,9 @@ import {
   Schema,
   Stdio,
   Stream,
+  Terminal,
 } from "effect";
-import { Argument, Command, Flag, Prompt } from "effect/cli";
+import { Argument, CliError, Command, Flag, Prompt } from "effect/cli";
 // 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 `#`
@@ -59,6 +67,10 @@ 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" };
 
+// @adhere This file owns CLI flags, progress output, and command wiring. Audit execution,
+// scaffolding, rule installation, credential storage, and rule checks are implemented in
+// their own modules imported above; the commands here connect them to the CLI.
+
 class FindingsReported extends Schema.TaggedError<FindingsReported>()("FindingsReported", {
   count: Schema.Finite,
 }) {
@@ -114,6 +126,13 @@ const sufficiencyThreshold = Flag.Finite("sufficiency-threshold").pipe(
   ),
 );
 
+const typeAware = Flag.Boolean("type-aware").pipe(
+  Flag.optional,
+  Flag.withDescription(
+    "Include compiler-resolved symbols and declaration excerpts. Off by default.",
+  ),
+);
+
 const limit = Flag.Int("limit").pipe(
   Flag.filter(
     (files) => files >= 0,
@@ -235,9 +254,43 @@ export const auditLayer = (flags: Flags, filter: ReadonlyArray<string> = []) =>
 /** `adhere lint`: the audit. */
 export const lintCommand = Command.make(
   "lint",
-  { preset, threshold, sufficiencyThreshold, yes, limit, rpm, filter, denyWarnings },
+  {
+    preset,
+    threshold,
+    sufficiencyThreshold,
+    typeAware,
+    yes,
+    limit,
+    rpm,
+    filter,
+    denyWarnings,
+    json: Flag.Boolean("json").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription(
+        "Write one JSON file per violated rule to .adhere/reports/. Use --stdout for one combined report instead.",
+      ),
+    ),
+    md: Flag.Boolean("md").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription(
+        "Write one Markdown file per violated rule to .adhere/reports/. Use --stdout for one combined report instead.",
+      ),
+    ),
+    stdout: Flag.Boolean("stdout").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription(
+        "Print all findings together instead of writing files. Select either --json or --md for a formatted report.",
+      ),
+    ),
+  },
   (input) =>
     Effect.gen(function* () {
+      if (input.stdout && input.json && input.md) {
+        return yield* CliError.UserError.make({
+          cause:
+            "Choose either --json or --md with --stdout; both formats can be written to files together.",
+        });
+      }
       const stdio = yield* Stdio.Stdio;
       const plan = yield* planAudit({ limit: Option.getOrUndefined(input.limit) });
       const limits = { filter: input.filter, rpm: Option.getOrUndefined(input.rpm) };
@@ -247,8 +300,7 @@ export const lintCommand = Command.make(
         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.
+      // Keep prompting limited to interactive runs, including when JSON is requested.
       const interactive = (yield* stdio.stdinIsTerminal) && (yield* stdio.stdoutIsTerminal);
       if (
         (plan.requests > 0 || (plan.cachedLocateRequests ?? 0) > 0) &&
@@ -257,6 +309,11 @@ export const lintCommand = Command.make(
       ) {
         const send = yield* Prompt.run(
           Prompt.Confirm({ message: sendQuestion(plan), initial: true }),
+        ).pipe(
+          Effect.updateService(Terminal.Terminal, (terminal) => ({
+            ...terminal,
+            display: toStderr,
+          })),
         );
         if (!send) {
           yield* toStderr("Nothing sent.\n");
@@ -272,16 +329,33 @@ export const lintCommand = Command.make(
       if (input.filter.length === 0) yield* pruneCache(plan);
       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(),
-          threshold: plan.threshold,
-          sufficiencyThreshold: plan.sufficiencyThreshold,
-          ...(plan.provider === undefined ? {} : { provider: plan.provider }),
-        }).join("\n"),
-      );
+      const options = {
+        color,
+        root: path.resolve(),
+        threshold: plan.threshold,
+        sufficiencyThreshold: plan.sufficiencyThreshold,
+        ...(plan.provider === undefined ? {} : { provider: plan.provider }),
+      };
+      if (!input.stdout && (input.json || input.md)) {
+        const fs = yield* FileSystem.FileSystem;
+        const directory = path.join(options.root, ".adhere", "reports");
+        const reports = renderRuleReports(result, input, options);
+        yield* fs.remove(directory, { recursive: true, force: true });
+        yield* fs.makeDirectory(directory, { recursive: true });
+        for (const [name, report] of reports) {
+          yield* fs.writeFileString(path.join(directory, name), report);
+        }
+        yield* toStderr(`Wrote ${reports.size} report files to .adhere/reports/.\n`);
+      } else {
+        // One write: separate Console.log calls have interleaved out of order here.
+        yield* Console.log(
+          input.json
+            ? renderJson(result, options)
+            : input.md
+              ? renderMarkdown(result, options)
+              : render(result, options).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) {
@@ -298,6 +372,7 @@ export const lintCommand = Command.make(
         presets: input.preset,
         threshold: Option.getOrUndefined(input.threshold),
         sufficiencyThreshold: Option.getOrUndefined(input.sufficiencyThreshold),
+        typeAware: Option.getOrUndefined(input.typeAware),
         rpm: Option.getOrUndefined(input.rpm),
       },
       input.filter,
@@ -544,6 +619,48 @@ export const skillCommand = Command.make("skill", { name: skillName }, ({ name }
   ),
 );
 
+const agent = Flag.Literals("agent", AGENTS).pipe(
+  Flag.optional,
+  Flag.withDescription(
+    "The coding agent to ask this time: claude, codex, or omp, in place of the one setup saved.",
+  ),
+);
+
+/** `adhere rules create [idea]`: a wizard that writes one rule, with a coding agent's help. */
+const rulesCreateCommand = Command.make(
+  "create",
+  {
+    idea: Argument.String("idea").pipe(
+      Argument.optional,
+      Argument.withDescription("What the rule should enforce. Asked for when left out."),
+    ),
+    agent,
+    setup: Flag.Boolean("setup").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription(
+        "Choose again which agent to ask and which GitHub repo, as org/repo, holds the organization's shared rules. The first run asks without it.",
+      ),
+    ),
+  },
+  (input) => createRule(input.idea, input.agent, input.setup).pipe(Effect.provide(statusLayer)),
+).pipe(
+  Command.withDescription(
+    "Write a rule with a coding agent's help: it suggests whether the rule belongs to this project or the organization's shared rules repo, names it, chooses a RULE.md or, when Jev needs state the file cannot show, a RULE.ts, and says which config context (typeAware, reads) it needs. It finds code in the repo for you to judge, with the lines around it, and drafts the rule from your answers; the draft is checked as adhere validate checks wording. A project rule is written to .adhere/rules/; an organization rule is pushed to the shared repo on a branch for a pull request.",
+  ),
+);
+
+export const rulesCommand = Command.make("rules").pipe(
+  Command.withDescription("Work on this repo's rules."),
+  Command.withSubcommands([rulesCreateCommand]),
+);
+
+export const postinstallCommand = Command.make("postinstall", {}, () =>
+  Effect.gen(function* () {
+    const path = yield* Path.Path;
+    yield* Console.log(yield* renderInstructions(path.resolve()));
+  }),
+).pipe(Command.withDescription("Render instruction files into a managed block in AGENTS.md."));
+
 /** 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/rules/, judged by Jev."),
@@ -568,10 +685,12 @@ export const cli = Command.make("adhere").pipe(
     lintCommand,
     validateCommand,
     initCommand,
+    postinstallCommand,
     listCommand,
     installCommand,
     loginCommand,
     logoutCommand,
     skillCommand,
+    rulesCommand,
   ]),
 );

package/src/config.ts

@@ -1,7 +1,7 @@
 import { type PresetName, presetNames } from "#presets.ts";
 import { type Provider, SAVED_KEYS } from "#providers/provider.ts";
 import type { RuleSet } from "#rules.ts";
-import { Effect, Predicate, Schema, SchemaTransformation } from "effect";
+import { Effect, Predicate, Schema } from "effect";
 
 export type RuleId = string;
 
@@ -32,7 +32,10 @@ const ProviderSchema = Schema.declare(
     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" },
+  {
+    expected: "a provider: a model, and a function to ask it",
+    toCode: () => ({ runtime: "Provider", Type: "Provider" }),
+  },
 );
 
 /**
@@ -56,12 +59,16 @@ export type AppendState = (
  * 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
+ * packages imported by this file to their directories. `dependents` lists what
+ * depends on this file: workspace packages whose package.json names its package,
+ * and files that import it by a relative path. `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", "symbols", "references"]));
+export const Reads = Schema.Array(
+  Schema.Literals(["workspacePackages", "dependents", "symbols", "references"]),
+);
 
 /**
  * A rule's examples, named in RFC 2119's words, which Jev reads as written. A
@@ -69,91 +76,84 @@ export const Reads = Schema.Array(Schema.Literals(["workspacePackages", "symbols
  * be. A guideline, which asks for less, shows code that `should` be written
  * and code that `shouldNot` be.
  */
-const RuleFields = Schema.Struct({
-  description: Schema.String,
-  /**
-   * What the description leaves out, such as why the rule holds or where it
-   * does not: in a `RULE.md`, the prose around its code. Jev reads it after
-   * the description, as part of the rule; the report shows the description
-   * alone.
-   */
-  details: Schema.optionalKey(Schema.String),
-  must: Schema.optionalKey(Schema.String),
-  never: Schema.optionalKey(Schema.String),
-  should: Schema.optionalKey(Schema.String),
-  shouldNot: Schema.optionalKey(Schema.String),
-  threshold: Schema.optionalKey(Schema.Finite),
-  /**
-   * Test files, which a rule skips by default: `only` for a rule about tests,
-   * which judges nothing else, and `include` for one that holds in tests too.
-   */
-  tests: Schema.optionalKey(Schema.Literals(["only", "include"])),
-  /**
-   * How a finding under the rule is reported: an `error`, the default, which
-   * fails the run, or a `warning`, for a nit or a rule that errs toward false
-   * findings, which does not.
-   */
-  level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
-  /**
-   * Where the rule applies, each a description of code that breaks it: Jev is
-   * asked of each whether any code that breaks the rule is as it describes,
-   * and a finding stands only when it says yes to every one.
-   */
-  appliesTo: Schema.optionalKey(Schema.Array(Schema.String)),
-  /**
-   * Where the rule does not apply: Jev is asked of each whether all the code
-   * 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.
-   */
+export const Rule = Schema.Struct({
+  description: Schema.String.annotate({
+    description: "What the rule says, in one sentence. The report shows it with each finding.",
+  }),
+  details: Schema.optionalKey(Schema.String).annotate({
+    description:
+      "What the description leaves out, such as why the rule holds or where it does not: in a `RULE.md`, the prose around its code. Jev reads it after the description, as part of the rule; the report shows the description alone.",
+  }),
+  must: Schema.optionalKey(Schema.String).annotate({
+    description:
+      "Code the rule requires. A rule has `must` and `never`, or, as a guideline, `should` and `shouldNot`.",
+  }),
+  never: Schema.optionalKey(Schema.String).annotate({
+    description: "Code the rule forbids.",
+  }),
+  should: Schema.optionalKey(Schema.String).annotate({
+    description: "A guideline's code to write.",
+  }),
+  shouldNot: Schema.optionalKey(Schema.String).annotate({
+    description: "A guideline's code not to write.",
+  }),
+  threshold: Schema.optionalKey(Schema.Finite).annotate({
+    description: "The rule's own confidence threshold, 0 to 1, in place of the config's.",
+  }),
+  tests: Schema.optionalKey(Schema.Literals(["only", "include"])).annotate({
+    description:
+      "Test files, which a rule skips by default: `only` for a rule about tests, which judges nothing else, and `include` for one that holds in tests too.",
+  }),
+  level: Schema.optionalKey(Schema.Literals(["error", "warning"])).annotate({
+    description:
+      "How a finding under the rule is reported: an `error`, the default, which fails the run, or a `warning`, for a nit or a rule that errs toward false findings, which does not.",
+  }),
+  appliesTo: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
+    description:
+      "Where the rule applies, each a description of code that breaks it: Jev is asked of each whether any code that breaks the rule is as it describes, and a finding stands only when it says yes to every one.",
+  }),
+  excludeIf: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
+    description:
+      "Where the rule does not apply: Jev is asked of each whether all the code that breaks the rule is as it describes, and a yes to any drops the finding.",
+  }),
   appendState: Schema.optionalKey(
     Schema.declare((value: unknown): value is AppendState => typeof value === "function", {
       expected: "a function",
+      toCode: () => ({ runtime: "AppendState", Type: "AppendState" }),
     }),
-  ),
-});
-
-/** Before 0.7, a rule's examples were `reference` and `avoid`: read as `must` and `never`. */
-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({...})",
+  ).annotate({
+    description:
+      "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.",
+  }),
+  options: Schema.optionalKey(
+    Schema.declare((value: unknown): value is Schema.Decoder<unknown> => Schema.isSchema(value), {
+      expected: "an Effect Schema",
+      toCode: () => ({ runtime: "Schema", Type: "Schema.Decoder<unknown>" }),
     }),
-  ),
+  ).annotate({
+    description:
+      "The settings a rule written in TypeScript takes, as an Effect Schema, set under the rule's id in a config's `overrides`, as `options`. A key the schema does not make optional must be set. Jev reads the decoded settings as `options`, in requests of the rule's own.",
+  }),
 })
-  .pipe(
-    Schema.decodeTo(
-      RuleFields,
-      SchemaTransformation.transform({
-        decode: ({ reference, avoid, ...rule }) => ({
-          ...rule,
-          ...(rule.must === undefined && reference !== undefined ? { must: reference } : {}),
-          ...(rule.never === undefined && avoid !== undefined ? { never: avoid } : {}),
-        }),
-        encode: (rule) => rule,
-      }),
+  .check(
+    Schema.makeFilter(
+      (rule) => {
+        const requirement = rule.must !== undefined || rule.never !== undefined;
+        const guideline = rule.should !== undefined || rule.shouldNot !== undefined;
+        return requirement && guideline
+          ? "a rule is a requirement (must, never) or a guideline (should, shouldNot), not both"
+          : requirement || guideline
+            ? undefined
+            : "a rule needs an example: must, never, should, or shouldNot";
+      },
+      { toCode: () => ({ runtime: "Schema.makeFilter(isRequirementOrGuideline)" }) },
     ),
   )
-  .check(
-    Schema.makeFilter((rule) => {
-      const requirement = rule.must !== undefined || rule.never !== undefined;
-      const guideline = rule.should !== undefined || rule.shouldNot !== undefined;
-      return requirement && guideline
-        ? "a rule is a requirement (must, never) or a guideline (should, shouldNot), not both"
-        : requirement || guideline
-          ? undefined
-          : "a rule needs an example: must, never, should, or shouldNot";
-    }),
-  );
-export interface Rule extends Schema.Schema.Type<typeof Rule> {}
+  .annotate({ identifier: "Rule" });
+export interface Rule extends Schema.Schema.Type<typeof Rule> {
+  /** The settings `options` decoded from the config's override, set as the config is loaded. */
+  readonly optionValues?: unknown;
+}
 
 /** How a finding is reported: an error fails the run, a warning does not. */
 export type Level = NonNullable<Rule["level"]>;
@@ -186,70 +186,76 @@ export type Rules = Readonly<Record<RuleId, Rule>>;
 /** Rules inline, or a directory of Markdown rule files (see `markdown.ts`). */
 export type RuleSource = Rules | string | URL;
 
-/** A rule's setting in a config's `overrides`: `off`, a level, or a level and a threshold. */
+/** A rule's setting in a config's `overrides`: `off`, a level, or a level, a threshold, and its options. */
 const Override = Schema.Union([
   Schema.Literals(["off", "error", "warning"]),
   Schema.Struct({
     level: Schema.optionalKey(Schema.Literals(["off", "error", "warning"])),
     threshold: Schema.optionalKey(Schema.Finite),
+    options: Schema.optionalKey(Schema.Unknown),
   }),
 ]);
 export type Override = typeof Override.Type;
 
+/** A config file's keys. Each `description` is what the docs' Config file reference shows. */
 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
-   */
-  threshold: Schema.optionalKey(Schema.Finite),
-  /**
-   * Below this, Jev's probability that a file shows enough to decide a
-   * finding's rule adds a warning to the finding: check what the code relies
-   * on outside the file. Defaults to 0.6
-   */
-  sufficiencyThreshold: Schema.optionalKey(Schema.Finite),
-  /**
-   * The presets to use for rule matching. Defaults to an empty array. Current presets
-   * include "effect" and "alchemy". Subcategories can be expanded by appending `/<subcategory>`.
-   */
-  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),
-  /** Maximum characters of each symbol's complete resolved content. Defaults to 256. */
-  maxSymbolLength: Schema.optionalKey(Schema.Natural),
-  /** Maximum characters of documentation and JSDoc tags per symbol. Defaults to 256; 0 omits them. */
-  maxSymbolDocumentationLength: Schema.optionalKey(Schema.Natural),
-  /**
-   * 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])),
-  /**
-   * Globs, relative to the working directory, of files no rule judges: what
-   * `--filter '!<glob>'` leaves out of one run, left out of every run.
-   */
-  exclude: Schema.optionalKey(Schema.Array(Schema.String)),
-  /**
-   * Settings for rules by the id a report names them with, a preset's with
-   * its preset first, as in `alchemy/providers/idempotent-delete`: `off`, a
-   * level, or `{ level, threshold }`. A preset's rule changes without its text
-   * being copied into `rules`.
-   */
-  overrides: Schema.optionalKey(Schema.Record(Schema.String, Override)),
-  /**
-   * Whether Jev reads every comment, for rules about comments. By default
-   * comments are taken out, since a comment changes nothing a file does, but
-   * for the notes that say `@adhere`.
-   */
-  includeComments: Schema.optionalKey(Schema.Boolean),
+  model: Schema.optionalKey(Schema.String).annotate({
+    description: `The model id sent to TypeSafe AI. Defaults to "jev-latest".`,
+  }),
+  provider: Schema.optionalKey(ProviderSchema).annotate({
+    description:
+      "Where the questions go in place of TypeSafe's Jev, with its own model (see `Provider`).",
+  }),
+  threshold: Schema.optionalKey(Schema.Finite).annotate({
+    description: "The minimum confidence threshold for a positive match. Defaults to 0.8.",
+  }),
+  sufficiencyThreshold: Schema.optionalKey(Schema.Finite).annotate({
+    description:
+      "Below this, Jev's probability that a file shows enough to decide a finding's rule adds a warning to the finding: check what the code relies on outside the file. Defaults to 0.6.",
+  }),
+  presets: Schema.Array(Schema.Literals(presetNames))
+    .pipe(Schema.withDecodingDefaultKey(Effect.succeed([])))
+    .annotate({
+      description:
+        "The built-in rule sets to use, such as `effect` or `alchemy`. Append `/<topic>` for one topic, as in `effect/basics`. Defaults to none.",
+    }),
+  reads: Schema.optionalKey(Reads).annotate({
+    description:
+      "Workspace context shared by every rule: `workspacePackages` (the default) and `dependents`; `[]` disables it. Native read names do not enable type awareness.",
+  }),
+  typeAware: Schema.optionalKey(Schema.Boolean).annotate({
+    description:
+      "Include both compiler-resolved symbols and declaration excerpts. Defaults to false.",
+  }),
+  maxSymbolLength: Schema.optionalKey(Schema.Natural).annotate({
+    description: "Maximum characters of each symbol's complete resolved content. Defaults to 256.",
+  }),
+  maxSymbolDocumentationLength: Schema.optionalKey(Schema.Natural).annotate({
+    description:
+      "Maximum characters of documentation and JSDoc tags per symbol. Defaults to 256; 0 omits them.",
+  }),
+  rules: Schema.optionalKey(
+    Schema.Union([Schema.Record(Schema.String, Rule), Schema.String]),
+  ).annotate({
+    description:
+      "A record of rules (see Rule keys), 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/`.",
+  }),
+  instructions: Schema.optionalKey(Schema.NonEmptyString).annotate({
+    description:
+      "Instructions directory relative to the config file. Unset: `.adhere/instructions`, then `.agents/instructions`.",
+  }),
+  exclude: Schema.optionalKey(Schema.Array(Schema.String)).annotate({
+    description:
+      "Globs, relative to the working directory, of files no rule judges: what `--filter '!<glob>'` leaves out of one run, left out of every run.",
+  }),
+  overrides: Schema.optionalKey(Schema.Record(Schema.String, Override)).annotate({
+    description:
+      "Settings for rules by the id a report names them with, a preset's with its preset first, as in `alchemy/providers/idempotent-delete`: `off`, a level, or `{ level, threshold, options }`. A preset's rule changes without its text being copied into `rules`.",
+  }),
+  includeComments: Schema.optionalKey(Schema.Boolean).annotate({
+    description:
+      "Whether Jev reads every comment, for rules about comments. By default comments are taken out, since a comment changes nothing a file does, but for the notes that say `@adhere`.",
+  }),
 });
 
 /** Where a repo keeps what adhere reads and writes: its config, its rules, and the cache. */
@@ -333,7 +339,7 @@ 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"];
+export const DEFAULT_READS: typeof Reads.Type = ["workspacePackages"];
 export const DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH = 256;
 export const DEFAULT_MAX_SYMBOL_LENGTH = 256;
 
@@ -355,6 +361,8 @@ export interface ResolvedConfig {
   readonly includeComments?: boolean;
   /** Built-in context shared by every rule, with the default applied. */
   readonly reads: typeof Reads.Type;
+  /** Whether both native symbol and declaration context are enabled. */
+  readonly typeAware: boolean;
   /** Maximum characters of each symbol's complete resolved content. */
   readonly maxSymbolLength: number;
   /** Maximum characters of documentation and JSDoc tags before the complete symbol limit applies. */
@@ -362,9 +370,11 @@ export interface ResolvedConfig {
   /**
    * The workspace's packages, each name with its directory from the working
    * directory, read from its manifests on every run when the config's reads
-   * names them.
+   * names `workspacePackages` or `dependents`.
    */
   readonly workspacePackages?: Readonly<Record<string, string>>;
+  /** Per workspace package, the workspace packages that depend on it, when reads names `dependents`. */
+  readonly workspaceDependents?: Readonly<Record<string, Readonly<Record<string, string>>>>;
 }
 
 /** Command-line values that apply on top of the config file. */
@@ -376,6 +386,8 @@ export interface Flags {
   readonly sufficiencyThreshold?: number | undefined;
   /** Throttles requests to Jev to at most this many a minute. */
   readonly rpm?: number | undefined;
+  /** Replaces the config's native-context opt-in. */
+  readonly typeAware?: boolean | undefined;
 }
 
 /**
@@ -410,6 +422,7 @@ export const resolveConfig = (
   });
   const last = <K extends "model" | "threshold">(key: K) =>
     applied.map((preset) => preset[key]).findLast((value) => value !== undefined);
+  const typeAware = flags.typeAware ?? config.typeAware ?? false;
   return {
     model: config.provider?.model ?? config.model ?? last("model") ?? DEFAULT_MODEL,
     ...(config.provider === undefined ? {} : { provider: config.provider }),
@@ -420,7 +433,13 @@ 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,
+    typeAware,
+    reads: [
+      ...(config.reads ?? DEFAULT_READS).filter(
+        (read) => read === "workspacePackages" || read === "dependents",
+      ),
+      ...(typeAware ? (["symbols", "references"] as const) : []),
+    ],
     maxSymbolLength: config.maxSymbolLength ?? DEFAULT_MAX_SYMBOL_LENGTH,
     maxSymbolDocumentationLength:
       config.maxSymbolDocumentationLength ?? DEFAULT_MAX_SYMBOL_DOCUMENTATION_LENGTH,