@drkmttr/adhere 0.18.0 → 0.21.2

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);
+    }
+  }
+};

package/src/create/ask.ts

@@ -0,0 +1,147 @@
+/**
+ * What `adhere rules create` asks the coding agent, and the answers it
+ * decodes: the rule's shape, code in the repo for the user to judge, and the
+ * rule file itself.
+ */
+import { type Agent, askAgent } from "#create/agents.ts";
+import { spinning } from "#create/look.ts";
+import { Effect, Schema } from "effect";
+import skill from "../../skills/adhere/SKILL.md" with { type: "text" };
+
+export class RuleNotCreated extends Schema.TaggedError<RuleNotCreated>()("RuleNotCreated", {
+  message: Schema.String,
+}) {}
+
+export const Shape = Schema.Struct({
+  linter: Schema.NullOr(Schema.String),
+  scope: Schema.Literals(["project", "org"]),
+  scopeReason: Schema.String,
+  format: Schema.Literals(["markdown", "typescript"]),
+  formatReason: Schema.String,
+  typeAware: Schema.Boolean,
+  reads: Schema.Array(Schema.Literals(["workspacePackages", "dependents"])),
+  contextReason: Schema.String,
+  names: Schema.Array(Schema.String),
+});
+export type Shape = typeof Shape.Type;
+
+const Candidate = Schema.Struct({
+  file: Schema.String,
+  startLine: Schema.Int,
+  endLine: Schema.Int,
+  violation: Schema.Boolean,
+  reason: Schema.String,
+});
+export type Candidate = typeof Candidate.Type;
+export const Candidates = Schema.Struct({ candidates: Schema.Array(Candidate) });
+
+/** Code from the repo the user has judged: where it is, as the file holds it, and whether it breaks the rule. */
+export interface Reviewed {
+  readonly where: string;
+  readonly code: string;
+  readonly violation: boolean;
+  /** Whether the user's call matched the agent's. */
+  readonly agreed: boolean;
+}
+
+export const shapePrompt = (
+  idea: string,
+) => `You are helping write a rule for adhere, a linter for conventions a normal linter cannot check: a model, Jev, judges each source file against each rule. A rule lives in .adhere/rules/<topic>/<name>/, either in this repository, for its own code, or in the organization's shared rules repository, which every repository installs from.
+
+The user wants a rule for: ${idea}
+
+Look at this repository as much as you need, then answer:
+- linter: an existing linter rule (ESLint, oxlint, TypeScript, or the like) that already checks this, by name, or null.
+- scope: "project" when the rule is about this repository's own code, "org" when it would hold in any of the organization's repositories.
+- scopeReason: one sentence saying why.
+- format: "markdown" for a RULE.md, the rule's text and examples; nearly every rule is one. "typescript" for a RULE.ts, only when judging a file needs something neither the file nor the shared context below shows, such as a schema or a list another file holds: its appendState hook reads it and adds it to what Jev reads for that rule.
+- formatReason: one sentence saying why.
+- typeAware: true when judging needs the compiler's view of the file: the types of the names it uses, or the declarations of what it uses from other files. It is slower and costs more, so false unless the file cannot show it.
+- reads: the shared context it needs: "workspacePackages", the workspace packages the file imports and their directories, and "dependents", what depends on the file. Empty when the code is enough.
+- contextReason: one sentence saying why typeAware and reads are as you set them.
+- names: three ids for the rule, each "topic/rule-name" in lowercase kebab case. Reuse a topic from .adhere/rules/ where one fits.`;
+
+export const examplesPrompt = (
+  idea: string,
+  id: string,
+) => `Find code in this repository to test the adhere rule ${id}: ${idea}
+
+Give up to six excerpts, a mix of code that breaks the rule and code that follows it; borderline cases are the most useful. Each is the repo-relative file, the excerpt's first and last line numbers, at most 15 lines apart, violation: whether it breaks the rule, and reason: one sentence saying why. Use only code that exists, and give none when there is none.`;
+
+const contextOf = (shape: Shape) =>
+  [
+    "`code`",
+    ...shape.reads.map((read) => `\`${read}\``),
+    ...(shape.typeAware ? ["`symbols`", "`references`"] : []),
+  ].join(", ");
+
+const typescriptFormat = (shape: Shape) =>
+  `Write it as a RULE.ts, because ${shape.formatReason} It imports defineRule from "@drkmttr/adhere" and default-exports defineRule({ description, details, must, never, appendState }). appendState(state, file, Bun) runs before each request for the rule: file is { path, contents }, its path absolute, and Bun is Bun's API, as in Bun.file(path).text() or new Bun.Glob(pattern). What it returns is spread over the request's state; name each key it adds in the description, in backticks. Helpers go in the same file.`;
+
+const reviewedOf = (reviewed: ReadonlyArray<Reviewed>) =>
+  reviewed.length === 0
+    ? "No code from the repository was judged: write short examples of your own."
+    : `The user judged this code from the repository. Base the rule's examples on what shows it best; you need not use all of it. Where the user overruled your first call, word the rule so the difference is clear.\n\n${reviewed
+        .map(
+          ({ where, code, violation, agreed }) =>
+            `${violation ? "Breaks the rule" : "Does not break the rule"}, ${where}${agreed ? "" : " (overruled)"}\n\`\`\`\n${code}\n\`\`\``,
+        )
+        .join("\n\n")}`;
+
+export const writePrompt = (
+  idea: string,
+  id: string,
+  shape: Shape,
+  reviewed: ReadonlyArray<Reviewed>,
+) => `${skill}
+
+---
+
+Using the reference above, write the rule file for this adhere rule.
+
+Rule id: ${id}
+What it enforces: ${idea}
+What Jev reads beside the rule: ${contextOf(shape)}
+${shape.format === "typescript" ? typescriptFormat(shape) : "Write it as a RULE.md."}
+
+${reviewedOf(reviewed)}
+
+Reply with only the file's contents, starting with its ${shape.format === "typescript" ? "imports" : "front matter"}.`;
+
+/** An agent's reply as the file it holds, without the fence it may wrap it in. */
+export const unfenced = (text: string) =>
+  /^\s*```[a-z]*\n([\s\S]*?)\n```\s*$/.exec(text)?.[1] ?? text.trim();
+
+export const asking = (agent: Agent, what: string, cwd: string, prompt: string, schema?: object) =>
+  spinning(
+    `Asking ${agent} ${what}`,
+    Effect.tryPromise({
+      try: () => askAgent(agent, prompt, cwd, schema),
+      catch: (cause) =>
+        new RuleNotCreated({ message: cause instanceof Error ? cause.message : String(cause) }),
+    }),
+  );
+
+export const askingFor = <A>(
+  agent: Agent,
+  what: string,
+  cwd: string,
+  prompt: string,
+  Answer: Schema.Codec<A, A>,
+) =>
+  asking(
+    agent,
+    what,
+    cwd,
+    prompt,
+    Schema.toJsonSchemaDocument(Answer, { onExcessProperty: "error" }).schema,
+  ).pipe(
+    Effect.flatMap((text) =>
+      Schema.decodeUnknownEffect(Schema.fromJsonString(Answer))(text).pipe(
+        Effect.mapError(
+          (problem) =>
+            new RuleNotCreated({ message: `${agent}'s answer did not decode: ${problem.message}` }),
+        ),
+      ),
+    ),
+  );

package/src/create/look.ts

@@ -0,0 +1,140 @@
+/**
+ * How `adhere rules create` looks: Clack's rail, drawn by effect/cli's own
+ * prompts through their theme, with the wizard's own lines hung on the same
+ * rail, and a spinner, as `gum spin` draws one, while an agent works.
+ */
+import { highlightedLines } from "#workflows/format.ts";
+import { Status, clearingStatus } from "#services/Status.ts";
+import { Console, Duration, Effect, Fiber } from "effect";
+import { Prompt } from "effect/cli";
+
+/**
+ * The prompts' theme. Every row's text starts in the fourth column: after the
+ * prompt's symbol and two spaces, a select's pointer and its two-wide paging
+ * arrow, or the paging arrow and a space before a multi-select's checkbox.
+ */
+export const look: Partial<Prompt.Theme> = {
+  prefix: "◆ ",
+  tick: "◇ ",
+  pointer: "●",
+  arrowUp: "↑ ",
+  arrowDown: "↓ ",
+  pointerSmall: "",
+  ellipsis: "",
+  descriptionSeparator: "\n   ",
+  checkboxOn: "◼",
+  checkboxOff: "◻",
+};
+
+const columns = () => process.stderr.columns ?? 80;
+
+/** `text` wrapped to the terminal, each further line indented under a choice's title as the first is. */
+export const indented = (text: string) =>
+  Bun.wrapAnsi(text, Math.max(columns() - 4, 20)).replaceAll("\n", "\n   ");
+
+type Color = (theme: Prompt.Theme) => string;
+const muted: Color = (theme) => theme.mutedColor;
+const primary: Color = (theme) => theme.primaryColor;
+
+const paint = (theme: Prompt.Theme, text: string, color?: Color) =>
+  theme.colors && color !== undefined ? `${color(theme)}${text}\x1b[0m` : text;
+
+/**
+ * Prints `text` beside `symbol`, wrapped to the terminal, its further lines
+ * beside `bar`, in color when the theme has colors.
+ */
+const rail = (symbol: string, symbolColor: Color, text: string, textColor?: Color, bar = "│") =>
+  Effect.gen(function* () {
+    const theme = yield* Prompt.Theme;
+    const [first = "", ...rest] = Bun.wrapAnsi(text, Math.max(columns() - 3, 20), {
+      hard: true,
+      trim: false,
+    }).split("\n");
+    yield* Console.error(
+      [
+        `${paint(theme, symbol, symbolColor)}  ${paint(theme, first, textColor)}`,
+        ...rest.map((line) => `${paint(theme, bar, muted)}  ${paint(theme, line, textColor)}`),
+      ].join("\n"),
+    );
+  });
+
+export const intro = (text: string) => rail("┌", muted, text);
+export const line = (text: string) => rail("│", muted, text);
+export const note = (text: string) => rail("│", muted, text, muted);
+export const warn = (text: string) => rail("▲", () => "\x1b[33m", text);
+export const outro = (text: string) =>
+  rail("└", (theme) => theme.successColor, text, undefined, " ");
+
+/** A choice the agent made, not the user: what it chose, and why, muted beneath. */
+export const decided = (what: string, why: string) =>
+  rail("◇", (theme) => theme.successColor, what).pipe(Effect.andThen(note(why)));
+
+/** What the agent says about something it shows the user, accented and in italics. */
+export const said = (text: string) =>
+  rail("│", muted, text, (theme) => `${theme.primaryColor}\x1b[3m`);
+
+/**
+ * Prints lines `from` to `to` of a file's `lines`, numbered from 1, on the
+ * rail: the excerpt's lines `start` to `end` marked and highlighted as a
+ * report highlights code, and the rest muted. A line too long for the
+ * terminal is cut.
+ */
+export const excerpt = (
+  lines: ReadonlyArray<string>,
+  range: {
+    readonly from: number;
+    readonly to: number;
+    readonly start: number;
+    readonly end: number;
+  },
+) =>
+  Effect.gen(function* () {
+    const theme = yield* Prompt.Theme;
+    const width = String(range.to).length;
+    const room = Math.max(columns() - width - 8, 20);
+    const cut = lines.slice(range.from - 1, range.to).map((text) => {
+      const flat = text.replaceAll("\t", "  ");
+      return flat.length > room ? `${flat.slice(0, room - 1)}…` : flat;
+    });
+    // Highlighted together, so a comment or template opened above an excerpt line colors it.
+    const colored = highlightedLines(cut.join("\n"), theme.colors);
+    const rows = cut.map((text, index) => {
+      const number = String(range.from + index).padStart(width);
+      const inside = range.from + index >= range.start && range.from + index <= range.end;
+      const marker = inside ? paint(theme, "▌", primary) : " ";
+      const body = inside
+        ? `${paint(theme, number, muted)}  ${colored[index] ?? text}`
+        : paint(theme, `${number}  ${text}`, muted);
+      return `${paint(theme, "│", muted)}  ${marker} ${body}`;
+    });
+    yield* Console.error(rows.join("\n"));
+  });
+
+const frames = ["⣾", "⣽", "⣻", "⢿", "⡿", "⣟", "⣯", "⣷"];
+
+/**
+ * Runs `effect` beside a spinner and `text` on the status line, then leaves
+ * `text` on the rail with how long it took. Where the status line shows
+ * nothing, as off a terminal, only that last line is printed.
+ */
+export const spinning = <A, E, R>(text: string, effect: Effect.Effect<A, E, R>) =>
+  Effect.gen(function* () {
+    const theme = yield* Prompt.Theme;
+    const status = yield* Status;
+    let frame = 0;
+    yield* line("");
+    // The status line redraws at most every 100 ms.
+    const spinner = yield* Effect.forkChild(
+      Effect.suspend(() =>
+        status.show(
+          `${paint(theme, frames[frame++ % frames.length] ?? "", primary)}  ${paint(theme, `${text}…`, muted)}`,
+        ),
+      ).pipe(Effect.andThen(Effect.sleep("110 millis")), Effect.forever),
+    );
+    const [took, result] = yield* Effect.timed(effect).pipe(
+      Effect.ensuring(Fiber.interrupt(spinner)),
+      clearingStatus,
+    );
+    yield* note(`${text} · ${Math.max(1, Math.round(Duration.toSeconds(took)))}s`);
+    return result;
+  });