@drkmttr/adhere 0.15.0 → 0.18.0

package/src/workflows/format.ts

@@ -288,9 +288,10 @@ const legend = (
   result: AuditResult,
   threshold: number,
   sufficiencyThreshold: number,
+  answerer = "Jev",
 ): ReadonlyArray<Line> => {
   const rows = [
-    ["confidence", cellsOf(threshold), "Jev's probability that the file breaks the rule"],
+    ["confidence", cellsOf(threshold), `${answerer}'s probability that the file breaks the rule`],
     [
       "context",
       cellsOf(sufficiencyThreshold),
@@ -370,6 +371,8 @@ export interface RenderOptions {
   readonly threshold?: number;
   /** Below this, a finding's context is low and it carries a warning. Defaults to 0.6. */
   readonly sufficiencyThreshold?: number;
+  /** The model of the config's provider, which the legend names in place of Jev. */
+  readonly provider?: string;
 }
 
 /**
@@ -384,7 +387,12 @@ export const render = (result: AuditResult, options: RenderOptions = {}): Readon
       ...frame(finding, options.root, sufficiencyThreshold),
       [],
     ]),
-    ...legend(result, options.threshold ?? DEFAULT_THRESHOLD, sufficiencyThreshold),
+    ...legend(
+      result,
+      options.threshold ?? DEFAULT_THRESHOLD,
+      sufficiencyThreshold,
+      options.provider,
+    ),
     ...summary(result),
     ...blockedFiles(result, options.root),
   ].map((line) => serialize(line, options.color === true));
@@ -444,51 +452,100 @@ const costLine = (plan: AuditPlan): string => {
   return `Those carry about ${tokensSaid(plan.tokens)} input tokens${priced}, and more for locating findings.`;
 };
 
+/** Who answers the plan's requests: Jev, or the model of the config's provider. */
+const answererOf = (plan: AuditPlan): string => plan.provider ?? "Jev";
+
+const NATIVE_READS_CAVEAT =
+  "Estimates cover only code and workspace-package context; symbol/reference input, possible extra request splits, and size-skips are determined at send time.";
+
 export const describePlan = (plan: AuditPlan, limits: RunLimits = {}): ReadonlyArray<string> => {
+  const native = plan.nativeReads === undefined ? [] : [NATIVE_READS_CAVEAT];
+  const locating = plan.cachedLocateRequests ?? 0;
   const cached = plan.cached > 0 ? `, ${plan.cached} cached` : "";
   const skipped =
     plan.skipped > 0 ? `, ${counted(plan.skipped, "file", "files")} too long to judge` : "";
   const matching = (limits.filter?.length ?? 0) > 0 ? " matching the filter" : "";
   const found = `${counted(plan.files.length, "file", "files")}${matching} and ${counted(plan.rules, "rule", "rules")}: ${counted(plan.checks, "check", "checks")}${cached}${skipped}.`;
-  const pending = plan.checks - plan.cached;
   const waiting =
     plan.deferred > 0
-      ? ` The other ${plan.deferred} ${plan.deferred === 1 ? "waits" : "wait"} for a later run.`
+      ? ` ${counted(plan.deferred, "file", "files")} ${plan.deferred === 1 ? "waits" : "wait"} for a later run.`
       : "";
+  if (plan.planOnly === true) {
+    return [
+      found,
+      "Plan only (--limit 0): no native reads will be resolved and no requests will be sent.",
+      ...(plan.deferred > 0
+        ? [`${counted(plan.deferred, "file", "files")} left for a later run.`]
+        : []),
+      ...native,
+    ];
+  }
+  if (plan.requests === 0 && locating > 0) {
+    const pace =
+      limits.rpm === undefined
+        ? ""
+        : ` At ${limits.rpm} a minute, they take about ${durationAt(locating, limits.rpm)}.`;
+    return [
+      found,
+      `Locating cached findings takes an estimated ${counted(locating, "request", "requests")} to ${answererOf(plan)}.${pace}${waiting}`,
+      "Locating input tokens and cost are not estimated.",
+      ...native,
+    ];
+  }
   if (plan.requests === 0) {
     const none =
       plan.deferred > 0
         ? plan.deferred === 1
-          ? "The limit leaves the 1 unjudged check for a later run."
-          : `The limit leaves all ${plan.deferred} unjudged checks for a later run.`
+          ? "The limit leaves 1 file needing requests for a later run."
+          : `The limit leaves all ${plan.deferred} files needing requests for a later run.`
         : plan.checks === 0
           ? "Nothing to judge."
           : "The cache answers every check.";
-    return [found, none];
+    return [found, none, ...native];
   }
-  const judging = pending - plan.deferred;
-  const rest =
-    plan.deferred > 0
-      ? `${judging} of ${plan.cached > 0 ? `the other ${pending}` : "them"}`
-      : plan.cached > 0
-        ? `the other ${pending}`
-        : "them";
+  const judging = plan.files.filter(
+    (file) => !file.skipped && !file.deferred && Object.keys(file.pending).length > 0,
+  ).length;
+  const rest = counted(judging, "file", "files");
   const pace =
     limits.rpm === undefined
       ? ""
-      : ` At ${limits.rpm} a minute, they take about ${durationAt(plan.requests, limits.rpm)}.`;
+      : ` At ${limits.rpm} a minute, they take about ${durationAt(plan.requests + locating, limits.rpm)}.`;
   return [
     found,
-    `Judging ${rest} takes ${counted(plan.requests, "request", "requests")} to Jev, plus 1 or more for each file with a finding.${pace}${waiting}`,
+    `Judging ${rest} takes ${plan.nativeReads === undefined ? "" : "an estimated "}${counted(plan.requests, "request", "requests")} to ${answererOf(plan)}, plus 1 or more for each file with a finding.${pace}${waiting}`,
     ...(plan.tokens > 0 ? [costLine(plan)] : []),
+    ...(locating > 0
+      ? [
+          `Known cached findings need an estimated ${counted(locating, "request", "requests")} to locate; locating input tokens and cost are not included.`,
+        ]
+      : []),
+    ...native,
   ];
 };
 
 /** The question before a run sends anything. */
 export const sendQuestion = (plan: AuditPlan): string => {
+  if (plan.planOnly === true) {
+    return "Plan only (--limit 0): no native reads will be resolved and no requests will be sent.";
+  }
   const cost = costOf(plan);
   const priced = cost === undefined || plan.tokens === 0 ? "" : `, ${dollars(cost)}`;
-  return `Send ${counted(plan.requests, "request", "requests")} to Jev${priced}?`;
+  const estimate = plan.nativeReads === undefined ? "" : "an estimated ";
+  const caveat = plan.nativeReads === undefined ? "" : `${NATIVE_READS_CAVEAT} `;
+  const locating = plan.cachedLocateRequests ?? 0;
+  if (locating > 0) {
+    const work =
+      plan.requests === 0
+        ? "to locate cached findings"
+        : `(${counted(plan.requests, "request", "requests")} judging, ${counted(locating, "request", "requests")} locating cached findings)`;
+    const costs =
+      plan.requests === 0 || cost === undefined || plan.tokens === 0
+        ? "Locating input tokens and cost are not estimated. "
+        : `Judging costs ${dollars(cost)}; locating input tokens and cost are not estimated. `;
+    return `${caveat}${costs}Send an estimated ${counted(plan.requests + locating, "request", "requests")} to ${answererOf(plan)} ${work}?`;
+  }
+  return `${caveat}Send ${estimate}${counted(plan.requests, "request", "requests")} to ${answererOf(plan)}${priced}?`;
 };
 
 /** A run's progress so far: every file it finished, with the requests and findings they added up to. */

package/src/workspaces.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from "vite-plus/test";
+import { workspacePackagesIn } from "./workspaces.ts";
+
+const catalog = {
+  "@repo/foo": "packages/foo",
+  "@repo/types": "packages/types",
+  "@repo/reexport": "packages/reexport",
+  "@repo/dynamic": "packages/dynamic",
+  legacy: "packages/legacy",
+};
+
+describe("file-local workspace packages", () => {
+  it("keeps static and type imports and re-exports under canonical package names", () => {
+    const code = `
+      import Foo, { value } from "@repo/foo/utils";
+      import type { Model } from "@repo/types";
+      import type DefaultModel from "@repo/types/model";
+      import { type OtherModel } from "@repo/types/other";
+      import * as Types from "@repo/types";
+      import "legacy/setup";
+      export { value as renamed } from "@repo/reexport/value";
+      export type { Shape } from "@repo/reexport/types";
+      export type * from "@repo/reexport";
+      export * as all from "@repo/reexport/all";
+      import Missing from "@repo/foobar";
+      import External from "external";
+      import Relative from "../@repo/foo";
+    `;
+    expect(workspacePackagesIn(code, catalog)).toEqual({
+      "@repo/foo": "packages/foo",
+      "@repo/types": "packages/types",
+      "@repo/reexport": "packages/reexport",
+      legacy: "packages/legacy",
+    });
+    expect(workspacePackagesIn("export const value = 1;", catalog)).toEqual({});
+    expect(catalog).toHaveProperty("@repo/dynamic");
+  });
+
+  it("ignores import text in comments, strings, regexes, and templates, and computed modules", () => {
+    const code = `
+      // import Foo from "@repo/foo";
+      /* export * from "@repo/reexport"; */
+      const quoted = 'import type { Model } from "@repo/types";';
+      const pattern = /require("legacy")/;
+      const template = \`import("@repo/dynamic")\`;
+      api.require("legacy");
+      api.import("@repo/foo");
+      api?.require("@repo/types");
+      import(moduleName);
+      require("@repo/foo/" + name);
+      import("@repo/dynamic" + suffix);
+    `;
+    expect(workspacePackagesIn(code, catalog)).toEqual({});
+    expect(workspacePackagesIn('import "@repo/foo";', {})).toEqual({});
+  });
+
+  it("reads escaped specifiers and literal import/require calls without a compiler", () => {
+    const code = String.raw`
+      import type { Model } from "\u0040repo\u002ftypes/model";
+      export * from '\x40repo/reexport';
+      const dynamic = import /* loader */ ("@repo/dynamic/utils", { with: { type: "json" } });
+      type Model = import("@repo/types").Model;
+      const legacy = require /* loader */ ('legacy/subpath',);
+      import Legacy = require("legacy");
+      const foo = require("\u{40}repo\/foo");
+    `;
+    expect(workspacePackagesIn(code, catalog)).toEqual(catalog);
+    expect(workspacePackagesIn("import(`@repo/foo/utils`)", catalog)).toEqual({
+      "@repo/foo": "packages/foo",
+    });
+    expect(workspacePackagesIn("import(`@repo/foo/${name}`)", catalog)).toEqual({});
+  });
+});

package/src/workspaces.ts

@@ -1,8 +1,99 @@
 import { Effect, FileSystem, Path } from "effect";
+import { scan, type Token } from "#highlight.ts";
 
 /** A workspace's packages: each one's name, with its directory from the root. */
 export type WorkspacePackages = Readonly<Record<string, string>>;
 
+const ESCAPES: Readonly<Record<string, string>> = {
+  n: "\n",
+  r: "\r",
+  t: "\t",
+  b: "\b",
+  f: "\f",
+  v: "\v",
+  "0": "\0",
+};
+
+/** Decode a quoted module name without evaluating code; only calls accept plain templates. */
+const specifierOf = (token: Token | undefined, templates = false): string | undefined => {
+  if (token?.kind !== "string") return undefined;
+  const quote = token.text[0];
+  if (quote !== '"' && quote !== "'" && !(templates && quote === "`")) return undefined;
+  if (token.text.at(-1) !== quote) return undefined;
+  const body = token.text.slice(1, -1);
+  if (quote === "`" && /(?:^|[^\\])(?:\\\\)*\$\{/.test(body)) return undefined;
+  return body.replace(
+    /\\(u\{[\da-fA-F]{1,6}\}|u[\da-fA-F]{4}|x[\da-fA-F]{2}|[\s\S])/g,
+    (_, escaped: string) => {
+      if (/^(?:u\{|u[\da-fA-F]{4}$|x[\da-fA-F]{2}$)/.test(escaped)) {
+        const point = Number.parseInt(
+          escaped.startsWith("u{") ? escaped.slice(2, -1) : escaped.slice(1),
+          16,
+        );
+        return point <= 0x10ffff ? String.fromCodePoint(point) : `\\${escaped}`;
+      }
+      return ESCAPES[escaped] ?? escaped;
+    },
+  );
+};
+
+/**
+ * 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.
+ */
+export const workspacePackagesIn = (
+  code: string,
+  catalog: WorkspacePackages,
+): WorkspacePackages => {
+  const tokens = scan(code).flatMap((token) => {
+    if (token.kind === "comment" || token.text.trim() === "") return [];
+    // Highlighting groups punctuation; module clauses need individual delimiters.
+    return token.kind === undefined && /^[^\w$]+$/.test(token.text)
+      ? [...token.text].map((text): Token => ({ text }))
+      : [token];
+  });
+  const names = 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);
+  };
+  for (const [index, token] of tokens.entries()) {
+    if (tokens[index - 1]?.text === ".") continue;
+    const next = tokens[index + 1];
+    if ((token.text === "import" || token.text === "require") && next?.text === "(") {
+      const end = tokens[index + 3]?.text;
+      if (end === ")" || end === ",") {
+        keep(specifierOf(tokens[index + 2], true));
+      }
+      continue;
+    }
+    if (token.kind !== "keyword" || (token.text !== "import" && token.text !== "export")) continue;
+    if (token.text === "import" && next?.kind === "string") {
+      keep(specifierOf(next));
+      continue;
+    }
+    const head = next?.text === "type" ? tokens[index + 2]?.text : next?.text;
+    if (token.text === "export" && head !== "{" && head !== "*") continue;
+    let depth = 0;
+    for (let at = index + 1; at < tokens.length; at += 1) {
+      const part = tokens[at]!;
+      if ([";", "=", "(", ")", "."].includes(part.text)) break;
+      if (part.text === "{") depth += 1;
+      else if (part.text === "}") depth -= 1;
+      if (depth !== 0) continue;
+      if (part.text === "from" && tokens[at + 1]?.kind === "string") {
+        keep(specifierOf(tokens[at + 1]));
+        break;
+      }
+      if (part.kind === "keyword" && !["type", "as", "from"].includes(part.text)) break;
+    }
+  }
+  return Object.fromEntries([...names].sort().map((name) => [name, catalog[name]!]));
+};
+
 /** What JSON text holds, or nothing when it is not JSON. */
 const parsed = (text: string): unknown => {
   try {