@drkmttr/adhere 0.18.1 → 0.23.0

package/src/workflows/audit.ts

@@ -40,7 +40,13 @@ import { SAMPLE, tallyKeyOf } from "#mechanical.ts";
 import { priceOf } from "#pricing.ts";
 import { applicableRules, judgesFile, shownId } from "#rules.ts";
 import { suppresses, type Suppressions, suppressionsOf } from "#suppress.ts";
-import { workspacePackagesIn } from "#workspaces.ts";
+import {
+  dependentFilesIn,
+  importSpecifiersIn,
+  packageOf,
+  workspacePackagesIn,
+} from "#workspaces.ts";
+import { relative, sep } from "node:path";
 import { type Crypto, Duration, Effect, Option, Record, Result, Semaphore, Stream } from "effect";
 
 export interface Finding {
@@ -125,19 +131,24 @@ const LAYOUT = "sections";
 
 /**
  * What a judgment depends on besides the file: the model, how the file is
- * laid out, and the questions asked for the rule, which carry the rule: its
- * 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. Shared read context and related files do not invalidate judgments.
+ * laid out, what the config has Jev read, and the questions asked for the
+ * rule, which carry the rule: its judge question, and its matchers' when it
+ * has any. An edited rule or matcher re-judges the rule, and a question asked
+ * differently, or other reads, re-judge 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. Options set differently
+ * re-judge their rule: decoded, a struct's keys come in its schema's order,
+ * however the config writes them. What the reads find, such as related
+ * files, does not invalidate judgments.
  */
-const fingerprintOf = (model: string, rule: Rule) => {
+const fingerprintOf = (model: string, reads: string, rule: Rule) => {
   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 options =
+    rule.optionValues === undefined ? "" : `\u0000${JSON.stringify(rule.optionValues)}`;
   return sha256(
-    `${model}\u0000${LAYOUT}\u0000${JSON.stringify(judgeQuestion(rule))}${scope}${hook}`,
+    `${model}\u0000${LAYOUT}${reads}\u0000${JSON.stringify(judgeQuestion(rule))}${scope}${hook}${options}`,
   );
 };
 
@@ -368,9 +379,14 @@ const hasLocatedFindings = (plan: FilePlan): boolean =>
     );
   });
 
+/** At most this many of a file's dependent files are listed; the rest are counted. */
+const MAX_DEPENDENT_FILES = 50;
+
 export interface PlanOptions {
   /** Select at most this many files needing judge or cached-locate requests; zero plans only. */
   readonly limit?: number | undefined;
+  /** The checkout Jev's paths are relative to. Defaults to the working directory. */
+  readonly root?: string | undefined;
 }
 
 export const planAudit = (
@@ -386,6 +402,7 @@ export const planAudit = (
     const workspacePackages = config.reads.includes("workspacePackages")
       ? (config.workspacePackages ?? {})
       : undefined;
+    const catalog = config.workspacePackages ?? {};
     const nativeReads: SourceReadRequest = {
       symbols: config.typeAware,
       references: config.typeAware,
@@ -395,6 +412,40 @@ export const planAudit = (
     };
     const walker = yield* SourceWalker;
     const files = yield* walker.files;
+    // Each file's path from the checkout, `/`-separated, as Jev reads it.
+    const root = options.root ?? process.cwd();
+    const fromRoot = new Map(
+      files.map((file) => [file.path, relative(root, file.path).split(sep).join("/")]),
+    );
+    // Only the specifiers stay in memory: each file is read again when it is planned.
+    const dependentFiles = config.reads.includes("dependents")
+      ? dependentFilesIn(
+          new Map(
+            yield* Effect.forEach(
+              files,
+              (file) =>
+                Effect.map(
+                  walker.read(file),
+                  ({ lines }) =>
+                    [fromRoot.get(file.path)!, importSpecifiersIn(lines.join("\n"))] as const,
+                ),
+              { concurrency: 8 },
+            ),
+          ),
+        )
+      : undefined;
+    const dependentsOf = (file: SourceFile) => {
+      const at = fromRoot.get(file.path)!;
+      const name = packageOf(at, catalog);
+      const importers = dependentFiles?.get(at) ?? [];
+      return {
+        packages: (name === undefined ? undefined : config.workspaceDependents?.[name]) ?? {},
+        files: importers.slice(0, MAX_DEPENDENT_FILES),
+        ...(importers.length > MAX_DEPENDENT_FILES
+          ? { omittedFiles: importers.length - MAX_DEPENDENT_FILES }
+          : {}),
+      };
+    };
 
     // Each preset's rule, with the preset it came from, for its findings to name.
     const presetOfRule = new Map(
@@ -416,11 +467,23 @@ export const planAudit = (
       );
 
     // Model, thresholds, and presets are fixed per plan; share immutable descriptors by Rule identity.
+    // The reads that take effect key every judgment; code-only keeps the key it always had.
+    // includeComments shapes other files' `references` excerpts, which the target's hash misses.
+    const reads = [
+      ...(workspacePackages === undefined ? [] : ["workspacePackages"]),
+      ...(dependentFiles === undefined ? [] : ["dependents"]),
+      ...(config.typeAware
+        ? [
+            `symbols:${config.maxSymbolLength}:${config.maxSymbolDocumentationLength}:${config.includeComments === true}`,
+          ]
+        : []),
+    ];
+    const readsKey = reads.length === 0 ? "" : `\u0000${reads.join(",")}`;
     const preparedRules = new Map<Rule, PreparedRule>(
       yield* Effect.forEach(
         new Set(config.scopedRules?.map(({ rule }) => rule) ?? Object.values(config.rules)),
         (rule) =>
-          Effect.map(fingerprintOf(config.model, rule), (fingerprint) => {
+          Effect.map(fingerprintOf(config.model, readsKey, rule), (fingerprint) => {
             const preset = presetOfRule.get(rule);
             return [
               rule,
@@ -440,10 +503,12 @@ export const planAudit = (
       const { lines, suppressions } = normalized(original.lines, config.includeComments === true);
       const rules = configuredRules(file, suppressions);
       const code = lines.join("\n");
-      const readState: ReadState =
-        workspacePackages === undefined
+      const readState: ReadState = {
+        ...(workspacePackages === undefined
           ? {}
-          : { workspacePackages: workspacePackagesIn(code, workspacePackages) };
+          : { workspacePackages: workspacePackagesIn(code, workspacePackages) }),
+        ...(dependentFiles === undefined ? {} : { dependents: dependentsOf(file) }),
+      };
       // Hashed even when unjudged or skipped, so a prune keeps what other runs know of its content.
       const hash = yield* sha256(code);
       const prepared = Record.map(rules, (rule) => preparedRules.get(rule)!);
@@ -802,7 +867,13 @@ export const executeAudit = (
       const room = questionRoom(file.lines, readState);
       const sentSamples = Record.filter(sampled, (_, id) => {
         const k = pending[id];
-        return k !== undefined && tokensOf(linterQuestion(k.rule)) <= room;
+        if (k === undefined) return false;
+        // A rule with options asks beside them, in a request of its own.
+        const left =
+          k.rule.optionValues === undefined
+            ? room
+            : questionRoom(file.lines, { ...readState, options: k.rule.optionValues });
+        return tokensOf(linterQuestion(k.rule)) <= left;
       });
       const sampleIds = Object.keys(sentSamples);
       const { probabilities, linter, matchers }: Judged = isEmpty(pending)

package/src/workflows/format.ts

@@ -89,6 +89,10 @@ const hanging = (label: Span, lines: ReadonlyArray<Line>): ReadonlyArray<Line> =
 const highlighted = (code: string): ReadonlyArray<Line> =>
   tokenize(code).map((tokens) => tokens.map(({ text, kind }) => span(text, kind)));
 
+/** Code as lines of text, highlighted as a report highlights it when `color`. */
+export const highlightedLines = (code: string, color: boolean): ReadonlyArray<string> =>
+  highlighted(code).map((line) => serialize(line, color));
+
 /** Code as highlighted lines, without the blank lines at either end. */
 const codeLines = (code: string): ReadonlyArray<Line> => {
   const lines = highlighted(code);
@@ -210,7 +214,7 @@ const excerpt = (finding: Finding, root: string | undefined): ReadonlyArray<Line
 /**
  * The warning on a finding whose file may not show enough to check its rule,
  * which its context score in the header says how far, and help: how to add
- * what the code relies on as a note Jev reads, in the form the README asks for.
+ * what the code relies on as a note Jev reads, in the form the docs ask for.
  */
 const insufficient = (finding: Finding, sufficiencyThreshold: number): ReadonlyArray<Line> =>
   !lacksContext(finding, sufficiencyThreshold)
@@ -398,6 +402,99 @@ export const render = (result: AuditResult, options: RenderOptions = {}): Readon
   ].map((line) => serialize(line, options.color === true));
 };
 
+/** The complete audit result, with the same rule ids and relative paths as the text report. */
+export const renderJson = (result: AuditResult, options: RenderOptions = {}): string =>
+  JSON.stringify(
+    {
+      ...result,
+      threshold: options.threshold ?? DEFAULT_THRESHOLD,
+      sufficiencyThreshold: options.sufficiencyThreshold ?? DEFAULT_SUFFICIENCY_THRESHOLD,
+      ...(options.provider === undefined ? {} : { provider: options.provider }),
+      findings: result.findings.map((finding) => ({
+        ...finding,
+        rule: shownId({ id: finding.rule, preset: finding.preset }),
+        file: displayPath(finding.file, options.root),
+      })),
+      blocked: result.blocked.map((blocked) => ({
+        ...blocked,
+        file: displayPath(blocked.file, options.root),
+      })),
+    },
+    null,
+    2,
+  );
+
+const markdownText = (text: string): string => text.replace(/[\\`*_[\]<>#]/g, "\\$&");
+
+/** A fence longer than any backtick run in the code, including template literals. */
+const fenced = (code: string): string => {
+  const fence = "`".repeat(
+    Math.max(3, ...Array.from(code.matchAll(/`+/g), ([run]) => run.length + 1)),
+  );
+  return `${fence}typescript\n${code}\n${fence}`;
+};
+
+/** All findings grouped by rule, followed by the run summary once. */
+export const renderMarkdown = (result: AuditResult, options: RenderOptions = {}): string => {
+  const sufficiencyThreshold = options.sufficiencyThreshold ?? DEFAULT_SUFFICIENCY_THRESHOLD;
+  const groups = Map.groupBy(result.findings, (finding) =>
+    shownId({ id: finding.rule, preset: finding.preset }),
+  );
+  return [
+    ...Array.from(groups, ([id, findings]) =>
+      [
+        `# ${markdownText(id)}`,
+        counted(findings.length, "finding", "findings"),
+        ...findings.flatMap((finding) => {
+          const lines = finding.lines ?? finding.section;
+          const location = `${displayPath(finding.file, options.root)}:${lines.first}${lines.last === lines.first ? "" : `–${lines.last}`}`;
+          return [
+            `## ${markdownText(location)}`,
+            finding.description,
+            `Level: **${finding.level}** · Confidence: ${finding.probability} · Threshold: ${finding.threshold}${finding.context === undefined ? "" : ` · Context: ${finding.context}`}`,
+            ...(lacksContext(finding, sufficiencyThreshold)
+              ? [
+                  `> Warning: this file may not show enough to check this rule (context below ${sufficiencyThreshold}). Add missing context with an \`@adhere\` note.`,
+                ]
+              : []),
+            `Excerpt starting at line ${finding.excerpt.start}:`,
+            fenced(finding.excerpt.lines.join("\n")),
+            ...[finding.examples.good, finding.examples.bad].flatMap((example) =>
+              example === undefined ? [] : [`### ${example.word}`, fenced(example.code.trim())],
+            ),
+          ];
+        }),
+      ].join("\n\n"),
+    ),
+    "## Run summary",
+    ...summary(result).map((line) => serialize(line, false)),
+    ...blockedFiles(result, options.root)
+      .filter((line) => line.length > 0)
+      .map((line) => serialize(line, false)),
+  ].join("\n\n");
+};
+
+/** One file per violated rule in each requested format, with run counts retained as context. */
+export const renderRuleReports = (
+  result: AuditResult,
+  formats: { readonly json: boolean; readonly md: boolean },
+  options: RenderOptions = {},
+): ReadonlyMap<string, string> => {
+  const groups = Map.groupBy(result.findings, (finding) =>
+    shownId({ id: finding.rule, preset: finding.preset }),
+  );
+  return new Map(
+    Array.from(groups).flatMap(([id, findings]): Array<[string, string]> => {
+      const name = encodeURIComponent(id);
+      const report = { ...result, findings };
+      const files: Array<[string, string]> = [];
+      if (formats.json) files.push([`${name}.json`, `${renderJson(report, options)}\n`]);
+      if (formats.md) files.push([`${name}.md`, `${renderMarkdown(report, options)}\n`]);
+      return files;
+    }),
+  );
+};
+
 /**
  * What a run will do, before it asks: the files and rules found, the checks
  * between them and how many the cache answers, then what judging the rest

package/src/workspaces.test.ts

@@ -1,5 +1,10 @@
 import { describe, expect, it } from "vite-plus/test";
-import { workspacePackagesIn } from "./workspaces.ts";
+import {
+  dependentFilesIn,
+  importSpecifiersIn,
+  packageOf,
+  workspacePackagesIn,
+} from "./workspaces.ts";
 
 const catalog = {
   "@repo/foo": "packages/foo",
@@ -71,3 +76,34 @@ describe("file-local workspace packages", () => {
     expect(workspacePackagesIn("import(`@repo/foo/${name}`)", catalog)).toEqual({});
   });
 });
+
+describe("dependent files", () => {
+  it("resolves relative specifiers to known files as written, by emitted extension, added extension, or index", () => {
+    const dependents = dependentFilesIn(
+      new Map([
+        ["src/a.ts", importSpecifiersIn('import { b } from "./b.js"; export * from "./lib";')],
+        ["src/b.ts", importSpecifiersIn('import "../util"; import x from "pkg/./b";')],
+        [
+          "src/lib/index.ts",
+          importSpecifiersIn('const self = require("./index.ts"); import("..");'),
+        ],
+        ["src/c.tsx", importSpecifiersIn('import { b } from "./b"; import "./missing";')],
+        ["util.ts", []],
+        ["src/index.ts", []],
+      ]),
+    );
+    expect(Object.fromEntries(dependents)).toEqual({
+      "src/b.ts": ["src/a.ts", "src/c.tsx"],
+      "src/lib/index.ts": ["src/a.ts"],
+      "util.ts": ["src/b.ts"],
+      "src/index.ts": ["src/lib/index.ts"],
+    });
+  });
+
+  it("places a file in the deepest package directory that holds it", () => {
+    const catalog = { outer: "packages/outer", inner: "packages/outer/inner", other: "packages/o" };
+    expect(packageOf("packages/outer/inner/src/a.ts", catalog)).toBe("inner");
+    expect(packageOf("packages/outer/src/a.ts", catalog)).toBe("outer");
+    expect(packageOf("packages/outer-x/a.ts", catalog)).toBeUndefined();
+  });
+});

package/src/workspaces.ts

@@ -1,4 +1,5 @@
 import { Effect, FileSystem, Path } from "effect";
+import { posix } from "node:path";
 import { scan, type Token } from "#highlight.ts";
 
 /** A workspace's packages: each one's name, with its directory from the root. */
@@ -38,15 +39,12 @@ const specifierOf = (token: Token | undefined, templates = false): string | unde
 };
 
 /**
- * Only packages named by this file's literal imports, type imports, re-exports,
- * or import/require calls. Tokens keep comments, strings, regexes, and templates
- * opaque; computed modules and imports inside template substitutions are not resolved.
- * Subpaths identify their canonical package, without walking the global catalog.
+ * Every module specifier named by this file's literal imports, type imports,
+ * re-exports, or import/require calls, once each, in order. Tokens keep comments,
+ * strings, regexes, and templates opaque; computed modules and imports inside
+ * template substitutions are not resolved.
  */
-export const workspacePackagesIn = (
-  code: string,
-  catalog: WorkspacePackages,
-): WorkspacePackages => {
+export const importSpecifiersIn = (code: string): ReadonlyArray<string> => {
   const tokens = scan(code).flatMap((token) => {
     if (token.kind === "comment" || token.text.trim() === "") return [];
     // Highlighting groups punctuation; module clauses need individual delimiters.
@@ -54,11 +52,9 @@ export const workspacePackagesIn = (
       ? [...token.text].map((text): Token => ({ text }))
       : [token];
   });
-  const names = new Set<string>();
+  const specifiers = new Set<string>();
   const keep = (specifier: string | undefined) => {
-    if (specifier === undefined || specifier.startsWith(".") || specifier.startsWith("/")) return;
-    const name = specifier.split("/", specifier.startsWith("@") ? 2 : 1).join("/");
-    if (Object.hasOwn(catalog, name)) names.add(name);
+    if (specifier !== undefined) specifiers.add(specifier);
   };
   for (const [index, token] of tokens.entries()) {
     if (tokens[index - 1]?.text === ".") continue;
@@ -91,6 +87,23 @@ export const workspacePackagesIn = (
       if (part.kind === "keyword" && !["type", "as", "from"].includes(part.text)) break;
     }
   }
+  return [...specifiers];
+};
+
+/**
+ * Only packages this file imports, by `importSpecifiersIn`. Subpaths identify
+ * their canonical package, without walking the global catalog.
+ */
+export const workspacePackagesIn = (
+  code: string,
+  catalog: WorkspacePackages,
+): WorkspacePackages => {
+  const names = new Set<string>();
+  for (const specifier of importSpecifiersIn(code)) {
+    if (specifier.startsWith(".") || specifier.startsWith("/")) continue;
+    const name = specifier.split("/", specifier.startsWith("@") ? 2 : 1).join("/");
+    if (Object.hasOwn(catalog, name)) names.add(name);
+  }
   return Object.fromEntries([...names].sort().map((name) => [name, catalog[name]!]));
 };
 
@@ -230,3 +243,99 @@ export const workspacePackagesOf = Effect.fn("workspacePackagesOf")(function* (r
     named.flat().sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
   ) as WorkspacePackages;
 });
+
+const DEPENDENCY_FIELDS = [
+  "dependencies",
+  "devDependencies",
+  "peerDependencies",
+  "optionalDependencies",
+] as const;
+
+/**
+ * For each workspace package, the other workspace packages whose package.json
+ * depends on it, by name with directory, sorted. A package no other one names
+ * is left out.
+ */
+export const workspaceDependentsOf = Effect.fn("workspaceDependentsOf")(function* (
+  root: string,
+  catalog: WorkspacePackages,
+) {
+  const fs = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const dependents = new Map<string, Map<string, string>>();
+  // Sequential over the sorted catalog, so each package's dependents are inserted sorted.
+  yield* Effect.forEach(Object.entries(catalog), ([name, directory]) =>
+    Effect.map(
+      fs
+        .readFileString(path.join(root, directory, "package.json"))
+        .pipe(Effect.orElseSucceed(() => "")),
+      (text) => {
+        const manifest = parsed(text) as Readonly<Record<string, unknown>> | undefined;
+        for (const field of DEPENDENCY_FIELDS) {
+          const named = manifest?.[field];
+          if (named === null || typeof named !== "object") continue;
+          for (const dependency of Object.keys(named)) {
+            if (dependency === name || !Object.hasOwn(catalog, dependency)) continue;
+            const found = dependents.get(dependency) ?? new Map<string, string>();
+            dependents.set(dependency, found.set(name, directory));
+          }
+        }
+      },
+    ),
+  );
+  return Object.fromEntries(
+    [...dependents].map(([name, found]) => [name, Object.fromEntries(found)]),
+  ) as Readonly<Record<string, WorkspacePackages>>;
+});
+
+/** TypeScript source extensions an import resolves to, in the order tried. */
+const SOURCE_EXTENSIONS = [".ts", ".tsx", ".mts", ".cts"] as const;
+/** The source extensions an emitted extension in a specifier stands for. */
+const EMITTED: Readonly<Record<string, ReadonlyArray<string>>> = {
+  ".js": [".ts", ".tsx"],
+  ".jsx": [".tsx"],
+  ".mjs": [".mts"],
+  ".cjs": [".cts"],
+};
+
+/** The paths a relative specifier can name, most specific first. */
+const candidatesOf = (target: string): ReadonlyArray<string> => {
+  const extension = posix.extname(target);
+  const emitted = EMITTED[extension] ?? [];
+  const stem = target.slice(0, target.length - extension.length);
+  return [
+    target,
+    ...emitted.map((source) => `${stem}${source}`),
+    ...SOURCE_EXTENSIONS.map((source) => `${target}${source}`),
+    ...SOURCE_EXTENSIONS.map((source) => `${target}/index${source}`),
+  ];
+};
+
+/**
+ * For each file, the files that import it by a relative specifier, sorted.
+ * Keys and values are `/`-separated paths from one root, as `imports` gives
+ * them; a specifier resolves only to a file `imports` has, by the first of its
+ * candidates found: as written, with `.js` as `.ts`, with a source extension
+ * added, then as a directory's index. Package and path-alias imports do not count.
+ */
+export const dependentFilesIn = (
+  imports: ReadonlyMap<string, ReadonlyArray<string>>,
+): ReadonlyMap<string, ReadonlyArray<string>> => {
+  const dependents = new Map<string, Set<string>>();
+  for (const [importer, specifiers] of imports) {
+    for (const specifier of specifiers) {
+      if (specifier !== "." && specifier !== ".." && !/^\.\.?\//.test(specifier)) continue;
+      const target = posix.join(posix.dirname(importer), specifier);
+      const found = candidatesOf(target).find((candidate) => imports.has(candidate));
+      if (found === undefined || found === importer) continue;
+      dependents.set(found, (dependents.get(found) ?? new Set()).add(importer));
+    }
+  }
+  return new Map([...dependents].map(([file, found]) => [file, [...found].sort()]));
+};
+
+/** The workspace package a `/`-separated path from the root lies in: the one with the deepest directory holding it. */
+export const packageOf = (file: string, catalog: WorkspacePackages): string | undefined =>
+  Object.entries(catalog)
+    .filter(([, directory]) => file.startsWith(`${directory}/`))
+    .sort(([, a], [, b]) => b.length - a.length)[0]?.[0];