@drkmttr/adhere 0.21.2 → 0.24.0

package/src/create/wizard.ts

@@ -11,33 +11,34 @@
 import { CONFIG_FILES, DEFAULT_READS } from "#config.ts";
 import { AGENTS, type Agent, installedAgents, run } from "#create/agents.ts";
 import {
-  type Candidate,
-  Candidates,
-  type Reviewed,
   RuleNotCreated,
   Shape,
+  adhereRevisionPrompt,
   asking,
   askingFor,
-  examplesPrompt,
   shapePrompt,
   unfenced,
   writePrompt,
 } from "#create/ask.ts";
+import { reviewedInRepository } from "#create/examples.ts";
+import { createOxlintRule } from "#create/oxlint.ts";
+import { trialAndReview, trialStatus, trialWriteSuffix } from "#create/trial-review.ts";
+import { oxlintRule } from "#oxlint/catalog.ts";
 import {
   decided,
-  excerpt,
   indented,
   intro,
   line,
   look,
   note,
   outro,
-  said,
+  renderMarkdown,
   spinning,
   warn,
 } from "#create/look.ts";
 import { cloned } from "#install.ts";
-import { parseRuleMarkdown } from "#markdown.ts";
+import { parseRuleMarkdown, ruleBodyOf } from "#markdown.ts";
+import { isSharedRepo, refreshIndexIfShared, refreshReadme, validateReadme } from "#readme.ts";
 import { importRule } from "#rules.ts";
 import { findConfigFile, loadConfigFile } from "#services/AdhereConfig.ts";
 import { adhereConfigDirectory } from "#services/Credentials.ts";
@@ -112,58 +113,6 @@ const failed = (cause: unknown) =>
 const git = (cwd: string, args: ReadonlyArray<string>) =>
   Effect.tryPromise({ try: () => run("git", args, cwd, ""), catch: failed });
 
-/**
- * Shows the user each excerpt the agent found, read from the file itself with
- * three lines either side, and asks whether it breaks the rule. An excerpt
- * that does not match the repo is left out.
- */
-const review = (agent: Agent, root: string, candidates: ReadonlyArray<Candidate>) =>
-  Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    const reviewed: Array<Reviewed> = [];
-    let missing = 0;
-    for (const [index, candidate] of candidates.entries()) {
-      const file = path.resolve(root, candidate.file);
-      const where = path.relative(root, file);
-      const text = where.startsWith("..")
-        ? Option.none()
-        : yield* fs.readFileString(file).pipe(Effect.option);
-      const lines = Option.getOrElse(text, () => "").split("\n");
-      const start = candidate.startLine;
-      if (Option.isNone(text) || start < 1 || start > lines.length) {
-        missing++;
-        continue;
-      }
-      const end = Math.min(Math.max(candidate.endLine, start), start + 14, lines.length);
-      const at = `${where}:${start === end ? start : `${start}-${end}`}`;
-      yield* line("");
-      yield* line(`${at} (${index + 1} of ${candidates.length})`);
-      yield* excerpt(lines, {
-        from: Math.max(1, start - 3),
-        to: Math.min(lines.length, end + 3),
-        start,
-        end,
-      });
-      yield* said(
-        `${agent}: ${candidate.violation ? "breaks it" : "follows it"}. ${candidate.reason}`,
-      );
-      const violation = yield* Prompt.run(
-        Prompt.Confirm({ message: "Is this a violation?", initial: candidate.violation }),
-      );
-      reviewed.push({
-        where: at,
-        code: lines.slice(start - 1, end).join("\n"),
-        violation,
-        agreed: violation === candidate.violation,
-      });
-    }
-    if (missing > 0) {
-      yield* note(`Left out ${missing} excerpt${missing === 1 ? "" : "s"} not found in the repo.`);
-    }
-    return reviewed;
-  });
-
 /**
  * What adhere can say of a draft without running it: for a RULE.md, what
  * `validate` would; for a RULE.ts, whether it parses and has a default export.
@@ -184,11 +133,31 @@ const problemsOf = (text: string, file: string, format: Shape["format"]) =>
         Effect.catch((message) => Effect.succeed([`It does not parse: ${message}`])),
       );
 
+/**
+ * Shows a draft as the user reads it: a RULE.md rendered from Markdown with
+ * its frontmatter and source intact, a RULE.ts as written, either on the rail.
+ * Only the preview is rendered; the draft itself stays raw for the agent, the
+ * trial, and the file.
+ */
+const showDraft = (text: string, format: Shape["format"]) =>
+  Effect.gen(function* () {
+    if (format !== "markdown") return yield* line(`\n${text}\n`);
+    const body = ruleBodyOf(text);
+    const frontmatter = text.slice(0, text.length - body.length);
+    yield* line(`\n${frontmatter}${yield* renderMarkdown(body)}\n`);
+  });
+
+/** A RULE.ts that imported, with its wording strays, or one that did not import. */
+export type LoadedDraft =
+  | { readonly _tag: "Loaded"; readonly warnings: ReadonlyArray<string> }
+  | { readonly _tag: "Unavailable"; readonly problems: ReadonlyArray<string> };
+
 /**
  * What `validate` would say of a RULE.ts the user has approved: imported from
- * a temporary directory, so its code runs.
+ * a temporary directory, so its code runs. A wording stray is a warning about
+ * a rule that still runs; only a failure to import makes it untriallable.
  */
-const loadedProblems = (text: string, shown: string) =>
+export const loadedDraft = (text: string, shown: string) =>
   Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
@@ -198,16 +167,45 @@ const loadedProblems = (text: string, shown: string) =>
     );
     yield* fs.writeFileString(file, text);
     return yield* importRule(file).pipe(
-      Effect.map((rule) => strayingOf(rule).map(sentenceOf)),
-      Effect.catchTag("ConfigUnavailable", ({ message }) =>
-        Effect.succeed([message.replaceAll(file, shown)]),
+      Effect.map((rule): LoadedDraft => ({
+        _tag: "Loaded",
+        warnings: strayingOf(rule).map(sentenceOf),
+      })),
+      Effect.catchTag("ConfigUnavailable", ({ message }): Effect.Effect<LoadedDraft> =>
+        Effect.succeed({
+          _tag: "Unavailable",
+          problems: [message.replaceAll(file, shown)],
+        }),
       ),
     );
   });
 
+/**
+ * Whether the trial may import and run the draft: a RULE.md has no code, while
+ * a RULE.ts is imported only after the user approves it.
+ */
+const approveDraft = (text: string, format: Shape["format"], shown: string) =>
+  Effect.gen(function* () {
+    if (format === "markdown") return { _tag: "Approved", draft: text } as const;
+    const run = yield* Prompt.run(
+      Prompt.Confirm({
+        message: "adhere will import this RULE.ts and run its code to trial it. Run it?",
+        initial: true,
+      }),
+    );
+    if (!run) return { _tag: "Declined" } as const;
+    const loaded = yield* loadedDraft(text, shown);
+    if (loaded._tag === "Unavailable") {
+      return { _tag: "Unavailable", problems: loaded.problems } as const;
+    }
+    for (const warning of loaded.warnings) yield* warn(warning);
+    return { _tag: "Approved", draft: text } as const;
+  });
+
 /**
  * The config settings the rule needs that `config` lacks, as they would be
- * written in it. Reads and type awareness are config-wide, not per rule.
+ * written in it. The rule declares its reads, but the config still enables
+ * them and type awareness.
  */
 const settingsFor = (
   shape: Shape,
@@ -249,14 +247,23 @@ export const createRule = Effect.fn("createRule")(
       : yield* Prompt.run(Prompt.String({ message: "What should the rule enforce?" }));
 
     const shape = yield* askingFor(agent, "how to shape it", root, shapePrompt(idea), Shape);
-    if (shape.linter !== null) {
-      const anyway = yield* Prompt.run(
-        Prompt.Confirm({
-          message: `A linter could check this: ${shape.linter}. Write an adhere rule anyway?`,
-          initial: false,
+    const native = shape.linter === null ? undefined : oxlintRule(shape.linter);
+    if (native !== undefined) {
+      return yield* createOxlintRule({ agent, idea, shape, root, shared });
+    }
+    if (shape.mechanical && !shape.typeAware) {
+      const approach = yield* Prompt.run(
+        Prompt.Select({
+          message: "A custom oxlint JS plugin can check this. Which do you want?",
+          choices: [
+            { title: "Write an oxlint plugin", value: "plugin" as const },
+            { title: "Write an adhere rule", value: "adhere" as const },
+          ],
         }),
       );
-      if (!anyway) return yield* outro("Nothing written.");
+      if (approach === "plugin") {
+        return yield* createOxlintRule({ agent, idea, shape, root, shared });
+      }
     }
     const ruleFile = shape.format === "typescript" ? "RULE.ts" : "RULE.md";
     yield* decided(`A ${ruleFile}`, shape.formatReason);
@@ -327,20 +334,7 @@ export const createRule = Effect.fn("createRule")(
           }),
         );
 
-    // Excerpts are optional: an agent that cannot search the repo, such as codex
-    // without its sandbox, leaves the rule's examples to the draft.
-    const found = yield* askingFor(
-      agent,
-      "for code to judge",
-      root,
-      examplesPrompt(idea, id),
-      Candidates,
-    ).pipe(
-      Effect.catch(({ message }) =>
-        warn(`No code from the repo: ${message}`).pipe(Effect.as({ candidates: [] })),
-      ),
-    );
-    const reviewed = yield* review(agent, root, found.candidates);
+    const reviewed = yield* reviewedInRepository(agent, root, idea, id);
 
     const file = path.join(rules, id, ruleFile);
     const branch = `adhere/${id}`;
@@ -360,31 +354,66 @@ export const createRule = Effect.fn("createRule")(
           );
     const problems = yield* problemsOf(text, file, shape.format);
 
-    yield* line(`\n${text}\n`);
+    yield* showDraft(text, shape.format);
     for (const problem of problems) yield* warn(problem);
+    const shown = path.relative(root, file);
+    const outcome = yield* trialAndReview({
+      agent,
+      root,
+      id,
+      draft: text,
+      toDraft: (source) => ({ kind: "adhere", id, format: shape.format, source }),
+      approve: (source) => approveDraft(source, shape.format, shown),
+      revise: (source, evidence) =>
+        Effect.gen(function* () {
+          const revised = unfenced(
+            yield* asking(
+              agent,
+              "to revise the rule",
+              root,
+              adhereRevisionPrompt(idea, id, shape, source, evidence),
+            ),
+          );
+          for (const problem of yield* problemsOf(revised, file, shape.format)) {
+            yield* warn(problem);
+          }
+          return revised;
+        }),
+      show: (source) => showDraft(source, shape.format),
+    });
+    if (outcome._tag === "Cancelled") return yield* outro("Nothing written.");
+    const finalText = outcome.draft;
+    const finalProblems = yield* problemsOf(finalText, file, shape.format);
+    if (finalText !== text) {
+      yield* showDraft(finalText, shape.format);
+      for (const problem of finalProblems) yield* warn(problem);
+    }
     const write = yield* Prompt.run(
       Prompt.Confirm({
         message:
-          scope === "project"
+          (scope === "project"
             ? `Write ${path.relative(root, file)}?`
-            : `Push it to ${shared} on the branch ${branch}?`,
-        initial: problems.length === 0,
+            : `Push it to ${shared} on the branch ${branch}?`) + trialWriteSuffix(outcome),
+        initial: finalProblems.length === 0 && outcome._tag === "Accepted",
       }),
     );
     if (!write) return yield* outro("Nothing written.");
     // A RULE.ts is only imported, and its code run, once the user has read it.
     if (shape.format === "typescript") {
-      const loaded = yield* loadedProblems(text, path.relative(root, file));
-      for (const problem of loaded) yield* warn(problem);
+      const loaded = yield* loadedDraft(finalText, path.relative(root, file));
+      const problems = loaded._tag === "Loaded" ? loaded.warnings : loaded.problems;
+      for (const problem of problems) yield* warn(problem);
       if (
-        loaded.length > 0 &&
+        problems.length > 0 &&
         !(yield* Prompt.run(Prompt.Confirm({ message: "Write it anyway?", initial: false })))
       ) {
         return yield* outro("Nothing written.");
       }
     }
+    const sharedHere = scope === "project" ? yield* isSharedRepo(root) : false;
+    if (sharedHere) yield* validateReadme(root);
     yield* fs.makeDirectory(path.dirname(file), { recursive: true });
-    yield* fs.writeFileString(file, `${text}\n`);
+    yield* fs.writeFileString(file, `${finalText}\n`);
 
     if (scope === "project") {
       const configFile = yield* findConfigFile(root).pipe(Effect.orElseSucceed(() => undefined));
@@ -400,8 +429,9 @@ export const createRule = Effect.fn("createRule")(
           `${id} needs ${needed.join(" and ")} in ${configFile ?? CONFIG_FILES[0]}${shape.typeAware ? " (or lint --type-aware)" : ""}. Until then, lint judges it without that context.`,
         );
       }
+      const refreshed = sharedHere ? yield* refreshReadme(root) : undefined;
       return yield* outro(
-        `Wrote ${path.relative(root, file)}.\nRun adhere validate to check it against your other rules.`,
+        `Wrote ${path.relative(root, file)}.\n${trialStatus(outcome)}\n${refreshed === undefined ? "" : `${refreshed.message}\n`}Run adhere validate to check it against your other rules.`,
       );
     }
     const needed = settingsFor(shape, {});
@@ -409,8 +439,13 @@ export const createRule = Effect.fn("createRule")(
       needed.length === 0
         ? []
         : [`Repos that install it need ${needed.join(" and ")} in their adhere config.`];
+    // A shared repo's index joins the rule in one commit and one pull request;
+    // a legacy rules-only repo has no index to refresh.
+    const indexed = yield* refreshIndexIfShared(repo);
     yield* git(repo, ["switch", "--quiet", "--create", branch]);
-    yield* git(repo, ["add", "--", path.relative(repo, file)]);
+    const staged = [path.relative(repo, file)];
+    if (indexed) staged.push("README.md");
+    yield* git(repo, ["add", "--", ...staged]);
     yield* git(repo, [
       "commit",
       "--quiet",
@@ -422,6 +457,7 @@ export const createRule = Effect.fn("createRule")(
     yield* outro(
       [
         `Pushed ${branch} to ${shared}.`,
+        trialStatus(outcome),
         ...needs,
         `Open the pull request: https://github.com/${shared}/compare/${branch}?expand=1`,
       ].join("\n"),

package/src/filters.ts

@@ -0,0 +1,86 @@
+import type { Rule, RuleFilter } from "#config.ts";
+import { matchesGlob } from "node:path";
+
+/** A repository path as every matcher here reads it: `/`-separated, without a leading `./`. */
+export const normalizedPath = (path: string): string =>
+  path.replaceAll("\\", "/").replace(/^\.\//, "");
+
+interface CompiledSide {
+  readonly paths: ReadonlyArray<string>;
+  readonly content: ReadonlyArray<RegExp>;
+}
+
+interface CompiledFilters {
+  readonly include: CompiledSide;
+  readonly exclude: CompiledSide;
+}
+
+const compiled = new WeakMap<Pick<Rule, "include" | "exclude">, CompiledFilters>();
+
+const compileSide = (filter: RuleFilter | undefined): CompiledSide => ({
+  paths: (filter?.paths ?? []).map(normalizedPath),
+  // Validated when the rule was decoded, so this cannot throw here.
+  content: (filter?.content ?? []).map((source) => new RegExp(source)),
+});
+
+/**
+ * A rule's filters, compiled once per rule: its globs with `/` separators, and
+ * its content patterns as regular expressions. Both sides are kept, since
+ * `include` and `exclude` differ only in what a match means.
+ */
+export const compiledFiltersOf = (rule: Pick<Rule, "include" | "exclude">): CompiledFilters => {
+  const held = compiled.get(rule);
+  if (held !== undefined) return held;
+  const filters = { include: compileSide(rule.include), exclude: compileSide(rule.exclude) };
+  compiled.set(rule, filters);
+  return filters;
+};
+
+/** Whether a rule has either filter, so a run can leave unfiltered rules untouched. */
+export const hasFilters = (rule: Pick<Rule, "include" | "exclude">): boolean =>
+  rule.include !== undefined || rule.exclude !== undefined;
+
+/** Whether a rule's content patterns, if any, need the file's text to decide. */
+export const filtersNeedText = (rule: Pick<Rule, "include" | "exclude">): boolean => {
+  const { include, exclude } = compiledFiltersOf(rule);
+  return include.content.length > 0 || exclude.content.length > 0;
+};
+
+const matchesAnyPath = (path: string, patterns: ReadonlyArray<string>): boolean =>
+  patterns.some((pattern) => matchesGlob(path, pattern));
+
+/**
+ * Whether a repository-relative path passes a rule's path filters alone: an
+ * `include.paths` list must match when it has entries, and any
+ * `exclude.paths` match drops the file even when it matched.
+ */
+export const pathsPass = (rule: Rule, relativePath: string): boolean => {
+  const { include, exclude } = compiledFiltersOf(rule);
+  const path = normalizedPath(relativePath);
+  return (
+    (include.paths.length === 0 || matchesAnyPath(path, include.paths)) &&
+    !(exclude.paths.length > 0 && matchesAnyPath(path, exclude.paths))
+  );
+};
+
+/**
+ * Whether a rule's content filters allow `text`, the file as written: any
+ * `include` entry matches, and no `exclude` entry does. A path fix for one
+ * file cannot change between planning and execution, so reloading a file
+ * rechecks only this half.
+ */
+export const contentPasses = (rule: Rule, text: string): boolean => {
+  const { include, exclude } = compiledFiltersOf(rule);
+  return (
+    (include.content.length === 0 || include.content.some((pattern) => pattern.test(text))) &&
+    !(exclude.content.length > 0 && exclude.content.some((pattern) => pattern.test(text)))
+  );
+};
+
+/**
+ * Whether a rule applies to a file at a repository-relative path whose text
+ * is `text`: `pathsPass` and `contentPasses`. An `include` category that is
+ * set must match, while a match in any `exclude` category drops the file.
+ */
+export const ruleAppliesTo = (rule: Rule, relativePath: string, text: string): boolean =>
+  pathsPass(rule, relativePath) && contentPasses(rule, text);