@drkmttr/adhere 0.13.1 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.13.1",
+  "version": "0.14.0",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "license": "MIT",
@@ -68,10 +68,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.13.1",
-    "@drkmttr/adhere-darwin-x64": "0.13.1",
-    "@drkmttr/adhere-linux-arm64": "0.13.1",
-    "@drkmttr/adhere-linux-x64": "0.13.1",
-    "@drkmttr/adhere-win32-x64": "0.13.1"
+    "@drkmttr/adhere-darwin-arm64": "0.14.0",
+    "@drkmttr/adhere-darwin-x64": "0.14.0",
+    "@drkmttr/adhere-linux-arm64": "0.14.0",
+    "@drkmttr/adhere-linux-x64": "0.14.0",
+    "@drkmttr/adhere-win32-x64": "0.14.0"
   }
 }

package/skills/adhere/SKILL.md

@@ -53,7 +53,8 @@ config in `.adhere/` are not rules.
 description: A port must be a branded, range-checked integer, never a bare number.
 ---
 
-Prose here renders on GitHub and is ignored.
+Prose here is the rule's details: Jev reads it after the description. Say why
+the rule holds, or where it does not apply.
 
 ## Must
 
@@ -88,6 +89,9 @@ How to word a rule, from adhere's evals:
 - One pattern per rule. Two in one block blur the probability.
 - A heading names its code only when it is the word alone: `## Never`, not
   `## Never do this`. A fence tagged `ts never` names its code itself.
+- Prose outside the code is sent to Jev with the description, so keep it about
+  the rule: why it holds, or where it does not apply. A note for the people who
+  maintain the rule, rather than for judging code, belongs elsewhere.
 
 Front matter besides `description`, all optional:
 
@@ -102,12 +106,14 @@ Front matter besides `description`, all optional:
   one line, scope a rule without widening its description: a finding stands
   only when Jev says the code that breaks the rule is as every `appliesTo`
   describes and as no `excludeIf` does.
-- `includeWorkspacePackages: true` gives Jev `workspacePackages` beside the
-  code: each of the repository's own packages, by name, with its directory,
-  read from the root `package.json`'s `workspaces` or `pnpm-workspace.yaml`.
-  Use it for a rule that turns on whether an import is of the repository's
-  own package or an installed one, and name `workspacePackages` in the
-  description. The rule costs a request of its own per file, and a changed
+- `reads: ["workspacePackages"]`, a JSON array on one line, names what Jev
+  reads for the rule beside the code, each under that name. There is one so
+  far, `workspacePackages`: each of the repository's own packages, by name,
+  with its directory, read from the root `package.json`'s `workspaces` or
+  `pnpm-workspace.yaml`. Use it for a rule that turns on whether an import is
+  of the repository's own package or an installed one, and name
+  `workspacePackages` in the description. A name adhere does not have refuses
+  the run. The rule costs a request of its own per file, and a changed
   workspace judges it again.
 
 A rule's directory can hold a `RULE.ts` instead, which default-exports

package/skills/adhere-setup/SKILL.md

@@ -38,8 +38,15 @@ wherever this skill says `adhere`, run it the manager's way, as in
 With pnpm, at a workspace root, add `--ignore-workspace-root-check`.
 
 In a repo without a `package.json`, use the `adhere` on PATH (`adhere
---version`), or **Ask** before installing it globally with the manager the
-user has, such as `bun add --global @drkmttr/adhere`.
+--version`), or **Ask** before installing the executable from the latest
+release (`adhere-Windows-x86_64.exe` on Windows), which needs no Node or
+package manager:
+
+```sh
+curl -fsSL --create-dirs -o ~/.local/bin/adhere \
+  https://github.com/darkmatter/adhere/releases/latest/download/adhere-$(uname -s)-$(uname -m)
+chmod +x ~/.local/bin/adhere
+```
 
 Validate and lint need a TypeSafe AI API key: `TYPESAFE_API_KEY`, or one saved
 by `adhere login`, which the user runs; never ask for the key in chat or print
@@ -205,9 +212,18 @@ jobs:
 
 Pin the versions the repo already uses: bun's `bun-version`, Node's
 `node-version` from `.nvmrc` or `engines`, and pnpm's from `packageManager`,
-which `pnpm/action-setup` reads. In a repo without a `package.json`, set up
-the manager the user has and run adhere at the version they ran locally, as
-in `bunx @drkmttr/adhere@0.11.0 lint --yes`.
+which `pnpm/action-setup` reads. In a repo without a `package.json`, skip the
+setup and install, and fetch the executable at the version the user ran
+locally:
+
+```yaml
+- run: |
+    curl -fsSL -o "$RUNNER_TEMP/adhere" https://github.com/darkmatter/adhere/releases/download/v0.14.0/adhere-$(uname -s)-$(uname -m)
+    chmod +x "$RUNNER_TEMP/adhere"
+    "$RUNNER_TEMP/adhere" lint --yes
+  env:
+    TYPESAFE_API_KEY: ${{ secrets.TYPESAFE_API_KEY }}
+```
 
 Add `--deny-warnings` if the user wants warnings to fail the job too. Match
 the branch to the repo's default branch. For another CI system, write the

package/src/config.ts

@@ -32,6 +32,15 @@ export type AppendState = (
   bun: BunApi,
 ) => Readonly<Record<string, unknown>> | Promise<Readonly<Record<string, unknown>>>;
 
+/**
+ * What a rule can have Jev read beside the code, each by the name of the key
+ * the state carries it under, which the rule's description can name in
+ * backticks. `workspacePackages` is the workspace's packages: each one's name
+ * with its directory, so a rule can tell an import of the repository's own
+ * package from an installed one's.
+ */
+export const Reads = Schema.Array(Schema.Literals(["workspacePackages"]));
+
 /**
  * A rule's examples, named in RFC 2119's words, which Jev reads as written. A
  * requirement shows code that `must` be written and code that must `never`
@@ -40,6 +49,13 @@ export type AppendState = (
  */
 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),
@@ -68,13 +84,11 @@ const RuleFields = Schema.Struct({
    */
   excludeIf: Schema.optionalKey(Schema.Array(Schema.String)),
   /**
-   * Whether Jev reads, beside the code, the workspace's packages as
-   * `workspacePackages`: each one's name with its directory, so the rule can
-   * tell an import of the repository's own package from an installed one's.
-   * The rule's questions go in requests of their own, and a change to the
-   * packages judges it again.
+   * What Jev reads for the rule beside the code, by name (see `Reads`). The
+   * rule's questions go in requests of their own, so only they read it, and
+   * a change to what is read judges the rule again.
    */
-  includeWorkspacePackages: Schema.optionalKey(Schema.Boolean),
+  reads: Schema.optionalKey(Reads),
   /**
    * 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
@@ -306,8 +320,8 @@ export interface ResolvedConfig {
   readonly includeComments?: boolean;
   /**
    * The workspace's packages, each name with its directory from the working
-   * directory, read from its manifests on every run, when a rule asks for
-   * them with `includeWorkspacePackages`.
+   * directory, read from its manifests on every run, when a rule's `reads`
+   * names them.
    */
   readonly workspacePackages?: Readonly<Record<string, string>>;
 }

package/src/init.ts

@@ -68,9 +68,8 @@ description: A file should be small and focused, with one primary responsibility
 threshold: 0.8
 ---
 
-A guideline, so its description and its headings say should and should not. A
-rule that must hold says must and never instead, as name-domain-actions does.
-Use this rule as a template for repository-specific conventions.
+Why: a file that does one thing is easier to find, read, and change. A helper
+that serves only that thing belongs in the same file.
 
 ## Should
 
@@ -93,6 +92,9 @@ description: A function must be named after the domain action it performs, never
 threshold: 0.8
 ---
 
+Why: a name like \`handle\` or \`process\` says nothing about what the function
+does, so every caller has to open it to find out.
+
 ## Must
 
 \`\`\`ts
@@ -104,9 +106,6 @@ export const loadCustomerProfile = (customerId: CustomerId) =>
 
 ## Never
 
-The code under Never shows what a violation looks like. It is optional, and a
-rule can have it without the code under Must.
-
 \`\`\`ts
 export const handle = (id: string) =>
   Effect.gen(function* () {

package/src/markdown.ts

@@ -1,4 +1,4 @@
-import { ConfigUnavailable, type Example, type Rule } from "#config.ts";
+import { ConfigUnavailable, type Example, Reads, type Rule } from "#config.ts";
 import { Effect, Schema } from "effect";
 
 /**
@@ -8,7 +8,7 @@ import { Effect, Schema } from "effect";
  *     description: One sentence saying what code must be, or never be.
  *     threshold: 0.8
  *     ---
- *     Any prose, rendered on GitHub and ignored by adhere.
+ *     Any prose, which Jev reads after the description, as the rule's details.
  *
  *     ## Must
  *
@@ -34,6 +34,8 @@ import { Effect, Schema } from "effect";
  * `warning` reports the rule's findings as warnings, which do not fail a run.
  * `appliesTo` and `excludeIf`, the rule's scope, are JSON arrays of strings on
  * one line, as in `excludeIf: ["a type that mirrors a third-party format"]`.
+ * So is `reads`, of the names of what Jev reads for the rule beside the code,
+ * as in `reads: ["workspacePackages"]`.
  */
 const Matchers = Schema.fromJsonString(Schema.Array(Schema.String));
 
@@ -44,7 +46,7 @@ const FrontMatter = Schema.Struct({
   level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
   appliesTo: Schema.optionalKey(Matchers),
   excludeIf: Schema.optionalKey(Matchers),
-  includeWorkspacePackages: Schema.optionalKey(Schema.Literals(["true", "false"])),
+  reads: Schema.optionalKey(Schema.fromJsonString(Reads)),
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -149,6 +151,24 @@ const fencesOf = (body: string): ReadonlyArray<Fence> => {
 const nonEmpty = (code: string | undefined): string | undefined =>
   code === undefined || code.length === 0 ? undefined : code;
 
+/**
+ * The body's prose: what is left outside its fences and the headings that
+ * name their code, which Jev reads after the description. A body without a
+ * fence is all code, so it has none.
+ */
+const detailsOf = (body: string): string | undefined =>
+  fencesOf(body).length === 0
+    ? undefined
+    : nonEmpty(
+        body
+          .replace(FENCE, "")
+          .replace(HEADING, (line, _level, text: string | undefined) =>
+            headingWordOf(text ?? "") === undefined ? line : "",
+          )
+          .replace(/\n{3,}/g, "\n\n")
+          .trim(),
+      );
+
 type Code = Pick<Rule, "must" | "never" | "should" | "shouldNot">;
 
 /**
@@ -207,12 +227,6 @@ export const parseRuleMarkdown = (
         message: `${file}: the body needs code, in a fence under a Must, Never, Should, or Should not heading, or untagged`,
       });
     }
-    const { includeWorkspacePackages, ...fields } = front;
-    return {
-      ...fields,
-      ...(includeWorkspacePackages === undefined
-        ? {}
-        : { includeWorkspacePackages: includeWorkspacePackages === "true" }),
-      ...code,
-    };
+    const details = detailsOf(match[2]);
+    return { ...front, ...(details === undefined ? {} : { details }), ...code };
   });

package/src/services/AdhereConfig.ts

@@ -133,7 +133,7 @@ export const AdhereConfigLive = (flags: Flags) =>
       const scopedRules = withOverrides(entries, overrides);
       // The manifests are read on every run, so a changed workspace is seen, and only when a rule reads them.
       const workspacePackages = scopedRules.some(
-        (entry) => entry.rule.includeWorkspacePackages === true,
+        (entry) => entry.rule.reads?.includes("workspacePackages") === true,
       )
         ? yield* workspacePackagesOf(cwd)
         : undefined;

package/src/services/Jev.http.ts

@@ -68,9 +68,9 @@ const refused = (message: string) => JevUnavailable.make({ message });
 const bun = (globalThis as { readonly Bun?: unknown }).Bun as Parameters<AppendState>[2];
 
 /**
- * A body as it goes out: when its rule has `includeWorkspacePackages`, with
- * the workspace's packages in its state, and when it has `appendState`, with
- * what the hook returns spread over that. A hook that fails refuses the run.
+ * A body as it goes out: when its rule's `reads` names the workspace's
+ * packages, with them in its state, and when it has `appendState`, with what
+ * the hook returns spread over that. A hook that fails refuses the run.
  */
 const hooked = (
   sent: Body & { readonly state: JevState },
@@ -78,7 +78,9 @@ const hooked = (
   file: JudgedFile,
   workspacePackages: Readonly<Record<string, string>>,
 ): Effect.Effect<Body, JevUnavailable> => {
-  const body = Object.values(group).some((rule) => rule.includeWorkspacePackages === true)
+  const body = Object.values(group).some(
+    (rule) => rule.reads?.includes("workspacePackages") === true,
+  )
     ? { ...sent, state: { ...sent.state, workspacePackages } }
     : sent;
   const [hook] = Object.entries(group).flatMap(([id, rule]) =>

package/src/services/Jev.ts

@@ -160,11 +160,15 @@ const exampleFields = (rule: Rule): Record<string, string> => {
   };
 };
 
-/** The rule as its questions carry it: the description, and its examples under their words. */
-const ruleFields = (rule: Rule) => ({ rule: rule.description, ...exampleFields(rule) });
+/** The rule in words, as Jev reads it: its description, then its details when it has any. */
+const ruleText = (rule: Rule): string =>
+  rule.details === undefined ? rule.description : `${rule.description}\n\n${rule.details}`;
+
+/** The rule as its questions carry it: its text, and its examples under their words. */
+const ruleFields = (rule: Rule) => ({ rule: ruleText(rule), ...exampleFields(rule) });
 
 /** A rule's text as a comparison of rules reads it. */
-const ruleState = (rule: Rule) => ({ description: rule.description, ...exampleFields(rule) });
+const ruleState = (rule: Rule) => ({ description: ruleText(rule), ...exampleFields(rule) });
 
 /**
  * The compared rules a question mentions, keyed by index: ids alone would
@@ -477,9 +481,9 @@ export const requestsOf = (body: Body): ReadonlyArray<Body> => {
   return requests.map(({ questions }) => ({ ...body, questions }));
 };
 
-/** Whether a rule reads state of its own: what its `appendState` adds, or the workspace's packages. */
+/** Whether a rule reads state of its own: what its `appendState` adds, or what its `reads` names. */
 const readsOwnState = (rule: Rule): boolean =>
-  rule.appendState !== undefined || rule.includeWorkspacePackages === true;
+  rule.appendState !== undefined || (rule.reads ?? []).length > 0;
 
 /**
  * The rules as requests carry them: every rule that reads only the code in

package/src/workflows/audit.ts

@@ -125,7 +125,9 @@ const fingerprintOf = (
   const scope = matchers.length === 0 ? "" : `\u0000${JSON.stringify(matchers)}`;
   const hook = rule.appendState === undefined ? "" : `\u0000${rule.appendState.toString()}`;
   const packages =
-    rule.includeWorkspacePackages === true ? `\u0000${JSON.stringify(workspacePackages)}` : "";
+    rule.reads?.includes("workspacePackages") === true
+      ? `\u0000${JSON.stringify(workspacePackages)}`
+      : "";
   return sha256(
     `${model}\u0000${LAYOUT}\u0000${JSON.stringify(judgeQuestion(rule))}${scope}${hook}${packages}`,
   );