@drkmttr/adhere 0.21.2 → 0.23.0

package/src/cli.ts

@@ -34,11 +34,32 @@ 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 {
+  type CatalogMatch,
+  type InstallPicks,
+  type Source,
+  catalogOf,
+  cloned,
+  describeRules,
+  installSelected,
+  instructionPath,
+  listRules,
+  matchOf,
+  parseSource,
+  rulePath,
+} 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";
+import {
+  ReadmeUnavailable,
+  standardsRepoOf,
+  isSharedRepo,
+  originUrlAt,
+  refreshRemoteReadme,
+  refreshSharedReadme,
+} from "#readme.ts";
 import { globalRuleSet } from "#rules.ts";
 import { formatStrays, straysAmong } from "#wording.ts";
 import {
@@ -129,7 +150,7 @@ 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.",
+    "Include compiler-resolved symbols and declaration excerpts, and the bundled rules that declare them. Off by default.",
   ),
 );
 
@@ -389,7 +410,7 @@ export const validateLayer = (flags: Flags) =>
 
 /**
  * `adhere validate`: everything `lint` loads, then how each rule's wording
- * differs from the README's rule writing tips, then the linter check's tallies
+ * differs from the docs' rule writing tips, then the linter check's tallies
  * from lint, then Jev on whether any two rules that apply to the same files
  * contradict. Only a contradiction fails the run: the tips and the linter
  * check are advice. A config, rule file, or preset that does not decode
@@ -419,7 +440,7 @@ export const validateCommand = Command.make("validate", { preset }, () =>
   }),
 ).pipe(
   Command.withDescription(
-    "Load the config, rule files, and presets the way lint does, check each rule's wording against the README's rule writing tips, report the rules lint's linter check flags, then ask Jev whether any two rules that apply to the same files contradict each other.",
+    "Load the config, rule files, and presets the way lint does, check each rule's wording against the docs' rule writing tips, report the rules lint's linter check flags, then ask Jev whether any two rules that apply to the same files contradict each other.",
   ),
   Command.provide((input) => validateLayer({ presets: input.preset })),
 );
@@ -442,7 +463,7 @@ const shared = Flag.String("shared").pipe(
   ),
   Flag.optional,
   Flag.withDescription(
-    "Scaffold a repo of rules other repos copy with adhere install, named org/repo on GitHub: example rules, a README, a CI workflow that runs adhere validate, and an alchemy.run.ts that creates the repo, public unless you make it private when asked, and its TYPESAFE_API_KEY secret.",
+    "Scaffold a repo of instructions, rules, and a lint package other repos use, named org/repo on GitHub: example instructions and rules, a README, a CI workflow that runs adhere validate, and an alchemy.run.ts that creates the repo, public unless you make it private when asked, and its TYPESAFE_API_KEY secret.",
   ),
 );
 
@@ -471,7 +492,7 @@ export const initCommand = Command.make("init", { force, shared }, (input) =>
   }),
 ).pipe(
   Command.withDescription(
-    "Scaffold .adhere/config.ts and example Markdown rules, and add @drkmttr/adhere to devDependencies with the project's package manager.",
+    "Scaffold .adhere/config.ts, .adhere/tsconfig.json, and example Markdown rules, and add @drkmttr/adhere to devDependencies with the project's package manager.",
   ),
 );
 
@@ -481,7 +502,7 @@ const source = Argument.String("source").pipe(
     (spec) => `org/repo, then optionally a topic or rule and #ref, not ${spec}`,
   ),
   Argument.withDescription(
-    "A GitHub repo with rules in .adhere/rules/, as org/repo, optionally followed by a topic or a rule, as in org/repo/data/brand-ports, and by #branch or #tag.",
+    "A GitHub repo with instructions in .adhere/instructions/ and rules in .adhere/rules/, as org/repo, optionally followed by a topic or a rule, as in org/repo/data/brand-ports, and by #branch or #tag.",
   ),
 );
 
@@ -500,30 +521,136 @@ export const listCommand = Command.make("list", { source }, (input) =>
   ),
 );
 
-/** `adhere install org/repo`: another repo's rules, copied into this one's `.adhere/rules/`. */
+class InstallUnavailable extends Schema.TaggedError<InstallUnavailable>()("InstallUnavailable", {
+  message: Schema.String,
+}) {}
+
+/**
+ * What `adhere install` copies: one exact rule without asking, everything
+ * when `--all` is given, or what the user picks at a terminal. Without a
+ * terminal, a choice refuses and says what `--all` would copy and which exact
+ * rule can be named instead. A choice already installed is preselected, so
+ * running install again offers to bring it up to date, and deselecting it
+ * leaves it as it is.
+ */
+const choosePicks = Effect.fn("install.choosePicks")(function* (
+  source: Source,
+  match: CatalogMatch,
+  options: { readonly all: boolean; readonly root: string; readonly clone: string },
+) {
+  if (match.kind === "direct") {
+    return { instructions: [], rules: [match.rule.id] } satisfies InstallPicks;
+  }
+  if (options.all) {
+    return {
+      instructions: match.instructions,
+      rules: match.rules.map(({ id }) => id),
+    } satisfies InstallPicks;
+  }
+  const pinned = source.ref === undefined ? "" : `#${source.ref}`;
+  const stdio = yield* Stdio.Stdio;
+  if (!(yield* stdio.stdinIsTerminal) || !(yield* stdio.stdoutIsTerminal)) {
+    const [first] = match.rules;
+    const ids = [
+      ...match.instructions.map((file) => `instructions/${file}`),
+      ...match.rules.map(({ id }) => id),
+    ];
+    const spec = `${source.repo}${source.rule === "" ? "" : `/${source.rule}`}${pinned}`;
+    const exact =
+      first === undefined
+        ? ""
+        : `, or name one rule exactly, as in ${source.repo}/${first.id}${pinned}`;
+    return yield* new InstallUnavailable({
+      message: `adhere install ${spec}: no terminal to choose from. Pass --all to copy every match (${ids.join(", ")})${exact}.`,
+    });
+  }
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  type Pick =
+    | { readonly kind: "instruction"; readonly path: string }
+    | { readonly kind: "rule"; readonly id: string };
+  const instructionChoices = yield* Effect.forEach(match.instructions, (file) =>
+    fs.exists(path.join(options.root, instructionPath(source, file))).pipe(
+      Effect.orElseSucceed(() => false),
+      Effect.map((selected) => ({
+        title: `instructions/${file}`,
+        value: { kind: "instruction", path: file } as const,
+        selected,
+      })),
+    ),
+  );
+  const described = yield* describeRules(source, options.clone, match.rules);
+  const ruleChoices = yield* Effect.forEach(described, (rule) =>
+    fs.exists(path.join(options.root, rulePath(source, rule.id))).pipe(
+      Effect.orElseSucceed(() => false),
+      Effect.map((selected) => ({
+        title: rule.id,
+        description: rule.description,
+        value: { kind: "rule", id: rule.id } as const,
+        selected,
+      })),
+    ),
+  );
+  const picks: ReadonlyArray<Pick> = yield* Prompt.run(
+    Prompt.MultiSelect<Pick>({
+      message:
+        source.rule === ""
+          ? `What should adhere copy from ${source.repo}${pinned}?`
+          : `Which rules under ${source.repo}/${source.rule}${pinned} should adhere copy?`,
+      choices: [...instructionChoices, ...ruleChoices],
+    }),
+  );
+  return {
+    instructions: picks.flatMap((pick) => (pick.kind === "instruction" ? [pick.path] : [])),
+    rules: picks.flatMap((pick) => (pick.kind === "rule" ? [pick.id] : [])),
+  } satisfies InstallPicks;
+});
+
+/** `adhere install org/repo`: another repo's instructions and rules, copied into this one's `.adhere/`. */
 export const installCommand = Command.make(
   "install",
   {
     source,
     force: Flag.Boolean("force").pipe(
       Flag.withDefault(false),
-      Flag.withDescription("Replace rules already in .adhere/rules/, directory and all."),
+      Flag.withDescription(
+        "Replace instruction files and rules already in .adhere/, file by file and directory by directory.",
+      ),
+    ),
+    all: Flag.Boolean("all").pipe(
+      Flag.withDefault(false),
+      Flag.withDescription(
+        "Copy every instruction file and rule the source names, without asking. Needs no terminal.",
+      ),
     ),
   },
   (input) =>
-    Effect.gen(function* () {
-      const path = yield* Path.Path;
-      const result = yield* installRules(path.resolve(), input.source, { force: input.force });
-      yield* Console.log(
-        [
-          result.created.length > 0 ? `created: ${result.created.join(", ")}` : "created: none",
-          result.skipped.length > 0 ? `skipped: ${result.skipped.join(", ")}` : "skipped: none",
-        ].join("\n"),
-      );
-    }),
+    Effect.scoped(
+      Effect.gen(function* () {
+        const path = yield* Path.Path;
+        const root = path.resolve();
+        const clone = yield* cloned(input.source);
+        const catalog = yield* catalogOf(input.source, clone);
+        const match = yield* matchOf(input.source, catalog);
+        const picks = yield* choosePicks(input.source, match, {
+          all: input.all,
+          root,
+          clone,
+        });
+        const result = yield* installSelected(root, input.source, clone, picks, {
+          force: input.force,
+        });
+        yield* Console.log(
+          [
+            result.created.length > 0 ? `created: ${result.created.join(", ")}` : "created: none",
+            result.skipped.length > 0 ? `skipped: ${result.skipped.join(", ")}` : "skipped: none",
+          ].join("\n"),
+        );
+      }),
+    ),
 ).pipe(
   Command.withDescription(
-    "Copy the rules in a GitHub repo's .adhere/rules/, or one topic or rule of them, each its whole directory, into this repo's .adhere/rules/<org>/<repo>/. They are this repo's own rules from then on, to edit or keep in step by hand, and a copied RULE.ts runs whenever lint does. A rule already there is skipped unless --force.",
+    "Copy instruction files and rules from a GitHub repo's .adhere/ into this repo's .adhere/instructions/<org>/<repo>/ and .adhere/rules/<org>/<repo>/. At a terminal, choose which instruction files and rules to copy; name a topic for its rules, or name one rule exactly to copy it without asking. --all copies everything. Existing files are skipped unless --force.",
   ),
 );
 
@@ -645,13 +772,70 @@ const rulesCreateCommand = Command.make(
   (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.",
+    "Write a rule with a coding agent's help: it suggests whether the convention is a native oxlint rule (an id from adhere's catalog; unknown ids are rejected, with its exact option values and the config to print or enable in the shared repo), a mechanical rule (an oxlint JS plugin, approved before it runs and tested on Node 22 or newer; a failed test gets one repair and reapproval), or one adhere must judge. It then 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/ or .adhere/oxlint/; an organization rule is pushed to the shared repo on a branch for a pull request.",
+  ),
+);
+
+/** The shared rules repo to refresh instead of this checkout's, as `org/repo`. */
+const sharedRepo = Argument.String("repo").pipe(
+  Argument.filterMap(
+    (spec) => Option.fromNullishOr(/^[\w.-]+\/[\w.-]+$/.test(spec) ? spec : undefined),
+    (spec) => `org/repo, as on GitHub, not ${spec}`,
+  ),
+  Argument.optional,
+  Argument.withDescription(
+    "The shared rules repo to refresh, as org/repo, instead of this checkout or the org's standards repo this checkout's origin names.",
+  ),
+);
+
+/**
+ * `adhere rules readme [org/repo]`: refresh the managed index in a shared
+ * rules repo's README from the rules and lint config checked out there. In a
+ * shared repo it writes that README; otherwise it clones the GitHub repo named
+ * here, or the org's standards repo this checkout's origin names, and pushes the refreshed
+ * README on a review branch for a pull request.
+ */
+const rulesReadmeCommand = Command.make("readme", { repo: sharedRepo }, ({ repo }) =>
+  Effect.gen(function* () {
+    const path = yield* Path.Path;
+    const root = path.resolve();
+    const named = Option.isSome(repo) ? repo.value : undefined;
+    if (named === undefined && (yield* isSharedRepo(root))) {
+      const refreshed = yield* refreshSharedReadme(root);
+      yield* Console.log(refreshed.message);
+      return;
+    }
+    const origin = named === undefined ? yield* originUrlAt(root) : undefined;
+    // A consumer repo's shared rules live in its org's standards repo, never in the repo itself.
+    const target = named ?? (origin === undefined ? undefined : standardsRepoOf(origin));
+    if (target === undefined) {
+      return yield* ReadmeUnavailable.make({
+        message:
+          origin === undefined
+            ? `${root} is not a shared rules repo, and git names no origin here, so there is no README to refresh. Run this in the shared repo, name it as adhere rules readme org/repo, or add a GitHub origin.`
+            : `${root} is not a shared rules repo, and its origin ${origin} is not a GitHub repo. Run this in the shared repo, or name one: adhere rules readme org/repo.`,
+      });
+    }
+    const refreshed = yield* refreshRemoteReadme(target);
+    yield* Console.log(
+      refreshed.branch === undefined
+        ? `${refreshed.message}\nNo change, so nothing was pushed.`
+        : [
+            refreshed.message,
+            `Pushed ${refreshed.branch} to ${refreshed.repo}.`,
+            `Open the pull request: https://github.com/${refreshed.repo}/compare/${refreshed.branch}?expand=1`,
+          ].join("\n"),
+    );
+  }).pipe(Effect.provide(statusLayer)),
+).pipe(
+  Command.withDescription(
+    "Refresh the managed index in a shared rules repo's README from .adhere/rules/ and oxlint/rules.json: each rule's link and description, each enabled native Oxlint setting, and each custom plugin's enabled rules. In the shared repo it writes that README. Elsewhere it refreshes the GitHub repo named as org/repo, or the org's standards repo this checkout's origin names, from a clone, pushes README.md alone on a review branch, and prints the pull request link; a current README pushes nothing. It preserves the rest of the README and refuses malformed markers.",
   ),
 );
 
 export const rulesCommand = Command.make("rules").pipe(
   Command.withDescription("Work on this repo's rules."),
-  Command.withSubcommands([rulesCreateCommand]),
+  Command.withSubcommands([rulesCreateCommand, rulesReadmeCommand]),
 );
 
 export const postinstallCommand = Command.make("postinstall", {}, () =>
@@ -659,13 +843,20 @@ export const postinstallCommand = Command.make("postinstall", {}, () =>
     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."));
+).pipe(
+  Command.withDescription(
+    "Render instruction files recursively 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."),
   Command.withExamples([
-    { command: "adhere init", description: "Scaffold .adhere/config.ts and two example rules" },
+    {
+      command: "adhere init",
+      description: "Scaffold config, tsconfig, and two example rules",
+    },
     {
       command: "adhere validate",
       description: "Check the rules' wording, and ask Jev whether any contradict",
@@ -674,7 +865,7 @@ export const cli = Command.make("adhere").pipe(
     { command: "adhere lint", description: "Audit the working directory" },
     {
       command: "adhere install org/repo",
-      description: "Copy another repo's .adhere/rules/ into this one",
+      description: "Copy another repo's instructions and rules into this one",
     },
     {
       command: "adhere lint --preset effect",

package/src/config.ts

@@ -57,8 +57,9 @@ 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
+ * its rules. A rule may also declare the reads it needs, which tells the run
+ * what would help without enabling any of it. 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. `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
@@ -116,6 +117,10 @@ export const Rule = Schema.Struct({
     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.",
   }),
+  reads: Schema.optionalKey(Reads).annotate({
+    description:
+      "Context the rule needs, such as `dependents` or `symbols`. This declares what would help; the config's `reads` and `typeAware` still decide what this run enables. A project's rule that declares a read they do not enable warns that it may be less accurate until enabled; a bundled preset rule that declares `symbols` or `references` is left out unless `typeAware` is on.",
+  }),
   appendState: Schema.optionalKey(
     Schema.declare((value: unknown): value is AppendState => typeof value === "function", {
       expected: "a function",
@@ -225,7 +230,7 @@ export const AdhereConfig = Schema.Struct({
   }),
   typeAware: Schema.optionalKey(Schema.Boolean).annotate({
     description:
-      "Include both compiler-resolved symbols and declaration excerpts. Defaults to false.",
+      "Include both compiler-resolved symbols and declaration excerpts. Defaults to false. Bundled preset rules that declare either run only with it on; a project's own rule still runs and warns.",
   }),
   maxSymbolLength: Schema.optionalKey(Schema.Natural).annotate({
     description: "Maximum characters of each symbol's complete resolved content. Defaults to 256.",
@@ -262,6 +267,8 @@ export const AdhereConfig = Schema.Struct({
 export const ADHERE_DIRECTORY = ".adhere";
 /** Where a repo keeps its rules by default, one to a directory: `<id>/RULE.md` or `<id>/RULE.ts`. */
 export const RULES_DIRECTORY = `${ADHERE_DIRECTORY}/rules`;
+/** Where a repo keeps the Markdown instruction files postinstall renders into AGENTS.md. */
+export const INSTRUCTIONS_DIRECTORY = `${ADHERE_DIRECTORY}/instructions`;
 export const CACHE_DIRECTORY = `${ADHERE_DIRECTORY}/cache`;
 /** Where a config may live, relative to the working directory. Exactly one may exist. */
 export const CONFIG_FILES = [
@@ -406,6 +413,22 @@ export const presetsOf = (
   });
 };
 
+/**
+ * Whether the run enables the compiler's native reads: the command line
+ * replaces the config's opt-in, which defaults to off.
+ */
+export const typeAwareOf = (
+  config: Pick<typeof AdhereConfig.Type, "typeAware">,
+  flags: Flags,
+): boolean => flags.typeAware ?? config.typeAware ?? false;
+
+/**
+ * Whether a rule declares a read only `typeAware` enables, so a run without
+ * it cannot judge the rule as it was written.
+ */
+export const declaresNativeReads = (rule: Pick<Rule, "reads">): boolean =>
+  (rule.reads ?? []).some((read) => read === "symbols" || read === "references");
+
 /**
  * Precedence, highest first: command line, config file, presets in order
  * (a later preset wins), then the defaults. A config rule replaces a preset
@@ -422,7 +445,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;
+  const typeAware = typeAwareOf(config, flags);
   return {
     model: config.provider?.model ?? config.model ?? last("model") ?? DEFAULT_MODEL,
     ...(config.provider === undefined ? {} : { provider: config.provider }),