@drkmttr/adhere 0.18.1 → 0.21.2

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,72 +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([])),
-  ),
-  /** Workspace context shared by every rule. Defaults to workspacePackages; [] disables it. Native read names do not enable type awareness. */
-  reads: Schema.optionalKey(Reads),
-  /** Include both compiler-resolved symbols and declaration excerpts. Defaults to false. */
-  typeAware: Schema.optionalKey(Schema.Boolean),
-  /** 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. */
@@ -366,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. */
@@ -429,7 +435,9 @@ export const resolveConfig = (
     ...(config.includeComments === undefined ? {} : { includeComments: config.includeComments }),
     typeAware,
     reads: [
-      ...(config.reads ?? DEFAULT_READS).filter((read) => read === "workspacePackages"),
+      ...(config.reads ?? DEFAULT_READS).filter(
+        (read) => read === "workspacePackages" || read === "dependents",
+      ),
       ...(typeAware ? (["symbols", "references"] as const) : []),
     ],
     maxSymbolLength: config.maxSymbolLength ?? DEFAULT_MAX_SYMBOL_LENGTH,

package/src/create/agents.ts

@@ -0,0 +1,149 @@
+/**
+ * The coding agents installed beside adhere, asked one question at a time
+ * without a session: `claude -p`, `codex exec`, and `omp -p`. The prompt goes
+ * on stdin, the agent may read the repo it runs in but not change it, and
+ * what comes back is the text of its last message. Given a JSON schema, the
+ * agent is held to it where its CLI can, and the text is that JSON.
+ */
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Option, Schema } from "effect";
+
+export const AGENTS = ["claude", "codex", "omp"] as const;
+export type Agent = (typeof AGENTS)[number];
+
+/** The agents on PATH, in the order adhere prefers them. */
+export const installedAgents = (): ReadonlyArray<Agent> =>
+  AGENTS.filter((agent) => Bun.which(agent) !== null);
+
+/** `claude -p --output-format json` prints its events, the last its result. */
+const ClaudeResult = Schema.fromJsonString(
+  Schema.Array(
+    Schema.Struct({
+      type: Schema.String,
+      is_error: Schema.optionalKey(Schema.Boolean),
+      result: Schema.optionalKey(Schema.String),
+      structured_output: Schema.optionalKey(Schema.Unknown),
+    }),
+  ),
+);
+
+/** The line of `omp --mode json` that ends an assistant's message; every other line is skipped. */
+const OmpAnswer = Schema.fromJsonString(
+  Schema.Struct({
+    type: Schema.Literal("message_end"),
+    message: Schema.Struct({
+      role: Schema.Literal("assistant"),
+      content: Schema.Array(
+        Schema.Struct({ type: Schema.String, text: Schema.optionalKey(Schema.String) }),
+      ),
+    }),
+  }),
+);
+
+/** Runs `command` in `cwd` with `input` on stdin, and returns its stdout once it exits 0. */
+export const run = async (
+  command: string,
+  args: ReadonlyArray<string>,
+  cwd: string,
+  input: string,
+) => {
+  const child = Bun.spawn([command, ...args], {
+    cwd,
+    stdin: new Blob([input]),
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ]);
+  if (code !== 0) throw new Error(`${command} exited ${code}: ${stderr.trim().slice(-500)}`);
+  return stdout;
+};
+
+/** The text of `agent`'s answer to `prompt`, asked in `cwd`; with `schema`, its JSON. */
+export const askAgent = async (
+  agent: Agent,
+  prompt: string,
+  cwd: string,
+  schema?: object,
+): Promise<string> => {
+  switch (agent) {
+    case "claude": {
+      const events = Schema.decodeUnknownSync(ClaudeResult)(
+        await run(
+          "claude",
+          [
+            "-p",
+            "--output-format=json",
+            "--tools=Read,Grep,Glob",
+            "--no-session-persistence",
+            ...(schema === undefined ? [] : [`--json-schema=${JSON.stringify(schema)}`]),
+          ],
+          cwd,
+          prompt,
+        ),
+      );
+      const result = events.findLast((event) => event.type === "result");
+      if (result === undefined || result.is_error === true) {
+        throw new Error(`claude did not answer: ${result?.result ?? "no result"}`);
+      }
+      return schema === undefined
+        ? (result.result ?? "")
+        : JSON.stringify(result.structured_output);
+    }
+    case "codex": {
+      const dir = await mkdtemp(join(tmpdir(), "adhere-codex-"));
+      try {
+        const out = join(dir, "answer");
+        const schemaFile = join(dir, "schema.json");
+        if (schema !== undefined) await writeFile(schemaFile, JSON.stringify(schema));
+        await run(
+          "codex",
+          [
+            "exec",
+            "--sandbox=read-only",
+            "--ephemeral",
+            "--skip-git-repo-check",
+            "--color=never",
+            `--output-last-message=${out}`,
+            ...(schema === undefined ? [] : [`--output-schema=${schemaFile}`]),
+            "-",
+          ],
+          cwd,
+          prompt,
+        );
+        return await readFile(out, "utf8");
+      } finally {
+        await rm(dir, { recursive: true, force: true });
+      }
+    }
+    case "omp": {
+      // omp holds no answer to a schema, so the schema goes in the prompt and
+      // the JSON is cut out of whatever surrounds it.
+      const asked =
+        schema === undefined
+          ? prompt
+          : `${prompt}\n\nReply with only JSON matching this schema:\n${JSON.stringify(schema)}`;
+      const lines = (
+        await run(
+          "omp",
+          ["-p", "--mode=json", "--tools=read,grep,glob", "--no-session", "--no-title"],
+          cwd,
+          asked,
+        )
+      ).split("\n");
+      const answer = lines
+        .flatMap((line) => Option.toArray(Schema.decodeUnknownOption(OmpAnswer)(line)))
+        .at(-1);
+      if (answer === undefined) throw new Error("omp did not answer");
+      const text = answer.message.content
+        .flatMap((part) => (part.type === "text" && part.text !== undefined ? [part.text] : []))
+        .join("");
+      return schema === undefined ? text : text.slice(text.indexOf("{"), text.lastIndexOf("}") + 1);
+    }
+  }
+};