@josueavalosjim/taste-check 0.5.2 → 0.7.0

package/README.md

@@ -290,6 +290,35 @@ inside a tool is somebody else's taste with the tool's authority behind it.
 Checklist lines are list items in your file; a heading or a paragraph is prose
 and is not judged.
 
+### Letting an agent carry the call
+
+A shell command is one way to reach a model and a poor one for an agent, which
+is already a model and can spawn a genuinely fresh context of its own instead
+of shelling out to a second copy of itself. So the judge splits in two:
+
+```bash
+taste-check judge --emit              # the prompt, and nothing else happens
+taste-check judge --verdict reply.json  # or - for stdin
+```
+
+`--emit` prints the prompt and stops. It still refuses when there are no
+screenshots or no checklist, because a prompt for nothing gets a confident
+verdict about nothing. `--verdict` checks the reply against the checklist
+exactly as the shell route does: every line answered once, no invented lines,
+valid verdicts. Taking the agent route does not buy a softer grading.
+
+`judge.command` is optional when you use this. There is a skill for it:
+
+```bash
+taste-check judge --skill    # prints the path to SKILL.md
+```
+
+Copy it wherever your agent keeps skills. It carries the mechanism, which is
+that the agent must not be the judge: it is reading the session that built the
+thing, and the reasoning that justified each choice is still sitting there
+ready to justify it again. It carries no design rules, for the same reason
+nothing else here does.
+
 ### What the exit code means here
 
 A verdict is an opinion, so a `fail` prints as a note and the command exits 0.
@@ -328,7 +357,7 @@ from anywhere.
 | `judge.checklist` | Your checklist file. List items are judged, prose is not. |
 | `judge.shots` | Screenshots to hand the judge. Matching nothing is a failure. |
 | `judge.shotCommand` | Optional command run first to produce those screenshots. |
-| `judge.command` | The model command. Prompt on stdin, image paths as arguments. |
+| `judge.command` | The model command. Prompt on stdin, image paths as arguments. Optional if an agent carries the call. |
 | `judge.failOn` | `"never"` (default) or `"fail"`. Whether a verdict blocks. |
 | `runtime.url` | The page to measure. A `file://` URL works. |
 | `runtime.endpoint` | An existing CDP endpoint. Given one, taste-check connects rather than launching, and never closes a browser it did not start. |
@@ -343,13 +372,52 @@ taste-check judge [options]   Ask a fresh-eyes judge about your screenshots
 
   -c, --config <path>   Config file (default: tastecheck.config.json)
       --only <name>     Run one check: contrast or treatments
-      --json            Machine-readable output
+      --format <kind>   text (default), json, or sarif
+      --json            Alias for --format json
       --version         Print the version
 ```
 
 Exit code is 1 if any check fails, 0 if every check ran and passed. The judge
 plays by the rules in its own section above.
 
+## SARIF
+
+```bash
+taste-check --format sarif > taste-check.sarif
+```
+
+Works on any of the three commands, and drops findings into a code scanning tab
+instead of a log nobody opens.
+
+```yaml
+- run: npx taste-check --format sarif > taste-check.sarif
+  continue-on-error: true
+- uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: taste-check.sarif
+```
+
+`continue-on-error` because the step exits 1 when something fails, and you
+still want the findings uploaded when it does.
+
+Two things make this worth having over a log.
+
+**Every finding points at the line you would edit.** A class points at the
+markup. A contrast failure points at the line in your token file where the
+foreground is declared, which is the half of a pair you usually end up moving.
+A judge verdict points at the line in your checklist. Findings with no file
+behind them, like a browser that would not start, point at the config, because
+that is where the rule was written.
+
+**Fingerprints are keyed to the content of the line, not its number.** Add an
+import at the top of a file and every finding below it stays the same alert
+rather than closing and reopening as a new one. Without that a code scanning
+tab fills with churn and people stop reading it.
+
+Levels follow the same rule the exit code does. Everything that gates the build
+is an `error`. A judge verdict is a `note`, or a `warning` if you set
+`failOn`, because it is an opinion either way.
+
 ## Where it sits next to other tools
 
 This is a small tool with a narrow claim, and several of these are better than
@@ -414,11 +482,6 @@ Not built. Written down so the shape is clear.
 
 **YAML configs**, once there is a reason to take on a parser.
 
-**SARIF output**, so findings land in a code scanning tab rather than only in
-a log.
-
-**A way to run the judge from an agent skill**, not only from a shell.
-
 **`lab()` and `lch()`**, which need the D50 white point and a chromatic
 adaptation step that `oklch()` does not. Completeness rather than reach, so
 it sits behind the others. Worth doing the same way when it happens: derive it,

package/bin/taste-check.mjs

@@ -7,9 +7,13 @@
  * exist, or scopes a pair to a theme that is not defined is a failure here,
  * not a quiet skip.
  */
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
 import { load } from '../src/config.mjs';
-import { judge, run, runtime } from '../src/index.mjs';
+import { gradeVerdict, judge, prepareJudge, run, runtime } from '../src/index.mjs';
 import { failed, toJson, toText } from '../src/report.mjs';
+import { toSarif } from '../src/sarif.mjs';
 
 const USAGE = `taste-check
 
@@ -20,17 +24,35 @@ const USAGE = `taste-check
 Options:
   -c, --config <path>   Config file (default: tastecheck.config.json)
       --only <name>     Run one check: contrast or treatments
-      --json            Machine-readable output
+      --emit            judge only: print the prompt and stop, for an agent
+                        to carry to a model itself
+      --verdict <path>  judge only: grade a reply from a file, or - for stdin
+      --skill           Print the path to the bundled agent skill
+      --format <kind>   text (default), json, or sarif
+      --json            Alias for --format json
   -h, --help            This
       --version         Print the version
 
 Exit code is 1 if any check fails, 0 if every check ran and passed.
 
+--format sarif writes SARIF 2.1.0 on stdout, for a code scanning tab:
+
+  taste-check --format sarif > taste-check.sarif
+
+Every finding points at the line you would edit to change it. A class points
+at the markup, a contrast failure at the line in your token file where the
+foreground is declared, a judge verdict at the line in your checklist.
+
 runtime is a separate command because it needs a browser and a server that
 is already up. It measures what is actually painted, compositing every
 background layer behind an element rather than stopping at the first opaque
 one, and it can put the page into a state first.
 
+An agent can carry the model call instead of a shell command. --emit prints
+the prompt and the images; the agent asks a fresh context and pipes the JSON
+back to --verdict -, which checks it against the checklist the same way. Run
+taste-check judge --skill for the bundled skill that wires this up.
+
 The judge is a separate command because it runs a model, and a model's
 verdict is not reproducible. Its verdicts print as notes and do not affect
 the exit code unless judge.failOn is set to "fail". Whether the judge ran
@@ -38,7 +60,15 @@ at all is a different question: no screenshots, a command that failed, or
 a reply that skipped a checklist line all exit 1 either way.`;
 
 function parseArgs(argv) {
-  const options = { config: 'tastecheck.config.json', only: null, json: false, command: 'check' };
+  const options = {
+    config: 'tastecheck.config.json',
+    only: null,
+    format: 'text',
+    command: 'check',
+    emit: false,
+    verdict: null,
+    skill: false,
+  };
   // One positional, and only in first position, so a stray argument is an
   // error rather than something silently ignored.
   if (argv[0] === 'judge' || argv[0] === 'runtime') {
@@ -49,7 +79,11 @@ function parseArgs(argv) {
     const arg = argv[i];
     const next = () => {
       const value = argv[i + 1];
-      if (value === undefined || value.startsWith('-')) throw new Error(`${arg} needs a value`);
+      // A bare "-" is a value, not a flag: it is the conventional name for
+      // stdin and --verdict takes it.
+      if (value === undefined || (value !== '-' && value.startsWith('-'))) {
+        throw new Error(`${arg} needs a value`);
+      }
       i += 1;
       return value;
     };
@@ -61,8 +95,16 @@ function parseArgs(argv) {
       if (options.only !== 'contrast' && options.only !== 'treatments') {
         throw new Error(`--only takes "contrast" or "treatments", not "${options.only}"`);
       }
-    } else if (arg === '--json') options.json = true;
-    else if (!arg.startsWith('-')) throw new Error(`unknown command "${arg}"`);
+    } else if (arg === '--json') options.format = 'json';
+    else if (arg === '--emit') options.emit = true;
+    else if (arg === '--skill') options.skill = true;
+    else if (arg === '--verdict') options.verdict = next();
+    else if (arg === '--format') {
+      options.format = next();
+      if (!['text', 'json', 'sarif'].includes(options.format)) {
+        throw new Error(`--format takes text, json or sarif, not "${options.format}"`);
+      }
+    } else if (!arg.startsWith('-')) throw new Error(`unknown command "${arg}"`);
     else throw new Error(`unknown option "${arg}"`);
   }
   return options;
@@ -85,15 +127,24 @@ if (options.help) {
   process.exit(0);
 }
 if (options.version) {
-  const { version } = JSON.parse(
-    await import('node:fs').then((fs) =>
-      fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
-    ),
-  );
+  const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
   console.log(version);
   process.exit(0);
 }
 
+// Printing the bundled skill needs no config: it is the same file every time.
+if (options.skill) {
+  console.log(fileURLToPath(new URL('../skills/taste-check-judge/SKILL.md', import.meta.url)));
+  process.exit(0);
+}
+
+for (const flag of ['emit', 'verdict']) {
+  if (options[flag] && options.command !== 'judge') {
+    die(`--${flag} applies to \`taste-check judge\`, not to ${options.command}`);
+  }
+}
+if (options.emit && options.verdict) die('--emit prints a prompt and --verdict grades a reply, so not both');
+
 const loaded = load(options.config);
 if (!loaded.ok) {
   console.error(`taste-check: ${options.config} could not be used:\n`);
@@ -109,8 +160,34 @@ if (options.command !== 'check' && !loaded.config[options.command]) {
   die(`${options.config} defines no "${options.command}" block.`);
 }
 
+// --emit stops before any model is involved, so it has no findings to report
+// and no exit code to earn. It still refuses to hand back a prompt when the
+// screenshots or the checklist are missing.
+if (options.emit) {
+  const prepared = prepareJudge(loaded.config.judge, loaded.dir);
+  if (!prepared.ok) {
+    console.log(toText([prepared.result]));
+    process.exit(1);
+  }
+  console.log(prepared.prompt);
+  process.exit(0);
+}
+
 let results;
-if (options.command === 'judge') results = judge(loaded.config, loaded.dir);
+if (options.verdict) {
+  const prepared = prepareJudge(loaded.config.judge, loaded.dir);
+  if (!prepared.ok) {
+    console.log(toText([prepared.result]));
+    process.exit(1);
+  }
+  let reply;
+  try {
+    reply = readFileSync(options.verdict === '-' ? 0 : options.verdict, 'utf8');
+  } catch {
+    die(`cannot read the verdict from ${options.verdict === '-' ? 'stdin' : options.verdict}`);
+  }
+  results = [gradeVerdict(reply, prepared, loaded.config.judge)];
+} else if (options.command === 'judge') results = judge(loaded.config, loaded.dir);
 else if (options.command === 'runtime') results = await runtime(loaded.config, loaded.dir);
 else results = run(loaded.config, loaded.dir, { only: options.only });
 
@@ -118,5 +195,12 @@ if (!results.length) {
   die(`nothing to run. ${options.config} defines no ${options.only ?? 'contrast or treatments'} check.`);
 }
 
-console.log(options.json ? toJson(results) : toText(results));
+if (options.format === 'sarif') {
+  const { version } = JSON.parse(
+    readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
+  );
+  console.log(toSarif(results, { version, configFile: options.config, configDir: loaded.dir }));
+} else {
+  console.log(options.format === 'json' ? toJson(results) : toText(results));
+}
 process.exit(failed(results) ? 1 : 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@josueavalosjim/taste-check",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Design review in CI with a line down the middle: measured checks that gate the build (WCAG contrast from your tokens or from a real rendered page, one-off values in your markup) and a fresh-eyes model judge whose verdicts stay advisory. Zero dependencies. Ships no design rules of its own.",
   "keywords": [
     "accessibility",
@@ -34,6 +34,7 @@
     "bin",
     "src",
     "schema",
+    "skills",
     "README.md",
     "LICENSE"
   ],

package/skills/taste-check-judge/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: taste-check-judge
+description: Run the taste-check fresh-eyes judge on a design, using a fresh subagent as the judge rather than a shell command. Use after building or changing a screen, when asked to review or critique a design, or on any request to run the taste gate. Requires a tastecheck.config.json with a judge block.
+---
+
+# taste-check judge
+
+You are the transport, not the judge.
+
+`taste-check` builds the prompt and checks the answer. You carry the prompt to a
+model and carry the reply back. The model you carry it to must not be you.
+
+## Why not you
+
+You are reading this inside a session that has context: what was built, what it
+was for, which tradeoffs were made and why. That context is exactly what
+disqualifies you from judging the result. The reasoning that justified each
+choice is still sitting here ready to justify it again, and a review that
+reaches for it is not a review.
+
+So the judge is a separate agent with none of it. That is the whole mechanism,
+and skipping it turns this into self-assessment with extra steps.
+
+## Steps
+
+**1. Produce the screenshots.** However this project does it. If the config has
+a `shotCommand`, the next step runs it for you.
+
+**2. Get the prompt.**
+
+```
+npx taste-check judge --emit
+```
+
+It prints the prompt, which already contains the framing and the user's
+checklist. It exits 1 and prints nothing usable if there are no screenshots or
+no checklist, which is deliberate: a judge with nothing to look at must not
+produce a verdict.
+
+**3. Ask a fresh agent.** Spawn a new general-purpose agent on the strongest
+reasoning tier available. Give it:
+
+- the prompt from step 2, verbatim
+- the screenshot files it names
+
+Give it nothing else. No summary of what changed. No statement of intent. No
+prior conversation. Do not mention which lines you expect to fail, do not say
+what you already fixed, and do not add a checklist item of your own. Every one
+of those turns the verdict into your opinion with a second signature on it.
+
+Ask it to reply with the JSON the prompt specifies and nothing else.
+
+**4. Grade the reply.**
+
+```
+npx taste-check judge --verdict reply.json
+```
+
+or pipe it on stdin with `-`. This checks the reply against the checklist:
+every line answered exactly once, no invented lines, valid verdicts. A judge
+that quietly drops the hardest line is the failure this catches.
+
+Exit code 1 means the judge could not run, or a verdict blocked under
+`failOn: "fail"`. Verdicts are otherwise advisory and print as notes.
+
+## Reporting back
+
+Report what the judge said, including the passes. Do not soften a `fail` and do
+not quietly drop an `unsure`.
+
+If you disagree with a verdict, say so as a disagreement and leave the verdict
+standing. "The judge flagged X, I think it is wrong because Y" is useful. Not
+mentioning X is not.
+
+Fix what you can, then run the whole thing again from step 1. A verdict on the
+old screenshots is not a verdict on the new ones.
+
+## What this skill does not contain
+
+Any design rules. The checklist is the user's file, named in their config, and
+if it is empty then this reports nothing and that is correct. A checklist that
+arrived with a tool is somebody else's taste wearing the tool's authority.

package/src/config.mjs

@@ -133,14 +133,16 @@ function validateTreatments(treatments, errors) {
 
 function validateJudge(judge, errors) {
   rejectUnknown(judge, ['checklist', 'shots', 'shotCommand', 'command', 'failOn'], 'judge', errors);
-  for (const key of ['checklist', 'command']) {
-    if (typeof judge[key] !== 'string' || !judge[key]) {
+  if (typeof judge.checklist !== 'string' || !judge.checklist) {
+    errors.push('judge.checklist must be a non-empty string');
+  }
+  // command is optional: an agent carrying the call with --emit and --verdict
+  // never needs one, and demanding a placeholder would be theatre.
+  for (const key of ['command', 'shotCommand']) {
+    if (judge[key] !== undefined && (typeof judge[key] !== 'string' || !judge[key])) {
       errors.push(`judge.${key} must be a non-empty string`);
     }
   }
-  if (judge.shotCommand !== undefined && (typeof judge.shotCommand !== 'string' || !judge.shotCommand)) {
-    errors.push('judge.shotCommand must be a non-empty string');
-  }
   stringArray(judge.shots, 'judge.shots', errors);
   if (judge.failOn !== undefined && judge.failOn !== 'never' && judge.failOn !== 'fail') {
     errors.push(

package/src/contrast.mjs

@@ -18,7 +18,7 @@
  */
 import { readFileSync } from 'node:fs';
 import { contrastRatio, isOpaque, parseColor } from './color.mjs';
-import { parseDeclarations, resolveScopes, resolveValue, unmatchedScopes } from './css.mjs';
+import { lineAt, parseDeclarations, resolveScopes, resolveValue, unmatchedScopes } from './css.mjs';
 import { expand, label } from './files.mjs';
 
 /** A token name, or a literal colour, resolved to rgba for one theme. */
@@ -28,7 +28,7 @@ function side(spec, table, theme) {
     if (!resolved.ok) return { ok: false, reason: `theme "${theme}": ${resolved.reason}` };
     const color = parseColor(resolved.value);
     if (!color.ok) return { ok: false, reason: `theme "${theme}": ${spec} is ${color.reason}` };
-    return { ok: true, rgba: color.rgba };
+    return { ok: true, rgba: color.rgba, at: resolved.decl };
   }
   const color = parseColor(spec);
   if (!color.ok) return { ok: false, reason: `theme "${theme}": ${color.reason}` };
@@ -49,7 +49,14 @@ export function runContrast(config, cwd) {
   // One declaration list across every token file, in the order they were
   // listed, so a later file overriding an earlier one behaves like a later
   // @import would.
-  const decls = files.flatMap((file) => parseDeclarations(readFileSync(file, 'utf8')));
+  // Each declaration remembers where it was written. A contrast failure is
+  // otherwise a number with nowhere to go, and the line you would edit to fix
+  // it is the line the token is declared on.
+  const decls = files.flatMap((file) => {
+    const source = readFileSync(file, 'utf8');
+    const where = { file: label(file, cwd), };
+    return parseDeclarations(source).map((d) => ({ ...d, ...where, line: lineAt(source, d.index) }));
+  });
 
   for (const theme of themes) {
     const table = resolveScopes(decls, theme.scopes);
@@ -111,6 +118,9 @@ export function runContrast(config, cwd) {
         ratio,
         min: pair.min,
         pass: ratio >= pair.min,
+        // Point at the foreground: it is the half a contrast failure is
+        // usually fixed by moving.
+        at: fg.at ? { file: fg.at.file, line: fg.at.line } : null,
       });
     }
   }

package/src/index.mjs

@@ -4,7 +4,7 @@
  */
 export { runContrast } from './contrast.mjs';
 export { runTreatments } from './treatments.mjs';
-export { runJudge, buildPrompt, checklistLines, extractJson } from './judge.mjs';
+export { runJudge, prepareJudge, gradeVerdict, buildPrompt, checklistLines, checklistEntries, extractJson } from './judge.mjs';
 export { runRuntime } from './runtime.mjs';
 export { connect, findBrowser } from './cdp.mjs';
 export { load, validate } from './config.mjs';

package/src/judge.mjs

@@ -86,10 +86,17 @@ CHECKLIST:
  * returns a verdict on your explanatory paragraph.
  */
 export function checklistLines(text) {
-  return text
-    .split('\n')
-    .filter((l) => /^\s*(?:[-*+]|\d+[.)])\s+\S/.test(l))
-    .map((l) => l.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, '').trim());
+  return checklistEntries(text).map((e) => e.text);
+}
+
+/** The same, keeping the line each one was written on so a finding can point at it. */
+export function checklistEntries(text) {
+  const entries = [];
+  text.split('\n').forEach((raw, i) => {
+    if (!/^\s*(?:[-*+]|\d+[.)])\s+\S/.test(raw)) return;
+    entries.push({ text: raw.replace(/^\s*(?:[-*+]|\d+[.)])\s+/, '').trim(), line: i + 1 });
+  });
+  return entries;
 }
 
 /**
@@ -147,62 +154,98 @@ export function extractJson(stdout) {
 
 const VERDICTS = new Set(['pass', 'fail', 'unsure']);
 
-export function runJudge(config, cwd) {
-  const findings = [];
-  const problems = [];
-  const { checklist: checklistPath, shots = [], shotCommand, command, failOn = 'never' } = config;
+const empty = (problems, failOn) => ({ name: 'judge', findings: [], problems, failOn, summary: '' });
+
+/**
+ * Everything the judge needs before a model is involved: the screenshots, the
+ * checklist, and the prompt built from them.
+ *
+ * Split out so the model call does not have to be a subprocess. A shell
+ * command is one way to reach a model and a poor one for an agent, which is
+ * already a model and can spawn a genuinely fresh context of its own rather
+ * than shelling out to a second copy of itself. This half prepares the call,
+ * `gradeVerdict` below checks the answer, and in between the transport is
+ * somebody else's problem.
+ *
+ * The preconditions are enforced here rather than at grading time. Handing
+ * back a prompt for zero screenshots would produce a confident verdict about
+ * nothing.
+ */
+export function prepareJudge(config, cwd) {
+  const { checklist: checklistPath, shots = [], shotCommand, failOn = 'never' } = config;
 
   if (shotCommand) {
     const made = runCommand(shotCommand, [], '', cwd);
-    if (!made.ok) {
-      problems.push(made.reason);
-      return { name: 'judge', findings, problems, failOn, summary: '' };
-    }
+    if (!made.ok) return { ok: false, result: empty([made.reason], failOn) };
   }
 
   const images = expand(shots, cwd);
   if (!images.length) {
-    problems.push(
-      `no screenshots matched ${shots.map((s) => `"${s}"`).join(', ')}. ` +
-        `A judge with nothing to look at cannot fail, so it does not get to pass either.`,
-    );
-    return { name: 'judge', findings, problems, failOn, summary: '' };
+    return {
+      ok: false,
+      result: empty(
+        [
+          `no screenshots matched ${shots.map((s) => `"${s}"`).join(', ')}. ` +
+            `A judge with nothing to look at cannot fail, so it does not get to pass either.`,
+        ],
+        failOn,
+      ),
+    };
   }
 
-  let lines;
+  let entries;
   try {
-    lines = checklistLines(readFileSync(resolve(cwd, checklistPath), 'utf8'));
+    entries = checklistEntries(readFileSync(resolve(cwd, checklistPath), 'utf8'));
   } catch {
-    problems.push(`cannot read the checklist at ${checklistPath}`);
-    return { name: 'judge', findings, problems, failOn, summary: '' };
+    return { ok: false, result: empty([`cannot read the checklist at ${checklistPath}`], failOn) };
   }
-  if (!lines.length) {
-    problems.push(
-      `${checklistPath} has no checklist lines in it. Lines to judge are list ` +
-        `items ("- ..." or "1. ..."); everything else is treated as prose.`,
-    );
-    return { name: 'judge', findings, problems, failOn, summary: '' };
+  if (!entries.length) {
+    return {
+      ok: false,
+      result: empty(
+        [
+          `${checklistPath} has no checklist lines in it. Lines to judge are list ` +
+            `items ("- ..." or "1. ..."); everything else is treated as prose.`,
+        ],
+        failOn,
+      ),
+    };
   }
 
-  const reply = runCommand(command, images, buildPrompt(lines, images.map((i) => label(i, cwd))), cwd);
-  if (!reply.ok) {
-    problems.push(reply.reason);
-    return { name: 'judge', findings, problems, failOn, summary: '' };
-  }
+  const relative = images.map((i) => label(i, cwd));
+  return {
+    ok: true,
+    entries,
+    images,
+    relativeImages: relative,
+    prompt: buildPrompt(entries.map((e) => e.text), relative),
+  };
+}
+
+/**
+ * Check a reply against the checklist it was supposed to answer.
+ *
+ * This is the half that makes the whole thing trustworthy, and it does not
+ * care where the reply came from. A judge that quietly drops the hardest line
+ * is the failure mode to guard: every remaining verdict says pass, and the one
+ * nobody answered is the one that mattered.
+ */
+export function gradeVerdict(reply, prepared, config) {
+  const { checklist: checklistPath, failOn = 'never' } = config;
+  const findings = [];
+  const problems = [];
+  const { entries, images } = prepared;
+  const lines = entries.map((e) => e.text);
+  const lineNumbers = new Map(entries.map((e) => [e.text, e.line]));
 
-  const parsed = extractJson(reply.stdout);
+  const parsed = extractJson(reply);
   if (!parsed.ok) {
-    problems.push(`${parsed.reason}. The judge must reply with the documented JSON shape.`);
-    return { name: 'judge', findings, problems, failOn, summary: '' };
+    return empty([`${parsed.reason}. The judge must reply with the documented JSON shape.`], failOn);
   }
   if (!Array.isArray(parsed.value.findings)) {
-    problems.push('the reply has no "findings" array');
-    return { name: 'judge', findings, problems, failOn, summary: '' };
+    return empty(['the reply has no "findings" array'], failOn);
   }
 
-  // Cross-check both directions. A judge that quietly drops the hardest line
-  // is the failure mode to guard: the remaining verdicts all say pass, and
-  // the line nobody answered is the one that mattered.
   const wanted = new Set(lines);
   const answered = new Set();
   for (const f of parsed.value.findings) {
@@ -219,7 +262,12 @@ export function runJudge(config, cwd) {
       continue;
     }
     answered.add(f.line);
-    findings.push({ line: f.line, verdict: f.verdict, why: (f.why ?? '').trim() });
+    findings.push({
+      line: f.line,
+      verdict: f.verdict,
+      why: (f.why ?? '').trim(),
+      at: { file: checklistPath, line: lineNumbers.get(f.line) },
+    });
   }
   for (const line of lines) {
     if (!answered.has(line)) problems.push(`the judge did not answer "${line}"`);
@@ -232,6 +280,27 @@ export function runJudge(config, cwd) {
     failOn,
     summary: `${lines.length} ${lines.length === 1 ? 'line' : 'lines'} against ${images.length} ${
       images.length === 1 ? 'screenshot' : 'screenshots'
-    } (${images.map((i) => label(i, cwd)).join(', ')})`,
+    } (${prepared.relativeImages.join(', ')})`,
   };
 }
+
+/** The whole thing, with a configured command as the transport. */
+export function runJudge(config, cwd) {
+  const { command, failOn = 'never' } = config;
+  const prepared = prepareJudge(config, cwd);
+  if (!prepared.ok) return prepared.result;
+
+  if (!command) {
+    return empty(
+      [
+        'judge.command is not set, so there is nothing to ask. Set it, or use ' +
+          '`taste-check judge --emit` and `--verdict` to let an agent carry the call.',
+      ],
+      failOn,
+    );
+  }
+
+  const reply = runCommand(command, prepared.images, prepared.prompt, cwd);
+  if (!reply.ok) return empty([reply.reason], failOn);
+  return gradeVerdict(reply.stdout, prepared, config);
+}

package/src/report.mjs

@@ -28,7 +28,7 @@ function contrastLines(result) {
 
 function treatmentLines(result) {
   return [
-    ...result.failures.map((text) => ({ level: 'fail', text })),
+    ...result.failures.map((f) => ({ level: 'fail', text: `${f.file}:${f.line} ${f.message}` })),
     ...result.problems.map((text) => ({ level: 'error', text })),
   ];
 }

package/src/sarif.mjs

@@ -0,0 +1,236 @@
+/**
+ * SARIF 2.1.0 output, so findings land in a code scanning tab instead of only
+ * in a log nobody opens.
+ *
+ * The part worth getting right is locations. A format conversion that emits
+ * every finding against the config file is technically valid SARIF and useless
+ * in practice: the annotations all pile onto one line and none of them say
+ * where the problem is.
+ *
+ * So every finding points at the line you would edit to change it. An
+ * unapproved class points at the markup. A contrast failure points at the line
+ * in the token file where the foreground is declared, which is the half of a
+ * pair you usually end up moving. A judge verdict points at the line in your
+ * checklist. Where a finding genuinely has no file behind it, it points at the
+ * config, because that is where the rule was written.
+ */
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { relative, resolve, sep } from 'node:path';
+
+import { linesFor } from './report.mjs';
+
+const HELP = 'https://github.com/josueavalosjim/taste-check#readme';
+
+/**
+ * Levels are the same judgement the exit code makes. A judge verdict is
+ * advisory, so it is a note; everything that gates the build is an error.
+ */
+const RULES = [
+  ['contrast/below-floor', 'error', 'A declared pair is under the ratio it was given.'],
+  ['contrast/unmeasurable', 'error', 'A pair could not be measured: a missing token, a dead scope, a translucent background, or a colour that would not parse.'],
+  ['treatments/unapproved-class', 'error', 'A class name that is not on the approved list.'],
+  ['treatments/one-off-value', 'error', 'A literal colour or length hardcoded into an inline style.'],
+  ['treatments/unscannable', 'error', 'No markup matched, so nothing was checked.'],
+  ['runtime/below-floor', 'error', 'A target on the rendered page is under the ratio it was given.'],
+  ['runtime/unmeasurable', 'error', 'A target could not be measured: no element, nothing rendered, an edge with no width, or no browser.'],
+  ['judge/verdict', 'note', 'A checklist line the judge did not pass. Advisory: a model verdict is not reproducible.'],
+  ['judge/did-not-run', 'error', 'The judge could not run, which is a fact rather than an opinion.'],
+];
+
+const index = new Map(RULES.map(([id], i) => [id, i]));
+
+/**
+ * SARIF URIs are relative to the run's root, which for code scanning is the
+ * repository. Paths inside a config are relative to the config file, so they
+ * have to be re-rooted here. Getting this wrong does not fail validation, it
+ * just hangs every annotation on a path that does not exist.
+ */
+function uriFor(file, { configDir, root }) {
+  const absolute = resolve(configDir, file);
+  return relative(root, absolute).split(sep).join('/');
+}
+
+/**
+ * A fingerprint keyed to the content of the line rather than to its number.
+ *
+ * This is what keeps an alert the same alert when the file shifts. Without it
+ * every finding below an added import reads as a new problem and an old one
+ * closed, which turns the code scanning tab into churn and trains people to
+ * ignore it. Hashing the line's text rather than its position is what survives
+ * the shift. The rule id and a key naming what the finding is about are in
+ * there too, because two one-off values on the same line are two findings and
+ * a fingerprint that collides makes them one. The key is an identity, not the
+ * message: rewording a message must not close an alert and open a new one.
+ */
+function fingerprint(uri, line, ruleId, key, ctx) {
+  let text = '';
+  try {
+    text = (readFileSync(resolve(ctx.root, uri), 'utf8').split('\n')[line - 1] ?? '').trim();
+  } catch {
+    /* a file we cannot read still gets a stable fingerprint from its path */
+  }
+  return {
+    primaryLocationLineHash: createHash('sha256')
+      .update(`${ruleId}\u0000${uri}\u0000${text}\u0000${key}`)
+      .digest('hex')
+      .slice(0, 32),
+  };
+}
+
+const location = (file, ctx, line) => ({
+  physicalLocation: {
+    artifactLocation: { uri: uriFor(file, ctx), uriBaseId: '%SRCROOT%' },
+    // A region with no line is invalid, and line 1 is the honest fallback for
+    // "this file, we cannot be more specific".
+    region: { startLine: Math.max(1, line ?? 1) },
+  },
+});
+
+function resultsFor(check, ctx) {
+  const here = location(ctx.configFile, { ...ctx, configDir: ctx.root }, 1);
+  const out = [];
+
+  if (check.name === 'contrast' || check.name === 'runtime') {
+    for (const sample of check.samples ?? []) {
+      if (sample.pass) continue;
+      out.push({
+        ruleId: `${check.name}/below-floor`,
+        key: `${sample.fg}|${sample.bg}|${sample.theme}`,
+        level: 'error',
+        message: {
+          text:
+            `${sample.ratio.toFixed(2)}:1 against a floor of ${sample.min} for ${sample.fg} on ` +
+            `${sample.bg} in ${sample.theme}${sample.note ? `. ${sample.note}` : ''}`,
+        },
+        locations: [sample.at ? location(sample.at.file, ctx, sample.at.line) : here],
+      });
+    }
+    for (const problem of check.problems ?? []) {
+      out.push({
+        ruleId: `${check.name}/unmeasurable`,
+        key: problem,
+        level: 'error',
+        message: { text: problem },
+        locations: [here],
+      });
+    }
+    return out;
+  }
+
+  if (check.name === 'treatments') {
+    for (const failure of check.failures ?? []) {
+      out.push({
+        ruleId: failure.rule,
+        key: `${failure.subject ?? failure.message}`,
+        level: 'error',
+        message: { text: failure.message },
+        locations: [location(failure.file, ctx, failure.line)],
+      });
+    }
+    for (const problem of check.problems ?? []) {
+      out.push({
+        ruleId: 'treatments/unscannable',
+        key: problem,
+        level: 'error',
+        message: { text: problem },
+        locations: [here],
+      });
+    }
+    return out;
+  }
+
+  if (check.name === 'judge') {
+    for (const finding of check.findings ?? []) {
+      if (finding.verdict === 'pass') continue;
+      out.push({
+        ruleId: 'judge/verdict',
+        key: finding.line,
+        // Mirrors the exit code: advisory unless the config opted into blocking.
+        level: check.failOn === 'fail' && finding.verdict === 'fail' ? 'warning' : 'note',
+        message: { text: `${finding.verdict}: ${finding.line}${finding.why ? `. ${finding.why}` : ''}` },
+        locations: [finding.at ? location(finding.at.file, ctx, finding.at.line) : here],
+      });
+    }
+    for (const problem of check.problems ?? []) {
+      out.push({
+        ruleId: 'judge/did-not-run',
+        key: problem,
+        level: 'error',
+        message: { text: problem },
+        locations: [here],
+      });
+    }
+  }
+  return out;
+}
+
+/** Attach a fingerprint to each result, derived from where it points. */
+function withFingerprints(found, ctx) {
+  return found.map((r) => {
+    const place = r.locations[0].physicalLocation;
+    const { key, ...rest } = r;
+    return {
+      ...rest,
+      partialFingerprints: fingerprint(
+        place.artifactLocation.uri,
+        place.region.startLine,
+        r.ruleId,
+        r.key ?? r.message.text,
+        ctx,
+      ),
+    };
+  });
+}
+
+export function toSarif(results, { version, configFile, configDir, root = process.cwd() }) {
+  const ctx = {
+    configFile: configFile ?? 'tastecheck.config.json',
+    configDir: configDir ?? root,
+    root,
+  };
+  const found = results.flatMap((check) => resultsFor(check, ctx));
+  // Only the rules that actually fired, so the tab is not padded with rules
+  // this run had no opinion about.
+  const fired = [...new Set(found.map((r) => r.ruleId))];
+
+  return JSON.stringify(
+    {
+      $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+      version: '2.1.0',
+      runs: [
+        {
+          tool: {
+            driver: {
+              name: 'taste-check',
+              version,
+              informationUri: HELP,
+              rules: fired.map((id) => {
+                const [, level, description] = RULES[index.get(id)];
+                return {
+                  id,
+                  name: id.replace(/[/-](.)/g, (_, c) => c.toUpperCase()),
+                  shortDescription: { text: description },
+                  helpUri: HELP,
+                  defaultConfiguration: { level },
+                };
+              }),
+            },
+          },
+          results: withFingerprints(found, ctx).map((r) => ({
+            ...r,
+            ruleIndex: fired.indexOf(r.ruleId),
+          })),
+        },
+      ],
+    },
+    null,
+    2,
+  );
+}
+
+/** Every rule this tool can emit, for the docs and for the tests to check. */
+export const ruleIds = () => RULES.map(([id]) => id);
+
+// Re-exported so a caller does not have to know that a note is not a failure.
+export { linesFor };

package/src/treatments.mjs

@@ -202,20 +202,29 @@ export function runTreatments(config, cwd) {
 
   for (const file of files) {
     const source = readFileSync(file, 'utf8');
-    const where = (at) => `${label(file, cwd)}:${lineOf(source, at)}`;
+    const where = (at) => ({ file: label(file, cwd), line: lineOf(source, at) });
 
     for (const tag of openTags(source, elements)) {
       for (const { name, at } of classesOf(tag.attrs)) {
         if (approved.has(name)) continue;
         if (allowPrefixes.some((p) => name.startsWith(p))) continue;
-        failures.push(`${where(tag.start + at)} class "${name}" on <${tag.name}> is not approved`);
+        failures.push({
+          rule: 'treatments/unapproved-class',
+          ...where(tag.start + at),
+          subject: name,
+          message: `class "${name}" on <${tag.name}> is not approved`,
+        });
       }
       for (const { text, at } of inlineValues(tag.attrs)) {
         if (allowedValues.has(text.toLowerCase())) continue;
-        failures.push(
-          `${where(tag.start + at)} inline value "${text}" on <${tag.name}> is a one-off. ` +
+        failures.push({
+          rule: 'treatments/one-off-value',
+          ...where(tag.start + at),
+          subject: text,
+          message:
+            `inline value "${text}" on <${tag.name}> is a one-off. ` +
             `Use a token, or add it to approvedValues.`,
-        );
+        });
       }
     }
   }