@drkmttr/adhere 0.10.0 → 0.12.0

package/src/install.ts

@@ -0,0 +1,147 @@
+import { spawn } from "node:child_process";
+import { access, copyFile, mkdir, mkdtemp, readdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, join, sep } from "node:path";
+import { ADHERE_DIRECTORY, type RuleId } from "#config.ts";
+import { parseRuleMarkdown } from "#markdown.ts";
+import { Effect } from "effect";
+
+/**
+ * A GitHub repo whose `.adhere/` rules another repo copies: `org/repo`, then
+ * optionally a topic or a rule's id, then optionally `#` and a branch or tag,
+ * as in `darkmatter/standards/data/brand-ports#v3`.
+ */
+export interface Source {
+  readonly repo: string;
+  /** A rule id or a topic, `data/brand-ports` or `data`; empty for every rule. */
+  readonly rule: string;
+  readonly ref?: string;
+}
+
+export const parseSource = (spec: string): Source | undefined => {
+  const [path = "", ref] = spec.split("#");
+  const [org, repo, ...rule] = path.split("/").filter((segment) => segment.length > 0);
+  if (org === undefined || repo === undefined || ref === "") return undefined;
+  return { repo: `${org}/${repo}`, rule: rule.join("/"), ...(ref === undefined ? {} : { ref }) };
+};
+
+const failed = (what: string) => (cause: unknown) =>
+  new Error(`${what}: ${cause instanceof Error ? cause.message : String(cause)}`);
+
+/**
+ * A shallow clone in a temporary directory, deleted when the scope closes.
+ * git, rather than GitHub's API, so a private repo is reached with whatever
+ * credentials git already has, and `url.<base>.insteadOf` can point
+ * github.com elsewhere, such as at SSH.
+ */
+const cloned = (source: Source) =>
+  Effect.acquireRelease(
+    Effect.tryPromise({
+      try: async () => {
+        const directory = await mkdtemp(join(tmpdir(), "adhere-install-"));
+        const branch = source.ref === undefined ? [] : ["--branch", source.ref];
+        const url = `https://github.com/${source.repo}.git`;
+        await new Promise<void>((resolve, reject) => {
+          let stderr = "";
+          spawn("git", ["clone", "--quiet", "--depth", "1", ...branch, url, directory], {
+            stdio: ["inherit", "ignore", "pipe"],
+          })
+            .on("error", reject)
+            .on("exit", (code) =>
+              code === 0
+                ? resolve()
+                : reject(new Error(stderr.trim() || `git exited with ${code}`)),
+            )
+            .stderr?.on("data", (chunk) => {
+              stderr += chunk;
+            });
+        });
+        return directory;
+      },
+      catch: failed(`Could not clone ${source.repo}`),
+    }),
+    (directory) => Effect.promise(() => rm(directory, { recursive: true, force: true })),
+  );
+
+/** The repo's root `.adhere/` rule files by id, as lint reads them there: every `*.md` outside `cache/`. */
+const rulesIn = (source: Source, clone: string) =>
+  Effect.tryPromise({
+    try: async () => {
+      const directory = join(clone, ADHERE_DIRECTORY);
+      const entries = await readdir(directory, { recursive: true }).catch(() => []);
+      const ids = entries
+        .filter((entry) => entry.endsWith(".md") && !entry.startsWith(`cache${sep}`))
+        .map((entry): RuleId => entry.slice(0, -".md".length).split(sep).join("/"))
+        .filter(
+          (id) => source.rule === "" || id === source.rule || id.startsWith(`${source.rule}/`),
+        )
+        .sort();
+      if (ids.length === 0) {
+        throw new Error(
+          source.rule === ""
+            ? `it has no rules in ${ADHERE_DIRECTORY}/`
+            : `it has no rule or topic ${source.rule} in ${ADHERE_DIRECTORY}/`,
+        );
+      }
+      return ids.map((id) => ({ id, file: join(directory, `${id}.md`) }));
+    },
+    catch: failed(`Nothing to copy from ${source.repo}`),
+  });
+
+/** Each rule a source names, with its description. */
+export const listRules = (source: Source) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const rules = yield* rulesIn(source, yield* cloned(source));
+      return yield* Effect.forEach(rules, ({ id, file }) =>
+        Effect.gen(function* () {
+          const text = yield* Effect.tryPromise({
+            try: () => readFile(file, "utf8"),
+            catch: failed(`Could not read ${id}`),
+          });
+          const rule = yield* parseRuleMarkdown(text, `${source.repo}/${id}.md`);
+          return { id, description: rule.description };
+        }),
+      );
+    }),
+  );
+
+export interface InstallResult {
+  readonly created: ReadonlyArray<string>;
+  readonly skipped: ReadonlyArray<string>;
+}
+
+/**
+ * Copies the rules a source names into `root`'s `.adhere/` under the source's
+ * org and repo, so `data/ports` from acme/rules is the rule
+ * `acme/rules/data/ports`, and two sources' rules never collide. They are the
+ * project's own rules from then on. As with init, a file already there is
+ * skipped unless `force`.
+ */
+export const installRules = (root: string, source: Source, options: { readonly force?: boolean }) =>
+  Effect.scoped(
+    Effect.gen(function* () {
+      const rules = yield* rulesIn(source, yield* cloned(source));
+      const created: Array<string> = [];
+      const skipped: Array<string> = [];
+      for (const { id, file } of rules) {
+        const path = `${ADHERE_DIRECTORY}/${source.repo}/${id}.md`;
+        const target = join(root, path);
+        const copied = yield* Effect.tryPromise({
+          try: async () => {
+            const exists = await access(target).then(
+              () => true,
+              () => false,
+            );
+            if (exists && options.force !== true) return false;
+            await mkdir(dirname(target), { recursive: true });
+            await copyFile(file, target);
+            return true;
+          },
+          catch: failed(`Could not write ${path}`),
+        });
+        (copied ? created : skipped).push(path);
+      }
+      return { created, skipped } satisfies InstallResult;
+    }),
+  );

package/src/markdown.ts

@@ -32,12 +32,18 @@ import { Effect, Schema } from "effect";
  * so is `tests`: `only` for a rule about test files, which rules otherwise
  * skip, and `include` for a rule that judges them too. So is `level`:
  * `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"]`.
  */
+const Matchers = Schema.fromJsonString(Schema.Array(Schema.String));
+
 const FrontMatter = Schema.Struct({
   description: Schema.String,
   threshold: Schema.optionalKey(Schema.FiniteFromString),
   tests: Schema.optionalKey(Schema.Literals(["only", "include"])),
   level: Schema.optionalKey(Schema.Literals(["error", "warning"])),
+  appliesTo: Schema.optionalKey(Matchers),
+  excludeIf: Schema.optionalKey(Matchers),
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;

package/src/presets.ts

@@ -23,6 +23,9 @@ const presetsRoot = isStandaloneExecutable
 const topics = {
   effect: ["basics", "config", "data", "errors", "services", "testing"],
   alchemy: ["apis", "data", "durable", "providers", "resources", "runtime", "secrets", "security"],
+  typescript: ["async", "design", "errors", "testing", "types"],
+  react: ["effects", "server", "state"],
+  security: [],
 } as const;
 
 type Topics = typeof topics;
@@ -57,6 +60,9 @@ export const presetOf = (name: PresetName): BuiltInPreset => {
 export const presets: Readonly<Record<WholePreset, BuiltInPreset>> = {
   effect: presetOf("effect"),
   alchemy: presetOf("alchemy"),
+  typescript: presetOf("typescript"),
+  react: presetOf("react"),
+  security: presetOf("security"),
 };
 
 /** The directory each whole preset reads, for checking `topics` against it. */

package/src/rules.ts

@@ -27,7 +27,7 @@ export interface RuleEntry {
 
 /**
  * A rule's id as output shows it: a preset's rule with the preset's name
- * first, as in effect/basics/external-calls-are-resilient, so a report that
+ * first, as in effect/basics/gen-for-sequencing, so a report that
  * mixes presets with the project's own rules says where each came from. The
  * project's own rules show their `.adhere/` ids as they are.
  */

package/src/services/AuditCache.ts

@@ -1,11 +1,30 @@
 import { CACHE_DIRECTORY } from "#config.ts";
 import { Context, Crypto, Effect, FileSystem, Layer, Option, Path, Record, Schema } from "effect";
 
+/** Jev's probability for each of a rule's `appliesTo` and `excludeIf` matchers, when it has them. */
+const MatcherFields = {
+  appliesTo: Schema.optionalKey(Schema.Array(Schema.Finite)),
+  excludeIf: Schema.optionalKey(Schema.Array(Schema.Finite)),
+};
+
+/** Lines of a file, first to last. */
+const Lines = Schema.Struct({ first: Schema.Finite, last: Schema.Finite });
+/** The lines of the section a finding is in, once located. */
+const Section = Schema.optionalKey(Lines);
+/** The lines in its section the code that breaks the rule starts and ends on, when Jev named them. */
+const Located = Schema.optionalKey(Lines);
+
+/** Jev's probability, asked with the section, that the file shows enough to decide the rule. */
+const Sufficiency = Schema.optionalKey(Schema.Finite);
+
 /** A rule's judgment as a run holds it: Jev's answer, with the fingerprint of the rule's text. */
 export const Judgment = Schema.Struct({
   fingerprint: Schema.String,
   probability: Schema.Finite,
-  line: Schema.optionalKey(Schema.Finite),
+  section: Section,
+  lines: Located,
+  sufficiency: Sufficiency,
+  ...MatcherFields,
 });
 export interface Judgment extends Schema.Schema.Type<typeof Judgment> {}
 
@@ -21,10 +40,17 @@ export const CacheEntry = Schema.Struct({
 });
 export interface CacheEntry extends Schema.Schema.Type<typeof CacheEntry> {}
 
-/** Jev's answer about some code for one rule text: the probability, and the line once located. */
+/**
+ * Jev's answer about some code for one rule text: the probability, the
+ * section, lines, and sufficiency once located, and its matchers' scores. An answer from before
+ * sections held a line instead, under a fingerprint no rule has now.
+ */
 export const Answer = Schema.Struct({
   probability: Schema.Finite,
-  line: Schema.optionalKey(Schema.Finite),
+  section: Section,
+  lines: Located,
+  sufficiency: Sufficiency,
+  ...MatcherFields,
 });
 export interface Answer extends Schema.Schema.Type<typeof Answer> {}
 
@@ -98,13 +124,13 @@ const sorted = <A>(record: Readonly<Record<string, A>>): Record<string, A> =>
 
 const textOf = (value: unknown): string => `${JSON.stringify(value, null, 2)}\n`;
 
-/** One answer per rule text: one that has its line over one that has not, otherwise the first. */
+/** One answer per rule text: one that has its section over one that has not, otherwise the first. */
 const unionOf = (entries: ReadonlyArray<Answers>): Answers => {
   const union: Record<string, Answer> = {};
   for (const answers of entries) {
     for (const [fingerprint, answer] of Object.entries(answers)) {
       const held = union[fingerprint];
-      if (held === undefined || (held.line === undefined && answer.line !== undefined)) {
+      if (held === undefined || (held.section === undefined && answer.section !== undefined)) {
         union[fingerprint] = answer;
       }
     }

package/src/services/Jev.http.ts

@@ -1,10 +1,11 @@
 import type { RuleId } from "#config.ts";
+import { sectionsOf } from "#excerpt.ts";
 import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { Credentials } from "#services/Credentials.ts";
 import {
-  blockBody,
   type Body,
   type ComparedRule,
+  edgeKey,
   conflictBody,
   contradictBody,
   Jev,
@@ -16,15 +17,27 @@ import {
   type Lines,
   linterKey,
   locateBody,
+  matcherKey,
+  type MatcherScores,
   namedPairs,
-  needsBlocks,
   type Pair,
   pairProbability,
   requestsOf,
   type Rules,
+  sufficiencyKey,
   tokensOf,
 } from "#services/Jev.ts";
-import { type Cause, Duration, Effect, Layer, Option, Record, Schedule, Schema } from "effect";
+import {
+  type Cause,
+  Duration,
+  Effect,
+  Layer,
+  Option,
+  Record,
+  Result,
+  Schedule,
+  Schema,
+} from "effect";
 import { HttpClient, HttpClientError, HttpClientResponse } from "effect/unstable/http";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 import { RateLimiter } from "effect/unstable/persistence";
@@ -37,6 +50,16 @@ const NoulAnswers = Schema.Struct({
 const ChoiceAnswers = Schema.Struct({
   answers: Schema.Record(Schema.String, Schema.Struct({ choice: Schema.String })),
 });
+/** A locate request's answers: a choice per rule, and a noul per sufficiency question. */
+const LocateAnswers = Schema.Struct({
+  answers: Schema.Record(
+    Schema.String,
+    Schema.Struct({
+      choice: Schema.optionalKey(Schema.String),
+      noul: Schema.optionalKey(Schema.Finite),
+    }),
+  ),
+});
 
 const refused = (message: string) => JevUnavailable.make({ message });
 
@@ -219,22 +242,64 @@ export const JevLive = Layer.effect(Jev)(
             return answer === undefined ? [] : [[id, answer.noul] as const];
           }),
         );
+      // A matcher Jev left unanswered counts as a no.
+      const scored = (
+        kind: keyof MatcherScores,
+        id: RuleId,
+        matchers: ReadonlyArray<string> = [],
+      ) => matchers.map((_, index) => answers[matcherKey(kind, id, index)]?.noul ?? 0);
+      const matchers: Record<RuleId, MatcherScores> = Record.fromEntries(
+        Object.entries(rules).flatMap(([id, rule]) =>
+          rule.appliesTo === undefined && rule.excludeIf === undefined
+            ? []
+            : [
+                [
+                  id,
+                  {
+                    appliesTo: scored("appliesTo", id, rule.appliesTo),
+                    excludeIf: scored("excludeIf", id, rule.excludeIf),
+                  },
+                ] as const,
+              ],
+        ),
+      );
       return {
         probabilities: answered(Object.keys(rules), (id) => id),
         linter: answered(sampled, linterKey),
+        ...(Record.isEmptyRecord(matchers) ? {} : { matchers }),
       } satisfies Judged;
     });
 
-    const chosen = (answers: Readonly<Record<string, { choice: string }>>) =>
-      Record.map(answers, (answer) => Number(answer.choice));
-
     const locate = Effect.fn("Jev.locate")(function* (lines: Lines, rules: Rules) {
-      const blocks = needsBlocks(lines)
-        ? chosen(yield* answersTo("blocks", blockBody(config.model, lines, rules), ChoiceAnswers))
-        : undefined;
-      return chosen(
-        yield* answersTo("locate", locateBody(config.model, lines, rules, blocks), ChoiceAnswers),
+      const sections = sectionsOf(lines);
+      const answers = yield* answersTo(
+        "locate",
+        locateBody(config.model, lines, rules),
+        LocateAnswers,
       );
+      // A file of one section has every finding in it. An answer that names no section,
+      // or none at all, which Jev should not give, leaves the rule unlocated; lines outside
+      // the section leave it without lines.
+      return Record.filterMap(rules, (_, id) => {
+        const chosen = sections.length === 1 ? 1 : Number(answers[id]?.choice);
+        const section = sections[chosen - 1];
+        const sufficiency = answers[sufficiencyKey(id)]?.noul;
+        if (section === undefined || sufficiency === undefined) return Result.failVoid;
+        const [start, end] = (["start", "end"] as const).map((edge) =>
+          Number(answers[edgeKey(edge, id, chosen)]?.choice),
+        );
+        const within = (line: number | undefined): line is number =>
+          line !== undefined && section.first <= line && line <= section.last;
+        return Result.succeed(
+          within(start) && within(end)
+            ? {
+                section,
+                sufficiency,
+                lines: { first: Math.min(start, end), last: Math.max(start, end) },
+              }
+            : { section, sufficiency },
+        );
+      });
     });
 
     const conflicts = Effect.fn("Jev.conflicts")(function* (