@drkmttr/adhere 0.18.0 → 0.21.2

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);
@@ -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];