ci(lint): split lint jobs and annotate Prettier and JSON schema errors in PRs (#4982)

* ci: split lint-code into ESLint, Prettier and JSON Schema jobs with PR annotations

- ESLint: annotations via setup-node's built-in eslint-stylish problem matcher.
- Prettier: new scripts/lintFormat.mts formats unformatted files in memory, diffs
  them and emits line-level `::error` annotations with the expected code.
- JSON Schema: replace ajv-cli with a local ESLint rule (Ajv draft 2020-12) that
  validates icons/categories JSON against their `$schema` and reports at the
  offending property. eslint-plugin-json-schema-validator was not used because it
  runs Ajv in draft-07 mode and ignores `dependentRequired`.

All annotations use workflow commands, so they work on fork PRs with a read-only token.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FVxEtqNswEDq1N23taZYh8

* Improve root value check and property error handling

Enhance error reporting for JSON schema validation.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

* style(lint): format jsonSchemaPlugin with Prettier

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FVxEtqNswEDq1N23taZYh8

* test commit

* fix(lint): annotate syntax errors from Prettier and ESLint in PRs

- ESLint/JSON Schema jobs use a small GitHub formatter that prints `::error`
  workflow commands. setup-node's eslint-stylish matcher skipped parsing errors
  because they have no rule id.
- lintFormat.mts annotates Prettier syntax errors (exit code 2) at their line and
  column instead of only printing stderr, and still checks the other files.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FVxEtqNswEDq1N23taZYh8

* ci(lint): spell check icon and category metadata with cspell annotations

- New "Spelling" job runs scripts/lintSpelling.mts, which turns cspell findings
  into `::error` annotations (with cspell's suggested fix when it has one).
- cspell accepts both US and British English, ignores contributor usernames and
  deprecated `alias.typo` aliases.
- Add existing search tags and domain terms to .cspell/custom-words.txt so the
  current metadata passes.
- Add `lint:spelling` to `pnpm lint` and lint-staged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FVxEtqNswEDq1N23taZYh8

* fix(lint): pin JSON schemas per file set and drop typo tags

- json-schema/no-invalid now takes the schema from config (icon.schema.json for
  icons, category.schema.json for categories) and reports a `$schema` that
  points elsewhere, so metadata can't opt out of validation.
- Remove the misspelled `frigerator` and `sterisk` tags and their allowlist entries.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FVxEtqNswEDq1N23taZYh8

* fix(icons): split joined-word tags into separate words

Tags like `groupchat` and `timemachine` become `group chat` and `time machine`
so they read naturally and pass the spell check without allowlisting. Where the
spaced tag already existed (`smart home`) the joined one is dropped.

cspell now skips all alias names, since they are icon names that can't change
(e.g. the deprecated `palmtree` alias).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FVxEtqNswEDq1N23taZYh8

* Revert

* Try another error

* Revert error

---------

Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

scripts/eslint/githubFormatter.mjs

@@ -0,0 +1,61 @@
+import path from 'node:path';
+
+/**
+ * ESLint formatter for GitHub Actions. Prints each problem as a readable line plus a workflow
+ * command (`::error file=…`), so it shows up as an inline annotation in the PR diff.
+ *
+ * Unlike setup-node's `eslint-stylish` problem matcher, this also annotates parsing errors, which
+ * have no rule id.
+ *
+ * Usage: eslint --format ./scripts/eslint/githubFormatter.mjs
+ */
+
+/** Escape data for a workflow command, see https://github.com/actions/toolkit/blob/main/packages/core/src/command.ts */
+const escapeData = (/** @type {string} */ value) =>
+  value.replaceAll('%', '%25').replaceAll('\r', '%0D').replaceAll('\n', '%0A');
+const escapeProperty = (/** @type {string} */ value) =>
+  escapeData(value).replaceAll(':', '%3A').replaceAll(',', '%2C');
+
+/** @type {import('eslint').ESLint.FormatterFunction} */
+const formatter = (results) => {
+  const lines = [];
+  let errors = 0;
+  let warnings = 0;
+
+  for (const result of results) {
+    const file = path.relative(process.cwd(), result.filePath);
+
+    for (const message of result.messages) {
+      const severity = message.severity === 2 ? 'error' : 'warning';
+      if (severity === 'error') errors++;
+      else warnings++;
+
+      const rule = message.ruleId ?? 'parse';
+      const line = message.line ?? 1;
+      const column = message.column ?? 1;
+      lines.push(`${file}:${line}:${column}  ${severity}  ${message.message}  (${rule})`);
+
+      const properties = [
+        `file=${escapeProperty(file)}`,
+        `line=${line}`,
+        `col=${column}`,
+        message.endLine ? `endLine=${message.endLine}` : '',
+        message.endColumn ? `endColumn=${message.endColumn}` : '',
+        `title=${escapeProperty(`ESLint (${rule})`)}`,
+      ].filter(Boolean);
+      lines.push(`::${severity} ${properties.join(',')}::${escapeData(message.message)}`);
+    }
+  }
+
+  if (errors + warnings > 0) {
+    const plural = (/** @type {number} */ count, /** @type {string} */ word) =>
+      `${count} ${word}${count === 1 ? '' : 's'}`;
+    lines.push(
+      '',
+      `✖ ${plural(errors + warnings, 'problem')} (${plural(errors, 'error')}, ${plural(warnings, 'warning')})`,
+    );
+  }
+  return lines.join('\n');
+};
+
+export default formatter;

scripts/eslint/jsonSchemaPlugin.mjs

@@ -0,0 +1,147 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { getStaticJSONValue } from 'jsonc-eslint-parser';
+
+/**
+ * ESLint plugin that validates JSON files against a configured JSON Schema (draft 2020-12),
+ * reporting each error at the offending property. It also requires the file's `$schema` field to
+ * point at that schema.
+ *
+ * Off-the-shelf plugins (e.g. eslint-plugin-json-schema-validator) only run Ajv in draft-07 mode,
+ * which silently skips 2020-12 keywords such as `dependentRequired`.
+ */
+
+const ajv = new Ajv2020({ allErrors: true });
+/** @type {Map<string, import('ajv').ValidateFunction>} */
+const validators = new Map();
+
+/** @param {string} schemaPath */
+const getValidator = (schemaPath) => {
+  let validate = validators.get(schemaPath);
+  if (!validate) {
+    validate = ajv.compile(JSON.parse(fs.readFileSync(schemaPath, 'utf-8')));
+    validators.set(schemaPath, validate);
+  }
+  return validate;
+};
+
+/**
+ * Find the AST node for a JSON pointer (e.g. `/aliases/0/name`). Returns the property node for
+ * object members so the report points at the key, falling back to the closest existing parent.
+ *
+ * @param {any} node
+ * @param {string} pointer
+ */
+const findNode = (node, pointer) => {
+  const segments = pointer
+    .split('/')
+    .slice(1)
+    .map((segment) => segment.replaceAll('~1', '/').replaceAll('~0', '~'));
+  let current = node;
+  let reportNode = node;
+  for (const segment of segments) {
+    if (current?.type === 'JSONObjectExpression') {
+      const property = current.properties.find(
+        (/** @type {any} */ prop) => (prop.key.value ?? prop.key.name) === segment,
+      );
+      if (!property) break;
+      reportNode = property;
+      current = property.value;
+    } else if (current?.type === 'JSONArrayExpression') {
+      const element = current.elements[Number(segment)];
+      if (!element) break;
+      reportNode = element;
+      current = element;
+    } else {
+      break;
+    }
+  }
+  return { node: current, reportNode };
+};
+
+/** @type {import('eslint').Rule.RuleModule} */
+const noInvalid = {
+  meta: {
+    type: 'problem',
+    docs: {
+      description: 'Validate JSON files against a JSON Schema and require `$schema` to point at it',
+    },
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          // Path to the schema, relative to the ESLint working directory (the repo root).
+          schema: { type: 'string' },
+        },
+        required: ['schema'],
+        additionalProperties: false,
+      },
+    ],
+  },
+  create(context) {
+    return {
+      /** @param {any} program */
+      Program(program) {
+        const root = program.body[0]?.expression;
+        if (root?.type !== 'JSONObjectExpression') {
+          context.report({ node: root ?? program, message: 'Root value must be an object.' });
+          return;
+        }
+
+        const data = getStaticJSONValue(root);
+        if (typeof data?.$schema !== 'string') {
+          context.report({ node: root, message: 'Missing `$schema` field.' });
+          return;
+        }
+
+        // Validate against the configured schema, not whatever `$schema` points at, so a file can't
+        // opt out of validation by referencing a more permissive schema.
+        const schemaPath = path.resolve(context.cwd, context.options[0].schema);
+        const expectedRef = path
+          .relative(path.dirname(context.filename), schemaPath)
+          .split(path.sep)
+          .join('/');
+        if (path.resolve(path.dirname(context.filename), data.$schema) !== schemaPath) {
+          context.report({
+            node: findNode(root, '/$schema').reportNode,
+            message: `\`$schema\` must be "${expectedRef}".`,
+          });
+        }
+
+        const validate = getValidator(schemaPath);
+        if (validate(data)) return;
+
+        for (const error of validate.errors ?? []) {
+          const { node, reportNode } = findNode(root, error.instancePath);
+          const location = error.instancePath || '(root)';
+
+          if (error.keyword === 'additionalProperties' && node?.type === 'JSONObjectExpression') {
+            const property = findNode(
+              node,
+              `/${error.params.additionalProperty.replaceAll('~', '~0').replaceAll('/', '~1')}`,
+            ).reportNode;
+            context.report({
+              node: property,
+              message: `${location} has unexpected property "${error.params.additionalProperty}".`,
+            });
+            continue;
+          }
+
+          const isContainer =
+            reportNode.type === 'JSONObjectExpression' || reportNode.type === 'JSONArrayExpression';
+          context.report({
+            // Report objects and arrays at their opening bracket only, not their whole range.
+            loc: isContainer ? reportNode.loc.start : reportNode.loc,
+            message: `${location} ${error.message}.`,
+          });
+        }
+      },
+    };
+  },
+};
+
+export default {
+  meta: { name: 'json-schema' },
+  rules: { 'no-invalid': noInvalid },
+};

scripts/lintFormat.mts

@@ -0,0 +1,123 @@
+/**
+ * Checks formatting with Prettier and reports every unformatted range as a GitHub Actions
+ * annotation (`::error file=…,line=…`), so it shows up inline in the PR diff.
+ *
+ * `prettier --check` only reports file names, so this formats each listed file in memory and
+ * diffs it against the original to find the exact lines.
+ */
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import process from 'process';
+import { spawnSync } from 'child_process';
+import { createRequire } from 'module';
+import * as prettier from 'prettier';
+
+const PATTERNS = ['**/*.{js,mjs,ts,jsx,tsx,html,css,scss,json,yml,yaml}', 'icons/*.svg'];
+
+const prettierBin = createRequire(import.meta.url).resolve('prettier/bin/prettier.cjs');
+
+const listDifferent = spawnSync(
+  process.execPath,
+  [prettierBin, '--list-different', '--no-color', ...PATTERNS],
+  { encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 },
+);
+
+/** Escape data for a workflow command, see https://github.com/actions/toolkit/blob/main/packages/core/src/command.ts */
+const escapeData = (value: string) =>
+  value.replaceAll('%', '%25').replaceAll('\r', '%0D').replaceAll('\n', '%0A');
+const escapeProperty = (value: string) =>
+  escapeData(value).replaceAll(':', '%3A').replaceAll(',', '%2C');
+
+let problems = 0;
+
+// Exit code 2 means Prettier could not process a file, e.g. because of a syntax error.
+if (listDifferent.status !== 0 && listDifferent.status !== 1) {
+  console.log('::group::Prettier errors');
+  console.log(listDifferent.stderr);
+  console.log('::endgroup::');
+
+  const syntaxError = /^\[error\] (.+?): (\w*Error: .+) \((\d+):(\d+)\)$/;
+  for (const line of listDifferent.stderr.split('\n')) {
+    const match = line.match(syntaxError);
+    if (!match) continue;
+    const [, file, message, errorLine, column] = match;
+    console.log(
+      `::error file=${escapeProperty(file)},line=${errorLine},col=${column},title=Prettier::${escapeData(message)}`,
+    );
+    problems++;
+  }
+
+  if (problems === 0) {
+    console.log(
+      `::error title=Prettier::${escapeData(listDifferent.stderr.trim() || 'Prettier failed.')}`,
+    );
+    problems++;
+  }
+}
+
+const files = listDifferent.stdout.split('\n').filter(Boolean);
+
+if (files.length === 0 && problems === 0) {
+  console.log('All matched files use Prettier code style!');
+  process.exit(0);
+}
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'lint-format-'));
+const hunkHeader = /^@@ -(\d+)(?:,(\d+))? \+\d+(?:,\d+)? @@/;
+
+for (const file of files) {
+  const source = fs.readFileSync(file, 'utf-8');
+  const options = await prettier.resolveConfig(file);
+  const formatted = await prettier.format(source, { ...options, filepath: file });
+
+  const formattedFile = path.join(tmpDir, 'formatted');
+  fs.writeFileSync(formattedFile, formatted);
+
+  const { stdout: diff } = spawnSync(
+    'git',
+    ['diff', '--no-index', '--no-color', '-U0', '--', file, formattedFile],
+    { encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 },
+  );
+
+  console.log(`::group::${file}`);
+  console.log(diff);
+  console.log('::endgroup::');
+
+  const lines = diff.split('\n');
+  for (let index = 0; index < lines.length; index++) {
+    const match = lines[index].match(hunkHeader);
+    if (!match) continue;
+
+    const start = Number(match[1]);
+    const count = match[2] === undefined ? 1 : Number(match[2]);
+
+    const expected: string[] = [];
+    while (index + 1 < lines.length && /^[-+\\ ]/.test(lines[index + 1])) {
+      index++;
+      if (lines[index].startsWith('+')) expected.push(lines[index].slice(1));
+    }
+
+    // A pure insertion (count 0) happens after `start`, so point at that line.
+    const line = Math.max(start, 1);
+    const endLine = count === 0 ? line : start + count - 1;
+
+    const message =
+      expected.length > 0
+        ? `Code is not formatted with Prettier. Expected:\n${expected.join('\n')}`
+        : 'Code is not formatted with Prettier. Remove these lines.';
+
+    console.log(
+      `::error file=${escapeProperty(file)},line=${line},endLine=${endLine},title=Prettier::${escapeData(message)}`,
+    );
+  }
+}
+
+fs.rmSync(tmpDir, { recursive: true, force: true });
+
+if (files.length > 0) {
+  console.log(
+    `\n${files.length} file(s) not formatted with Prettier. Run \`pnpm lint:format-fix\` and \`pnpm lint:icons-fix\` to fix.`,
+  );
+}
+process.exit(1);

scripts/lintSpelling.mts

@@ -0,0 +1,57 @@
+/**
+ * Spell checks icon and category metadata with cspell and reports every unknown word as a GitHub
+ * Actions annotation (`::error file=…,line=…`), so it shows up inline in the PR diff.
+ *
+ * Words that are correct but unknown to cspell go in `.cspell/custom-words.txt`.
+ */
+import process from 'process';
+import { spawnSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const PATTERNS = ['icons/*.json', 'categories/*.json'];
+
+// cspell only exports its bin for `import`, so resolve it the ESM way.
+const cspellBin = fileURLToPath(import.meta.resolve('cspell/bin.mjs'));
+
+const cspell = spawnSync(
+  process.execPath,
+  [cspellBin, '--no-color', '--no-progress', '--no-summary', ...PATTERNS],
+  { encoding: 'utf-8', maxBuffer: 64 * 1024 * 1024 },
+);
+
+/** Escape data for a workflow command, see https://github.com/actions/toolkit/blob/main/packages/core/src/command.ts */
+const escapeData = (value: string) =>
+  value.replaceAll('%', '%25').replaceAll('\r', '%0D').replaceAll('\n', '%0A');
+const escapeProperty = (value: string) =>
+  escapeData(value).replaceAll(':', '%3A').replaceAll(',', '%2C');
+
+const issue = /^(.+?):(\d+):(\d+) - Unknown word \((.+?)\)(?: fix: \((.+?)\))?/;
+let problems = 0;
+
+for (const line of cspell.stdout.split('\n')) {
+  const match = line.match(issue);
+  if (!match) continue;
+
+  const [, file, lineNumber, column, word, fix] = match;
+  const suggestion = fix ? ` Did you mean "${fix}"?` : '';
+  const message = `Unknown word "${word}".${suggestion} Fix the typo or add the word to .cspell/custom-words.txt.`;
+
+  console.log(line);
+  console.log(
+    `::error file=${escapeProperty(file)},line=${lineNumber},col=${column},endColumn=${Number(column) + word.length},title=cspell::${escapeData(message)}`,
+  );
+  problems++;
+}
+
+if (cspell.status !== 0 && problems === 0) {
+  process.stderr.write(cspell.stderr);
+  console.log(`::error title=cspell::${escapeData(cspell.stderr.trim() || 'cspell failed.')}`);
+  process.exit(cspell.status ?? 1);
+}
+
+if (problems > 0) {
+  console.log(`\n${problems} spelling issue(s) found.`);
+  process.exit(1);
+}
+
+console.log('No spelling issues found.');