@drkmttr/adhere 0.13.0 → 0.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.13.0",
+  "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.0",
-    "@drkmttr/adhere-darwin-x64": "0.13.0",
-    "@drkmttr/adhere-linux-arm64": "0.13.0",
-    "@drkmttr/adhere-linux-x64": "0.13.0",
-    "@drkmttr/adhere-win32-x64": "0.13.0"
+    "@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,6 +106,15 @@ 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.
+- `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
 `defineRule({...})` from `@drkmttr/adhere`, with the fields a config's inline

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),
@@ -67,6 +83,12 @@ const RuleFields = Schema.Struct({
    * that breaks the rule is as it describes, and a yes to any drops the finding.
    */
   excludeIf: Schema.optionalKey(Schema.Array(Schema.String)),
+  /**
+   * 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.
+   */
+  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
@@ -296,6 +318,12 @@ export interface ResolvedConfig {
   readonly exclude?: ReadonlyArray<string>;
   /** Whether Jev reads every comment; unset, only the `@adhere` notes. */
   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's `reads`
+   * names them.
+   */
+  readonly workspacePackages?: Readonly<Record<string, string>>;
 }
 
 /** Command-line values that apply on top of the config file. */

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,6 +46,7 @@ const FrontMatter = Schema.Struct({
   level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
   appliesTo: Schema.optionalKey(Matchers),
   excludeIf: Schema.optionalKey(Matchers),
+  reads: Schema.optionalKey(Schema.fromJsonString(Reads)),
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -148,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">;
 
 /**
@@ -206,5 +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`,
       });
     }
-    return { ...front, ...code };
+    const details = detailsOf(match[2]);
+    return { ...front, ...(details === undefined ? {} : { details }), ...code };
   });

package/src/services/AdhereConfig.ts

@@ -21,6 +21,7 @@ import {
   shownId,
   withOverrides,
 } from "#rules.ts";
+import { workspacePackagesOf } from "#workspaces.ts";
 import { Context, Effect, FileSystem, Layer, Path, Record } from "effect";
 
 export class AdhereConfig extends Context.Service<AdhereConfig, ResolvedConfig>()(
@@ -129,6 +130,17 @@ export const AdhereConfigLive = (flags: Flags) =>
           });
         }
       }
-      return AdhereConfig.of({ ...resolved, scopedRules: withOverrides(entries, overrides) });
+      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.reads?.includes("workspacePackages") === true,
+      )
+        ? yield* workspacePackagesOf(cwd)
+        : undefined;
+      return AdhereConfig.of({
+        ...resolved,
+        scopedRules,
+        ...(workspacePackages === undefined ? {} : { workspacePackages }),
+      });
     }),
   );

package/src/services/Jev.http.ts

@@ -68,14 +68,21 @@ 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 `appendState`, with what the hook
- * returns spread over the body's state. 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 = (
-  body: Body & { readonly state: JevState },
+  sent: Body & { readonly state: JevState },
   group: Rules,
   file: JudgedFile,
+  workspacePackages: Readonly<Record<string, string>>,
 ): Effect.Effect<Body, JevUnavailable> => {
+  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]) =>
     rule.appendState === undefined ? [] : [[id, rule.appendState] as const],
   );
@@ -273,8 +280,9 @@ export const JevLive = Layer.effect(Jev)(
     ) =>
       Effect.map(
         Effect.forEach(requestGroups(rules), (group) =>
-          Effect.flatMap(hooked(bodyOf(group), group, file), (body) =>
-            answersTo(kind, body, Answers),
+          Effect.flatMap(
+            hooked(bodyOf(group), group, file, config.workspacePackages ?? {}),
+            (body) => answersTo(kind, body, Answers),
           ),
         ),
         (groups) =>

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,18 +481,20 @@ 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 what its `reads` names. */
+const readsOwnState = (rule: Rule): boolean =>
+  rule.appendState !== undefined || (rule.reads ?? []).length > 0;
+
 /**
- * The rules as requests carry them: every rule without `appendState` in one
- * body, and each rule with it in a body of its own, so that what its hook
- * puts in the state only its own questions read.
+ * The rules as requests carry them: every rule that reads only the code in
+ * one body, and each rule with state of its own in a body of its own, so
+ * that what is added to the state for it only its own questions read.
  */
 export const requestGroups = (rules: Rules): ReadonlyArray<Rules> => {
-  const shared = Record.filter(rules, (rule) => rule.appendState === undefined);
+  const shared = Record.filter(rules, (rule) => !readsOwnState(rule));
   return [
     ...(Record.isEmptyRecord(shared) ? [] : [shared]),
-    ...Object.entries(rules).flatMap(([id, rule]) =>
-      rule.appendState === undefined ? [] : [{ [id]: rule }],
-    ),
+    ...Object.entries(rules).flatMap(([id, rule]) => (readsOwnState(rule) ? [{ [id]: rule }] : [])),
   ];
 };
 

package/src/workflows/audit.ts

@@ -112,14 +112,24 @@ const LAYOUT = "sections";
  * judge question, and its matchers' when it has any. An edited rule or
  * matcher re-judges the rule, and a question asked differently re-judges
  * every rule. So does an edited `appendState`, by its source; what the hook
- * reads outside the file is not known until it runs, so a change there does not.
+ * reads outside the file is not known until it runs, so a change there does
+ * not. A rule that reads the workspace's packages depends on them too, so a
+ * package added, renamed, or moved re-judges that rule and no other.
  */
-const fingerprintOf = (model: string, rule: Rule) => {
+const fingerprintOf = (
+  model: string,
+  rule: Rule,
+  workspacePackages: Readonly<Record<string, string>> = {},
+) => {
   const matchers = matcherQuestions("", rule).map(([, question]) => question);
   const scope = matchers.length === 0 ? "" : `\u0000${JSON.stringify(matchers)}`;
   const hook = rule.appendState === undefined ? "" : `\u0000${rule.appendState.toString()}`;
+  const packages =
+    rule.reads?.includes("workspacePackages") === true
+      ? `\u0000${JSON.stringify(workspacePackages)}`
+      : "";
   return sha256(
-    `${model}\u0000${LAYOUT}\u0000${JSON.stringify(judgeQuestion(rule))}${scope}${hook}`,
+    `${model}\u0000${LAYOUT}\u0000${JSON.stringify(judgeQuestion(rule))}${scope}${hook}${packages}`,
   );
 };
 
@@ -314,7 +324,7 @@ export const planAudit = (
       const prepared: Record<RuleId, PreparedRule> = yield* Effect.forEach(
         Object.entries(rules),
         ([id, rule]) =>
-          Effect.map(fingerprintOf(config.model, rule), (fingerprint) => {
+          Effect.map(fingerprintOf(config.model, rule, config.workspacePackages), (fingerprint) => {
             const preset = presetOfRule.get(rule);
             return [
               id,

package/src/workspaces.ts

@@ -0,0 +1,141 @@
+import { Effect, FileSystem, Path } from "effect";
+
+/** A workspace's packages: each one's name, with its directory from the root. */
+export type WorkspacePackages = Readonly<Record<string, string>>;
+
+/** What JSON text holds, or nothing when it is not JSON. */
+const parsed = (text: string): unknown => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+
+/** The strings of a value that is an array of them, and none of any other value. */
+const strings = (value: unknown): ReadonlyArray<string> =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+
+/**
+ * A root package.json's workspace patterns: `workspaces` as an array, which
+ * npm, Bun, and Yarn read, or as Yarn's `{ packages: [...] }`.
+ */
+const manifestPatterns = (manifest: unknown): ReadonlyArray<string> => {
+  const workspaces = (manifest as { readonly workspaces?: unknown } | undefined)?.workspaces;
+  return Array.isArray(workspaces)
+    ? strings(workspaces)
+    : strings((workspaces as { readonly packages?: unknown } | undefined)?.packages);
+};
+
+/**
+ * The patterns under `packages:` in a pnpm-workspace.yaml: the list items
+ * that follow it, up to the next key. Read line by line, since that list is
+ * all of the file adhere needs and the executable carries no YAML parser.
+ */
+const pnpmPatterns = (yaml: string): ReadonlyArray<string> => {
+  const lines = yaml.split(/\r?\n/);
+  const start = lines.findIndex((line) => /^packages:\s*$/.test(line));
+  if (start < 0) return [];
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex((line) => /^\S/.test(line) && !line.startsWith("-"));
+  return (end < 0 ? rest : rest.slice(0, end)).flatMap((line) => {
+    const [, item] = /^\s*-\s*(.+?)\s*$/.exec(line) ?? [];
+    return item === undefined ? [] : [item.replace(/^["']|["']$/g, "")];
+  });
+};
+
+/** Whether a directory's name matches a pattern segment, where `*` stands for any run of characters. */
+const matches = (segment: string, name: string): boolean =>
+  new RegExp(
+    `^${segment
+      .split("*")
+      .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+      .join(".*")}$`,
+  ).test(name);
+
+/**
+ * The packages of the workspace whose root is `root`, by name, sorted, so
+ * the same workspace always reads the same: from the root package.json's
+ * `workspaces` and from pnpm-workspace.yaml's `packages`. A pattern's `*` is
+ * any directory and `**` any depth of them, outside `node_modules` and dot
+ * directories, and one that starts with `!` leaves out what it matches. A
+ * root that has neither file, or names no workspaces, has no packages.
+ */
+export const workspacePackagesOf = Effect.fn("workspacePackagesOf")(function* (root: string) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const read = (file: string) =>
+    fs.readFileString(path.join(root, file)).pipe(Effect.orElseSucceed(() => ""));
+  const children = (directory: string) =>
+    fs.readDirectory(path.join(root, directory)).pipe(
+      Effect.orElseSucceed((): ReadonlyArray<string> => []),
+      Effect.map((names) =>
+        names.filter((name) => name !== "node_modules" && !name.startsWith(".")),
+      ),
+      Effect.flatMap((names) =>
+        Effect.filter(names, (name) =>
+          fs.stat(path.join(root, directory, name)).pipe(
+            Effect.map((info) => info.type === "Directory"),
+            Effect.orElseSucceed(() => false),
+          ),
+        ),
+      ),
+      Effect.map((names) =>
+        names.map((name) => (directory === "" ? name : `${directory}/${name}`)),
+      ),
+    );
+  /** The directories under `directory` that the pattern's remaining segments lead to. */
+  const expand = (
+    directory: string,
+    segments: ReadonlyArray<string>,
+  ): Effect.Effect<ReadonlyArray<string>> => {
+    const [segment, ...rest] = segments;
+    if (segment === undefined) return Effect.succeed([directory]);
+    if (segment === "**") {
+      return Effect.gen(function* () {
+        const below = yield* Effect.forEach(yield* children(directory), (child) =>
+          expand(child, segments),
+        );
+        return [...(yield* expand(directory, rest)), ...below.flat()];
+      });
+    }
+    if (!segment.includes("*")) {
+      return expand(directory === "" ? segment : `${directory}/${segment}`, rest);
+    }
+    return Effect.flatMap(children(directory), (names) =>
+      Effect.map(
+        Effect.forEach(
+          names.filter((name) => matches(segment, name.slice(name.lastIndexOf("/") + 1))),
+          (child) => expand(child, rest),
+        ),
+        (found) => found.flat(),
+      ),
+    );
+  };
+  const segmentsOf = (pattern: string) =>
+    pattern.split("/").filter((segment) => segment !== "" && segment !== ".");
+  const patterns = [
+    ...manifestPatterns(parsed(yield* read("package.json"))),
+    ...pnpmPatterns(yield* read("pnpm-workspace.yaml")),
+  ];
+  const directoriesOf = (chosen: ReadonlyArray<string>) =>
+    Effect.map(
+      Effect.forEach(chosen, (pattern) => expand("", segmentsOf(pattern))),
+      (found) => new Set(found.flat()),
+    );
+  const included = yield* directoriesOf(patterns.filter((pattern) => !pattern.startsWith("!")));
+  const excluded = yield* directoriesOf(
+    patterns.filter((pattern) => pattern.startsWith("!")).map((pattern) => pattern.slice(1)),
+  );
+  const named = yield* Effect.forEach(
+    [...included].filter((directory) => !excluded.has(directory)),
+    (directory) =>
+      Effect.map(read(`${directory}/package.json`), (text) => {
+        const name = (parsed(text) as { readonly name?: unknown } | undefined)?.name;
+        return typeof name === "string" ? [[name, directory] as const] : [];
+      }),
+  );
+  return Object.fromEntries(
+    named.flat().sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+  ) as WorkspacePackages;
+});