@drkmttr/adhere 0.13.0 → 0.13.1

package/README.md

@@ -676,6 +676,51 @@ its matchers dropped, with their scores.
 Keeping the scope out of the description keeps the description to what the
 rule asks for, which the report shows, and gives each part a score of its own.
 
+### Workspace packages
+
+A rule can turn on whose package an import is of: the repository's own, or
+one installed from a registry. The file alone does not show that, so a rule
+can ask for the workspace's packages, with `includeWorkspacePackages: true`
+in its front matter, or as a field of a rule in TypeScript or a config:
+
+````md
+---
+description: A function from one of this repository's own packages, which `workspacePackages` names, must be called through the package's namespace, never imported by its own name.
+includeWorkspacePackages: true
+---
+
+## Must
+
+```ts
+import * as Orders from "orders-core";
+```
+
+## Never
+
+```ts
+import { parse } from "orders-core";
+```
+````
+
+Jev then reads, beside the code, `workspacePackages`: each package's name
+with its directory from the working directory, as in
+`{ "orders-core": "packages/orders" }`. The description can name that key in
+backticks, as the questions name `code`. A package that is not in it is an
+installed one.
+
+The packages are read on every run, when a rule asks for them, from the
+working directory's `package.json`, whose `workspaces` npm, Bun, and Yarn
+read, and from `pnpm-workspace.yaml`'s `packages`. In a pattern, `*` is any
+directory and `**` any depth of them, and one that starts with `!` leaves out
+what it matches. Each matched directory's `package.json` gives the name.
+Nothing need be installed, so a run in CI reads the same packages as one on a
+laptop. A working directory that is not a workspace's root has none.
+
+Such a rule goes to Jev in requests of its own, as a rule with `appendState`
+does, so no other rule reads the packages. They are part of what its
+judgments are cached under: when a package is added, renamed, or moved, that
+rule is judged again for every file, and no other rule is.
+
 ### Rule writing tips
 
 We've evaluated different ways of giving Jev a rule, to catch the most

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "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.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"
   }
 }

package/skills/adhere/SKILL.md

@@ -102,6 +102,13 @@ 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
+  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/src/config.ts

@@ -67,6 +67,14 @@ 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)),
+  /**
+   * 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.
+   */
+  includeWorkspacePackages: Schema.optionalKey(Schema.Boolean),
   /**
    * 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 +304,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 asks for
+   * them with `includeWorkspacePackages`.
+   */
+  readonly workspacePackages?: Readonly<Record<string, string>>;
 }
 
 /** Command-line values that apply on top of the config file. */

package/src/markdown.ts

@@ -44,6 +44,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"])),
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
@@ -206,5 +207,12 @@ 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 { includeWorkspacePackages, ...fields } = front;
+    return {
+      ...fields,
+      ...(includeWorkspacePackages === undefined
+        ? {}
+        : { includeWorkspacePackages: includeWorkspacePackages === "true" }),
+      ...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.includeWorkspacePackages === true,
+      )
+        ? yield* workspacePackagesOf(cwd)
+        : undefined;
+      return AdhereConfig.of({
+        ...resolved,
+        scopedRules,
+        ...(workspacePackages === undefined ? {} : { workspacePackages }),
+      });
     }),
   );

package/src/services/Jev.http.ts

@@ -68,14 +68,19 @@ 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 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.
  */
 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.includeWorkspacePackages === 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 +278,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

@@ -477,18 +477,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 the workspace's packages. */
+const readsOwnState = (rule: Rule): boolean =>
+  rule.appendState !== undefined || rule.includeWorkspacePackages === true;
+
 /**
- * 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,22 @@ 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.includeWorkspacePackages === 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 +322,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;
+});