@drkmttr/adhere 0.9.5 → 0.10.0

package/src/suppress.ts

@@ -0,0 +1,113 @@
+import { type Range, statementFrom } from "#excerpt.ts";
+import { scan } from "#highlight.ts";
+
+/**
+ * What a file's `adhere-ignore` comments suppress. `// adhere-ignore <rules>
+ * -- <reason>` on a line of its own suppresses the rules it names in the
+ * statement that starts on the next line of code, wherever in it Jev points;
+ * at the end of a line of code, in the statement that starts on that line, or
+ * the line alone. `// adhere-ignore-file <rules> -- <reason>` suppresses them
+ * in the whole file, which they then do not judge. Rules are named as a report
+ * names them, separated by commas.
+ */
+export interface Suppressions {
+  /** Rules suppressed in the whole file. */
+  readonly file: ReadonlySet<string>;
+  /** Rules suppressed over the lines of one statement. */
+  readonly statements: ReadonlyArray<Range & { readonly rules: ReadonlySet<string> }>;
+}
+
+export const NO_SUPPRESSIONS: Suppressions = { file: new Set(), statements: [] };
+
+/** A directive's comment: whether it covers the file, then what follows, up to a block comment's end. */
+const DIRECTIVE = /^(?:\/\/|\/\*)\s*adhere-ignore(-file)?\s+(.*?)\s*(?:\*\/)?$/s;
+
+/** An `adhere-ignore` comment: where it is, and the rules it names. */
+interface Directive {
+  readonly line: number;
+  /** At the end of a line of code, rather than on a line of its own. */
+  readonly trailing: boolean;
+  /** `adhere-ignore-file`, for the whole file. */
+  readonly file: boolean;
+  readonly rules: ReadonlySet<string>;
+}
+
+/** The rules a directive names, before any ` -- ` and its reason. None if it is not a directive. */
+const directiveOf = (comment: string): Pick<Directive, "file" | "rules"> | undefined => {
+  const match = DIRECTIVE.exec(comment);
+  const named = (match?.[2] ?? "").split(/(?:^|\s)--(?:\s|$)/)[0] ?? "";
+  const rules = named.split(/[\s,]+/).filter((rule) => rule.length > 0);
+  return match === null || rules.length === 0
+    ? undefined
+    : { file: match[1] !== undefined, rules: new Set(rules) };
+};
+
+/** Whether a line holds nothing a statement could start with: blank, or a comment. */
+const isQuiet = (line: string): boolean => {
+  const text = line.trim();
+  return (
+    text.length === 0 || text.startsWith("//") || text.startsWith("/*") || text.startsWith("*")
+  );
+};
+
+/** The statement that starts on the first line of code after `line`, or that line alone. */
+const statementAfter = (lines: ReadonlyArray<string>, line: number): Range | undefined => {
+  for (let next = line + 1; next <= lines.length; next++) {
+    if (isQuiet(lines[next - 1] ?? "")) continue;
+    return statementFrom(lines, next) ?? { first: next, last: next };
+  }
+  return undefined;
+};
+
+/**
+ * A file's lines with its `adhere-ignore` comments blanked, each line keeping
+ * its number, so Jev never reads them, and what they suppress.
+ */
+export const suppressionsOf = (
+  lines: ReadonlyArray<string>,
+): { readonly lines: ReadonlyArray<string>; readonly suppressions: Suppressions } => {
+  const code = lines.join("\n");
+  if (!code.includes("adhere-ignore")) return { lines, suppressions: NO_SUPPRESSIONS };
+  const tokens = scan(code);
+  const found: Array<Directive> = [];
+  const kept: Array<string> = [];
+  let line = 1;
+  // Whether code comes before the current token on its line.
+  let afterCode = false;
+  for (const token of tokens) {
+    const directive = token.kind === "comment" ? directiveOf(token.text) : undefined;
+    if (directive !== undefined) found.push({ line, trailing: afterCode, ...directive });
+    kept.push(directive === undefined ? token.text : token.text.replace(/[^\n]/g, ""));
+    const breaks = token.text.split("\n").length - 1;
+    const tail = token.text.slice(token.text.lastIndexOf("\n") + 1);
+    if (breaks > 0) afterCode = false;
+    if (token.kind !== "comment" && tail.trim().length > 0) afterCode = true;
+    line += breaks;
+  }
+  // What the highlighter could not read, if anything, stays as it was.
+  const read = tokens.reduce((length, token) => length + token.text.length, 0);
+  const cleaned = (kept.join("") + code.slice(read))
+    .split("\n")
+    .map((text, index) => (text === lines[index] ? text : text.trimEnd()));
+  const statements = found.flatMap(({ line: at, trailing, file, rules }) => {
+    if (file) return [];
+    const range = trailing
+      ? (statementFrom(cleaned, at) ?? { first: at, last: at })
+      : statementAfter(cleaned, at);
+    return range === undefined ? [] : [{ ...range, rules }];
+  });
+  return {
+    lines: cleaned,
+    suppressions: {
+      file: new Set(found.filter(({ file }) => file).flatMap(({ rules }) => [...rules])),
+      statements,
+    },
+  };
+};
+
+/** Whether a file's comments suppress `rule`, named as a report names it, at `line`. */
+export const suppresses = (suppressions: Suppressions, rule: string, line: number): boolean =>
+  suppressions.file.has(rule) ||
+  suppressions.statements.some(
+    (statement) => statement.rules.has(rule) && statement.first <= line && line <= statement.last,
+  );

package/src/workflows/audit.ts

@@ -1,4 +1,5 @@
-import { type Examples, examplesOf, type Rule, type RuleId } from "#config.ts";
+import { isNote, withoutComments } from "#comments.ts";
+import { type Examples, examplesOf, type Level, type Rule, type RuleId } from "#config.ts";
 import { type Excerpt, excerptOf } from "#excerpt.ts";
 import type { ScannedFile, WalkUnavailable } from "#models/Audit.ts";
 import { AdhereConfig } from "#services/AdhereConfig.ts";
@@ -20,7 +21,8 @@ import { SourceWalker } from "#services/SourceWalker.ts";
 import { clearingStatus, counted, countOf, Status } from "#services/Status.ts";
 import { SAMPLE, tallyKeyOf } from "#mechanical.ts";
 import { priceOf } from "#pricing.ts";
-import { applicableRules } from "#rules.ts";
+import { applicableRules, judgesFile, shownId } from "#rules.ts";
+import { NO_SUPPRESSIONS, suppresses, type Suppressions, suppressionsOf } from "#suppress.ts";
 import { type Crypto, Duration, Effect, Record, Result, Semaphore } from "effect";
 
 export interface Finding {
@@ -34,8 +36,17 @@ export interface Finding {
   /** The code around `line` the report shows. */
   readonly excerpt: Excerpt;
   readonly probability: number;
+  /** An error fails the run; a warning does not, unless `--deny-warnings`. */
+  readonly level: Level;
 }
 
+/** The findings that fail a run: its errors, and its warnings too when `denyWarnings`. */
+export const failing = (
+  findings: ReadonlyArray<Finding>,
+  denyWarnings = false,
+): ReadonlyArray<Finding> =>
+  denyWarnings ? findings : findings.filter((finding) => finding.level === "error");
+
 export interface AuditResult {
   readonly files: number;
   readonly judged: number;
@@ -46,6 +57,8 @@ export interface AuditResult {
   /** Files the firewall in front of Jev's API refused, with the ID to report each by. */
   readonly blocked: ReadonlyArray<Blocked>;
   readonly findings: ReadonlyArray<Finding>;
+  /** Findings an `adhere-ignore` comment covers, left out of `findings`. */
+  readonly suppressed: number;
 }
 
 /** A file whose request the firewall refused, and Cloudflare's Ray ID for the refusal. */
@@ -58,6 +71,8 @@ interface FileResult {
   readonly status: "judged" | "cached" | "skipped" | "waiting" | "blocked";
   readonly findings: ReadonlyArray<Finding>;
   readonly blocked?: Blocked;
+  /** Findings an `adhere-ignore` comment covers, left out of `findings`. */
+  readonly suppressed?: number;
 }
 
 interface PreparedRule {
@@ -85,7 +100,10 @@ const fingerprintOf = (model: string, rule: Rule) =>
 
 /** One file before anything is sent: its rules, and which of them the cache answers. */
 export interface FilePlan {
+  /** The file as Jev reads it: its comments taken out, unless the config keeps them. */
   readonly file: ScannedFile;
+  /** The file's lines as written, which the report's excerpts show. */
+  readonly original: ReadonlyArray<string>;
   /** Too long for Jev: counted, not judged. */
   readonly skipped: boolean;
   readonly hash: string;
@@ -97,11 +115,18 @@ export interface FilePlan {
   readonly deferred: number;
   /** Pending rules whose linter check question rides along on this file, each with its tally's key. */
   readonly sampled: Readonly<Record<RuleId, string>>;
+  /** What the file's `adhere-ignore` comments suppress. */
+  readonly suppressions: Suppressions;
 }
 
 /** A run worked out from the files, the rules, and the cache, before any request. */
 export interface AuditPlan {
   readonly files: ReadonlyArray<FilePlan>;
+  /**
+   * The content hashes of files read that no rule in the run judges, such as
+   * tests when no rule says `tests`: a prune keeps what other runs know of them.
+   */
+  readonly unjudged: ReadonlyArray<string>;
   /** Rules that apply to at least one file that is judged. */
   readonly rules: number;
   /** Every pair of a judged file and a rule that applies to it. */
@@ -165,7 +190,7 @@ const withinLimit = (planned: ReadonlyArray<FilePlan>, limit: number): ReadonlyA
 
 export interface PlanOptions {
   /** Judge at most this many checks; the rest wait for a later run. */
-  readonly limit?: number;
+  readonly limit?: number | undefined;
 }
 
 export const planAudit = (
@@ -178,13 +203,37 @@ export const planAudit = (
   Effect.gen(function* () {
     const config = yield* AdhereConfig;
     const cache = yield* AuditCache;
-    const files = yield* (yield* SourceWalker).files;
-
-    const configuredRules = (file: string) =>
-      config.scopedRules === undefined ? config.rules : applicableRules(file, config.scopedRules);
+    const walked = yield* (yield* SourceWalker).files;
+    // Each file as Jev reads it, each line keeping its number: its adhere-ignore comments blanked,
+    // and every other comment too but the @adhere notes, unless the config keeps comments. A
+    // comment changes nothing a file does, so it should not change the report.
+    const suppressed = new Map<string, Suppressions>();
+    const originals = new Map<string, ReadonlyArray<string>>();
+    const files = walked.map((file) => {
+      const { lines: directed, suppressions } = suppressionsOf(file.lines);
+      if (suppressions !== NO_SUPPRESSIONS) suppressed.set(file.path, suppressions);
+      const lines = config.includeComments === true ? directed : withoutComments(directed, isNote);
+      if (lines === file.lines) return file;
+      originals.set(file.path, file.lines);
+      return { ...file, lines };
+    });
+    const suppressionsIn = (file: ScannedFile) => suppressed.get(file.path) ?? NO_SUPPRESSIONS;
+    const originalOf = (file: ScannedFile) => originals.get(file.path) ?? file.lines;
+
+    // The rules that judge a file: those scoped to it, of which only the rules that say `tests`
+    // judge a test, and none that an adhere-ignore-file comment names.
+    const configuredRules = (file: ScannedFile) =>
+      Record.filter(
+        config.scopedRules === undefined
+          ? config.rules
+          : applicableRules(file.path, config.scopedRules),
+        (rule, id) =>
+          judgesFile(rule, file.test === true) &&
+          !suppressionsIn(file).file.has(shownId({ id, preset: presetOfRule.get(rule) })),
+      );
 
     const planFile = Effect.fn("audit.plan")(function* (file: ScannedFile) {
-      const rules = configuredRules(file.path);
+      const rules = configuredRules(file);
       // Hashed even when skipped, so a prune keeps what other runs know of its content.
       const hash = yield* sha256(file.lines.join("\n"));
       // Too long for Jev's context: skipped and counted, rather than refused mid-run.
@@ -199,6 +248,8 @@ export const planAudit = (
           pending: {},
           deferred: 0,
           sampled: {},
+          suppressions: suppressionsIn(file),
+          original: originalOf(file),
         } satisfies FilePlan;
       }
       const prepared: Record<RuleId, PreparedRule> = yield* Effect.forEach(
@@ -235,6 +286,8 @@ export const planAudit = (
         pending,
         deferred: 0,
         sampled: {},
+        suppressions: suppressionsIn(file),
+        original: originalOf(file),
       } satisfies FilePlan;
     });
 
@@ -305,7 +358,16 @@ export const planAudit = (
       });
     });
 
-    const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
+    // A file no rule judges, such as a test when no rule says `tests`, is not part of the run,
+    // but its content is: another run's rules may judge it.
+    const sorted = files
+      .filter((file) => !isEmpty(configuredRules(file)))
+      .sort((a, b) => a.path.localeCompare(b.path));
+    const unjudged = yield* Effect.forEach(
+      files.filter((file) => isEmpty(configuredRules(file))),
+      (file) => sha256(file.lines.join("\n")),
+      { concurrency: 8 },
+    );
     const status = yield* Status;
     let done = 0;
     const everything: ReadonlyArray<FilePlan> = yield* clearingStatus(
@@ -337,6 +399,7 @@ export const planAudit = (
       judged.reduce((sum, plan) => sum + count(plan), 0);
     return {
       files: planned,
+      unjudged,
       rules: new Set(judged.flatMap((plan) => Object.keys(plan.prepared))).size,
       checks: total((plan) => sizeOf(plan.prepared)),
       cached: total((plan) => sizeOf(plan.kept)),
@@ -386,6 +449,7 @@ export const executeAudit = (
     /** Judges and locates one file the plan left pending, with the requests that took. */
     const judgeFile = Effect.fn("audit.judgeFile")(function* ({
       file,
+      original,
       hash,
       prepared,
       kept,
@@ -416,9 +480,10 @@ export const executeAudit = (
       const {
         lines,
         blocked,
-      }: { readonly lines: Readonly<Record<RuleId, number>>; readonly blocked?: Blocked } = isEmpty(
-        flagged,
-      )
+      }: {
+        readonly lines: Readonly<Record<RuleId, number>>;
+        readonly blocked: Blocked | undefined;
+      } = isEmpty(flagged)
         ? { lines: {}, blocked: undefined }
         : yield* jev.locate(file.lines, rulesOf(flagged)).pipe(
             Effect.map((lines) => ({ lines, blocked: undefined })),
@@ -449,8 +514,9 @@ export const executeAudit = (
                   examples: examplesOf(k.rule),
                   file: file.path,
                   line: judgment.line,
-                  excerpt: excerptOf(file.lines, judgment.line),
+                  excerpt: excerptOf(original, judgment.line),
                   probability: judgment.probability,
+                  level: k.rule.level ?? "error",
                 },
               ]
             : [];
@@ -511,8 +577,22 @@ export const executeAudit = (
         ),
         Effect.annotateLogs("file", plan.file.path),
       );
-      yield* progress({ requests, findings: result.findings.length });
-      return result;
+      // A finding an adhere-ignore comment covers is left out of the report, and counted.
+      const shown = result.findings.filter(
+        (finding) =>
+          !suppresses(
+            plan.suppressions,
+            shownId({ id: finding.rule, preset: finding.preset }),
+            finding.line,
+          ),
+      );
+      if (shown.length < result.findings.length) {
+        yield* Effect.logDebug(
+          `${result.findings.length - shown.length} suppressed by adhere-ignore`,
+        ).pipe(Effect.annotateLogs("file", plan.file.path));
+      }
+      yield* progress({ requests, findings: shown.length });
+      return { ...result, findings: shown, suppressed: result.findings.length - shown.length };
     });
 
     const results = yield* Effect.forEach(plan.files, auditFile, { concurrency: 8 });
@@ -526,13 +606,15 @@ export const executeAudit = (
       waiting: count("waiting"),
       blocked: results.flatMap((result) => (result.blocked === undefined ? [] : [result.blocked])),
       findings: results.flatMap((result) => result.findings),
+      suppressed: results.reduce((sum, result) => sum + (result.suppressed ?? 0), 0),
     };
   });
 
 /**
  * Deletes from the cache the answers about content no file has anymore.
  * Answers to rules the run left out stay, since a run with other presets or
- * rules asks them. Only after a run that read every file; a run narrowed by
+ * rules asks them, and so do answers about files the run read but judged
+ * against no rule. Only after a run that read every file; a run narrowed by
  * `--filter` cannot tell what content the files it left out have.
  */
 export const pruneCache = Effect.fn("audit.prune")(function* (plan: AuditPlan) {
@@ -544,7 +626,7 @@ export const pruneCache = Effect.fn("audit.prune")(function* (plan: AuditPlan) {
   );
   const deleted = yield* cache.prune({
     // A file too long to judge counts: a run with shorter questions judges it.
-    hashes: new Set(plan.files.map((file) => file.hash)),
+    hashes: new Set([...plan.files.map((file) => file.hash), ...plan.unjudged]),
     tallies: new Set(tallies),
   });
   yield* Effect.logDebug(`cache pruned: ${deleted} ${deleted === 1 ? "file" : "files"} deleted`);

package/src/workflows/format.ts

@@ -9,6 +9,7 @@ import type { AuditPlan, AuditResult, FileDone, Finding } from "#workflows/audit
  */
 type Role =
   | "error"
+  | "warning"
   | "probability"
   | "description"
   | "path"
@@ -27,15 +28,16 @@ type Line = ReadonlyArray<Span>;
 /**
  * SGR parameters per role. The frame's are set colors, from the 256-color
  * palette (`38;5;N`) or truecolor (`38;2;R;G;B`), bold with a trailing `;1`,
- * and a dim line number. Of the header, only the `×` and the rule are red,
- * since a whole line of red is hard to read: the probability is an accent, and
- * the description a cool near-white, set here since a theme's own white can
- * be gray. The code's are the terminal's own colors (`3N`), so the user's
- * theme picks shades that read on its background; none is magenta, which
- * would run into the underline.
+ * and a dim line number. Of the header, only the `×` and the rule are red, or
+ * a warning's `⚠` and rule amber, since a whole line of red is hard to read:
+ * the probability is an accent, and the description a cool near-white, set
+ * here since a theme's own white can be gray. The code's are the terminal's
+ * own colors (`3N`), so the user's theme picks shades that read on its
+ * background; none is magenta, which would run into the underline.
  */
 const THEME: Readonly<Record<Role, string>> = {
   error: "38;2;164;20;71;1",
+  warning: "38;2;214;154;0;1",
   probability: "38;5;156",
   description: "38;2;230;230;255",
   path: "38;2;5;125;160;1",
@@ -90,9 +92,9 @@ const counted = (count: number, one: string, many: string): string =>
 
 const header = (finding: Finding): Line => [
   span("  "),
-  span("×", "error"),
+  span(finding.level === "warning" ? "⚠" : "×", finding.level),
   span(" "),
-  span(shownId({ id: finding.rule, preset: finding.preset }), "error"),
+  span(shownId({ id: finding.rule, preset: finding.preset }), finding.level),
   span(" ("),
   span(finding.probability.toFixed(2), "probability"),
   span("): "),
@@ -152,6 +154,13 @@ const frame = (finding: Finding, root: string | undefined): ReadonlyArray<Line>
   ...hint(finding),
 ];
 
+/** The findings counted by level: `1 error`, or `2 errors and 1 warning` once there are warnings. */
+const found = (findings: ReadonlyArray<Finding>): string => {
+  const warnings = findings.filter((finding) => finding.level === "warning").length;
+  const errors = counted(findings.length - warnings, "error", "errors");
+  return warnings === 0 ? errors : `${errors} and ${counted(warnings, "warning", "warnings")}`;
+};
+
 const summary = (result: AuditResult): ReadonlyArray<Line> => {
   const counts = [
     counted(result.files, "file", "files"),
@@ -160,11 +169,9 @@ const summary = (result: AuditResult): ReadonlyArray<Line> => {
     ...(result.skipped > 0 ? [`${result.skipped} skipped`] : []),
     ...(result.waiting > 0 ? [`${result.waiting} waiting`] : []),
     ...(result.blocked.length > 0 ? [`${result.blocked.length} blocked`] : []),
+    ...(result.suppressed > 0 ? [`${result.suppressed} suppressed`] : []),
   ];
-  return [
-    [span(`Found ${counted(result.findings.length, "error", "errors")}.`)],
-    [span(`${counts.join(", ")}.`)],
-  ];
+  return [[span(`Found ${found(result.findings)}.`)], [span(`${counts.join(", ")}.`)]];
 };
 
 /**
@@ -214,7 +221,7 @@ export const render = (result: AuditResult, options: RenderOptions = {}): Readon
 /** What a run was asked to keep to, for the plan to say. */
 export interface RunLimits {
   readonly filter?: ReadonlyArray<string>;
-  readonly rpm?: number;
+  readonly rpm?: number | undefined;
 }
 
 /** About how long `requests` take at `rpm`: seconds under a minute, minutes past it. */