@expressivecss/mcp-server 0.4.0 → 0.5.0

package/server.js

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
 import { existsSync, closeSync, constants as fsConstants, fstatSync, lstatSync, openSync, readFileSync, realpathSync } from 'node:fs';
-import { lstat, open, readdir, readFile, realpath, stat } from 'node:fs/promises';
+import { lstat, readFile, realpath, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { createHash, randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { createHash, randomUUID, hash } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
 import * as z from 'zod/v4';
@@ -11,6 +11,8 @@ import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { McpError, ReadResourceRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { resolveExpressiveVersion } from './scripts/resolve-version.mjs';
+import { readBoundedRegularFile } from './scripts/bounded-file.mjs';
+import { authoredName, enforcedRules, expandedSelector, ruleBreach } from './scripts/semantics-rules.mjs';
 
 const SERVER_DIR = path.dirname(fileURLToPath(import.meta.url));
 const COMPONENT_DECISIONS = JSON.parse(readFileSync(path.join(SERVER_DIR, 'component-decisions.json'), 'utf8'));
@@ -33,6 +35,9 @@ const DEFAULT_QA_MAX_TOTAL_MB = 16;
 const MAX_STATIC_ISSUES = 200;
 const MAX_STATIC_ISSUES_PER_REQUEST = 1_000;
 const MAX_STATIC_MARKUP_DELIMITERS = 4_000;
+// `:has()` selectors visit every descendant of every candidate, so deep nesting is quadratic
+// (1,024 levels take over a second), and `outerHTML` overflows the stack past about 2,200.
+const MAX_STATIC_MARKUP_DEPTH = 256;
 // Source locations make parse5 copy a parent's children for each text run, so the cost grows with
 // characters times tags. Past this product, semantics findings report 1:1 to stay within the budget.
 const MAX_LOCATED_MARKUP_WORK = 100_000_000;
@@ -83,7 +88,7 @@ const SETTINGS = {
   commandTimeoutMs: Number(process.env.EXPRESSIVECSS_MCP_COMMAND_TIMEOUT_MS || DEFAULT_COMMAND_TIMEOUT_MS),
   allowedScripts: configuredScripts(process.env.EXPRESSIVECSS_MCP_ALLOWED_SCRIPTS),
   allowedCommandRoots: configuredCommandRoots(process.env.EXPRESSIVECSS_MCP_ALLOWED_COMMAND_ROOTS),
-  // Unset keeps every root open. A set but empty or invalid list denies every client-supplied root.
+  // Unset allows only the default root. A set but empty or invalid list denies every client-supplied root.
   allowedProjectRoots: process.env[PROJECT_ROOTS_SETTING] === undefined ? null : configuredCommandRoots(process.env[PROJECT_ROOTS_SETTING]),
 };
 
@@ -96,12 +101,24 @@ const SKIP_FLAGS = {
   qualityInspector: 'SKIP_QUALITY_INSPECTOR',
 };
 
+// Class-attribute matching for the legacy rules. CLASS_OPEN is the start of a
+// class attribute's value in HTML or JSX: class="…", className="…",
+// className={"…"} or className={`…`}. CLASS_CHARS runs to its end. A class
+// token is a whole name: not part of a longer one, and not a Tailwind-style
+// `name:` prefix.
+const CLASS_OPEN = String.raw`(?<![-\w])class(?:Name)?\s*=\s*(?:\{\s*)?["'\`]`;
+const CLASS_CHARS = String.raw`[^"'\`]*`;
+const classToken = (names) => String.raw`(?<![-\w:])(?:${names})(?![-\w:])`;
+const inClass = (names) => CLASS_OPEN + CLASS_CHARS + classToken(names);
+
 const LegacyPatternList = [
   {
     id: 'legacy-btn-class',
     severity: 'high',
     description: 'Replace `.btn` with the ExpressiveCSS button contract (`<button>`, `.button`, or component-specific button classes).',
-    pattern: /\bclass(?:Name)?\s*=\s*(?:"[^"]*\bbtn\b[^"]*"|'[^']*\bbtn\b[^']*'|`[^`]*\bbtn\b[^`]*`|\{\s*(?:"[^"]*\bbtn\b[^"]*"|'[^']*\bbtn\b[^']*'|`[^`]*\bbtn\b[^`]*`)\s*\}|btn(?=[\s>]))/gu,
+    // The match ends at `btn`: requiring the closing quote too backtracks once per
+    // `btn` in an unclosed value, which is quadratic.
+    pattern: /\bclass(?:Name)?\s*=\s*(?:\{\s*)?(?:"[^"]*\bbtn\b|'[^']*\bbtn\b|`[^`]*\bbtn\b|btn(?=[\s>]))/gu,
   },
   {
     id: 'legacy-card-content',
@@ -151,6 +168,108 @@ const LegacyPatternList = [
     description: '`.materialize-textarea` is retired; use `.expressive-textarea`.',
     pattern: /\bmaterialize-textarea\b/g,
   },
+  // Names removed in 0.16.0. Each description gives the replacement; the
+  // framework CHANGELOG's 0.16.0 migration notes list them together. Class names
+  // are matched as whole tokens inside a class attribute (see inClass), so an
+  // id or a word in prose that shares a name is not flagged. Tag patterns
+  // stop at `<` so unclosed markup cannot make them backtrack.
+  {
+    id: 'legacy-material-icons',
+    severity: 'high',
+    description: '`.material-icons` was removed in 0.16.0; use `.material-symbols` (or `-outlined`, `-rounded`, `-sharp`).',
+    pattern: /(?<![-\w])material-icons(?![-\w])/g,
+  },
+  {
+    id: 'legacy-i-icon',
+    severity: 'medium',
+    description: 'A bare `<i>` holding an icon name is italic text in 0.16.0, not an icon; write `<span class="material-symbols" aria-hidden="true">`. Only an `<i>` that opens a button, link, list item, label or similar host is checked; if it is italic prose, ignore this.',
+    // The host tag is part of the match, not a lookbehind: Node 22's V8 runs a
+    // variable-length lookbehind at every position, which is quadratic.
+    pattern: /<(?:a|button|label|li|span|div|nav|header|footer|menu|summary)\b[^<>]*>\s*<i(?:\s(?![^<>]*material-symbols)[^<>]*)?>\s*[a-z][a-z0-9]*(?:_[a-z0-9]+)*\s*<\/i>/g,
+  },
+  {
+    id: 'legacy-visibility-alias',
+    severity: 'high',
+    description: 'The small/med/xxl visibility aliases were removed in 0.16.0; use `.hide-on-compact-only`, `.hide-on-medium-only`, `.hide-on-extra-large-only`, `.show-on-compact` or `.show-on-extra-large`.',
+    pattern: /(?<![-\w])(?:hide-on-(?:small-only|small-and-down|med-only|xxl-only)|show-on-(?:small|xxl))(?![-\w])/g,
+  },
+  {
+    id: 'legacy-helper-class',
+    severity: 'medium',
+    description: '`.no-padding`, `.center-block` and `.no-select` were removed in 0.16.0; use `.p-0`, `.mx-auto` with `display: block`, or `user-select: none` in your own CSS.',
+    pattern: /(?<![-\w])(?:no-padding|center-block|no-select)(?![-\w])/g,
+  },
+  {
+    id: 'legacy-renamed-component',
+    severity: 'high',
+    description: '`.preloader`, `.searchbar` and the `.range` / `.range-field` slider hosts were removed in 0.16.0; use `.progress.circular`, `.search-bar` and `.slider`.',
+    // A `.range` host is only flagged where it wraps a range input: the name is
+    // too common to flag on its own. The gap to `>` is bounded: unbounded, an
+    // unclosed tag full of `.range` hosts rescanned to the end from each one.
+    pattern: new RegExp(`${inClass('preloader|searchbar|range-field')}|${CLASS_OPEN}(?=${CLASS_CHARS}${classToken('range')})${CLASS_CHARS}["'\`][^<>]{0,2000}>\\s*<input\\b[^<>]*\\btype\\s*=\\s*["']?range(?![-\\w])`, 'g'),
+  },
+  {
+    id: 'legacy-picker-root',
+    severity: 'high',
+    description: 'AutoInit starts `.date-picker` and `.time-picker` in 0.16.0; rename `class="datepicker"` and `class="timepicker"`.',
+    pattern: new RegExp(inClass('datepicker|timepicker'), 'g'),
+  },
+  {
+    id: 'legacy-sheet-class',
+    severity: 'high',
+    description: 'Sheet aliases were removed in 0.16.0; use `dialog.bottom-sheet` with `.drag-handle`, and `dialog.side-sheet` (add `.start` for the start edge).',
+    pattern: new RegExp(`<dialog\\b[^<>]*${inClass('bottom|right|left|right-sheet|left-sheet')}|<dialog\\b(?=[^<>]*${classToken('bottom-sheet')})[^<>]*>(?:(?!<\\/dialog>|<\\/DIALOG>)[^]){0,4000}?${inClass('handle')}`, 'g'),
+  },
+  {
+    id: 'legacy-variant-alias',
+    severity: 'high',
+    description: 'Variant aliases were removed in 0.16.0: use `.tooltip.rich` for `.tooltip.max`, `.toolbar.docked` for a `.max` bar and `.toolbar.vibrant` for a `.filled` bar, and `.selected` for a chip\'s `.active`.',
+    pattern: new RegExp(`${CLASS_OPEN}(?=${CLASS_CHARS}${classToken('tooltip|toolbar|chip')})(?=${CLASS_CHARS}${classToken('max|filled|active')})${CLASS_CHARS}["'\`]`, 'g'),
+  },
+  {
+    id: 'legacy-markup-path',
+    severity: 'high',
+    description: 'Pre-1.0 markup paths were removed in 0.16.0: put tab links directly in `nav.tabs` (no `li.tab`), put `.switch` on the `<label>` that wraps the checkbox, use `.medium` for a 56dp common button, and a plain `.button` for a navigation rail FAB (`.extra` only marks `circle extra` FABs).',
+    pattern: new RegExp([
+      `<(?!label\\b)[a-z][\\w-]*(?![\\w-])[^<>]*${inClass('switch')}`,
+      `<li\\b[^<>]*${inClass('tab')}`,
+      // `.extra` sized a common button: a <button> or <a>, or anything with `.button`.
+      `<(?:a|button)\\b[^<>]*${CLASS_OPEN}(?!${CLASS_CHARS}${classToken('circle')})${CLASS_CHARS}${classToken('extra')}`,
+      `${CLASS_OPEN}(?!${CLASS_CHARS}${classToken('circle')})(?=${CLASS_CHARS}${classToken('button')})${CLASS_CHARS}${classToken('extra')}`,
+    ].join('|'), 'g'),
+  },
+  {
+    id: 'legacy-carousel-flat',
+    severity: 'medium',
+    description: 'Carousel `.flat`, the `fullWidth` option and `.carousel-fixed-item` were removed in 0.16.0; choose an M3 layout such as `.hero` or `.uncontained`.',
+    pattern: new RegExp(`${CLASS_OPEN}(?=${CLASS_CHARS}${classToken('carousel')})${CLASS_CHARS}${classToken('flat')}|\\bfullWidth\\s*:\\s*true\\b|(?<![-\\w])carousel-fixed-item(?![-\\w])`, 'g'),
+  },
+  {
+    id: 'legacy-color-role',
+    severity: 'high',
+    description: 'The legacy color roles were removed in 0.16.0, with their `-light`/`-dark` pairs and classes; use `surface` for `background`, `on-surface` for `on-background`, `surface-container-highest` for `surface-variant` and `primary` for `surface-tint`.',
+    // A bare `background` class is a common name of a page's own, so only the
+    // role's `-text` class is flagged.
+    pattern: new RegExp(`--md-sys-color-(?:background|on-background|surface-variant|surface-tint)(?:-light|-dark)?(?![-\\w])|${inClass('background-text|(?:on-background|surface-variant|surface-tint)(?:-text)?')}`, 'g'),
+  },
+  {
+    id: 'legacy-selector',
+    severity: 'high',
+    description: 'A CSS selector or query names a class 0.16.0 removed: `.preloader`, `.searchbar`, `.range-field`, `.datepicker` / `.timepicker` (now `.date-picker` / `.time-picker`), `.toolbar.max` / `.toolbar.filled`, `.tooltip.max`, `.chip.active`, `.carousel.flat` or a legacy color role class. See the replacements in the other `legacy-*` rules.',
+    pattern: /(?<![\w$)\]-])\.(?:preloader|searchbar|range-field|(?:date|time)picker|(?:toolbar|tooltip)\.(?:max|filled)|chip\.active|carousel\.flat|(?:on-background|surface-variant|surface-tint)(?:-text)?|background-text)(?![-\w])/g,
+  },
+  {
+    id: 'legacy-datepicker-range',
+    severity: 'high',
+    description: 'Datepicker `startRange` and `endRange` were removed in 0.16.0; use `isDateRange` for range selection.',
+    pattern: /[{,]\s*(["']?)\b(?:startRange|endRange)\1\s*:/g,
+  },
+  {
+    id: 'legacy-range-export',
+    severity: 'high',
+    description: '`Expressive.Range` was removed in 0.16.0; use `Expressive.Slider`.',
+    pattern: /\bExpressive\.Range\b/g,
+  },
   {
     id: 'raw-color-in-component-style',
     severity: 'medium',
@@ -322,16 +441,32 @@ function resolveProjectRoot(projectRoot) {
   return projectRoot ? authorizedProjectRoot(projectRoot) : parseCliProjectRoot();
 }
 
-// The operator's default root is trusted. When configured, a client-supplied root must sit inside an allowed root.
+// Unconfigured, the only allowed root is the default one.
+function projectRootPolicy() {
+  return SETTINGS.allowedProjectRoots
+    ? { roots: SETTINGS.allowedProjectRoots, denial: `projectRoot is not inside a root allowed by ${PROJECT_ROOTS_SETTING}.` }
+    : { roots: [parseCliProjectRoot()], denial: `projectRoot is missing or outside the server's root; list other roots in ${PROJECT_ROOTS_SETTING}.` };
+}
+
+// The operator's default root is trusted. A client-supplied root must sit inside an allowed root.
 function authorizedProjectRoot(projectRoot) {
-  const resolved = path.resolve(projectRoot);
-  if (!SETTINGS.allowedProjectRoots) return resolved;
-  let canonical = null;
-  try { canonical = realpathSync(resolved); } catch {}
-  if (!canonical || !matchingRoot(SETTINGS.allowedProjectRoots, canonical)) {
-    throw new Error(`projectRoot is not inside a root allowed by ${PROJECT_ROOTS_SETTING}.`);
-  }
-  return resolved;
+  const policy = projectRootPolicy();
+  const canonical = canonicalPath(path.resolve(projectRoot), policy.roots);
+  if (!canonical || !matchingRoot(policy.roots, canonical)) throw new Error(policy.denial);
+  // The checked path, so a symlink swapped after the check cannot move later reads.
+  return canonical;
+}
+
+// Resolving a Windows network path (\\host\share) contacts that host, so only
+// one under a root the operator listed is resolved.
+function isUnlistedNetworkPath(resolved, roots) {
+  return process.platform === 'win32' && /^[\\/]{2}/u.test(resolved)
+    && !roots.some((root) => isPathInside(path.resolve(root), resolved));
+}
+
+function canonicalPath(resolved, roots) {
+  if (isUnlistedNetworkPath(resolved, roots)) return null;
+  try { return realpathSync(resolved); } catch { return null; }
 }
 
 function matchingRoot(configuredRoots, candidate) {
@@ -633,22 +768,6 @@ function sameFileIdentity(left, right) {
   return left.dev === right.dev && left.ino === right.ino;
 }
 
-async function readHandleBounded(handle, maxBytes) {
-  const chunks = [];
-  let totalBytes = 0;
-  while (totalBytes <= maxBytes) {
-    const buffer = Buffer.allocUnsafe(Math.min(64 * 1024, (maxBytes + 1) - totalBytes));
-    const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
-    if (bytesRead === 0) break;
-    chunks.push(buffer.subarray(0, bytesRead));
-    totalBytes += bytesRead;
-  }
-  return {
-    content: totalBytes > maxBytes ? null : Buffer.concat(chunks, totalBytes),
-    totalBytes,
-  };
-}
-
 async function verifyLocalContractProvenance(projectRoot, contract, canonicalSources) {
   if (!contract) {
     return { status: 'missing', expectedHash: null, computedHash: null, missingSources: [] };
@@ -702,60 +821,24 @@ async function verifyLocalContractProvenance(projectRoot, contract, canonicalSou
     if (aggregateBytes > MAX_CONTRACT_TOTAL_BYTES) {
       return { status: 'invalid', expectedHash: contract.sourceHash, computedHash: null, missingSources };
     }
-    validatedSources.push({ source, sourcePath: resolvedSourcePath, sourceStat });
+    validatedSources.push({ source, sourcePath: resolvedSourcePath });
   }
   if (missingSources.length) {
     return { status: 'missing', expectedHash: contract.sourceHash, computedHash: null, missingSources };
   }
 
-  const hash = createHash('sha256');
+  const hasher = createHash('sha256');
   aggregateBytes = 0;
-  for (const { source, sourcePath, sourceStat } of validatedSources) {
-    const handle = await open(sourcePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW).catch(() => null);
-    if (!handle) {
+  for (const { source, sourcePath } of validatedSources) {
+    const limit = Math.min(MAX_CONTRACT_SOURCE_BYTES, Math.max(0, MAX_CONTRACT_TOTAL_BYTES - aggregateBytes));
+    const content = await readBoundedRegularFile(sourcePath, limit, 'contract source', root, null).catch(() => null);
+    if (!content) {
       return { status: 'invalid', expectedHash: contract.sourceHash, computedHash: null, missingSources };
     }
-    try {
-      const openedStat = await handle.stat();
-      const currentPathStat = await lstat(sourcePath).catch(() => null);
-      const currentResolvedPath = await realpath(sourcePath).catch(() => null);
-      const openedResolvedPath = await realpath(`/proc/self/fd/${handle.fd}`).catch(() => currentResolvedPath);
-      if (
-        !openedStat.isFile()
-        || !currentPathStat?.isFile()
-        || currentPathStat.isSymbolicLink()
-        || !currentResolvedPath
-        || !openedResolvedPath
-        || !isPathInside(root, currentResolvedPath)
-        || currentResolvedPath !== sourcePath
-        || openedResolvedPath !== sourcePath
-        || !sameFileIdentity(sourceStat, openedStat)
-        || !sameFileIdentity(openedStat, currentPathStat)
-        || openedStat.size > MAX_CONTRACT_SOURCE_BYTES
-      ) {
-        return { status: 'invalid', expectedHash: contract.sourceHash, computedHash: null, missingSources };
-      }
-
-      const remainingAggregateBytes = Math.max(0, MAX_CONTRACT_TOTAL_BYTES - aggregateBytes);
-      const bounded = await readHandleBounded(handle, Math.min(MAX_CONTRACT_SOURCE_BYTES, remainingAggregateBytes));
-      aggregateBytes += bounded.totalBytes;
-      const finalStat = await handle.stat();
-      if (
-        !bounded.content
-        || aggregateBytes > MAX_CONTRACT_TOTAL_BYTES
-        || !sameFileIdentity(openedStat, finalStat)
-        || openedStat.size !== finalStat.size
-        || openedStat.mtimeMs !== finalStat.mtimeMs
-        || openedStat.ctimeMs !== finalStat.ctimeMs
-      ) {
-        return { status: 'invalid', expectedHash: contract.sourceHash, computedHash: null, missingSources };
-      }
-      hash.update(`${source}\0${bounded.content.toString('utf8')}\0`);
-    } finally {
-      await handle.close();
-    }
+    aggregateBytes += content.length;
+    hasher.update(`${source}\0${content.toString('utf8')}\0`);
   }
-  const computedHash = hash.digest('hex');
+  const computedHash = hasher.digest('hex');
   return {
     status: computedHash === contract.sourceHash ? 'verified' : 'stale',
     expectedHash: contract.sourceHash,
@@ -1023,45 +1106,6 @@ function loadSemanticsContract() {
   return semanticsCache;
 }
 
-function enforcedSemanticRules(data) {
-  return Object.entries(data.rows)
-    .filter(([, component]) => component.status === 'enforced')
-    .flatMap(([component, definition]) => definition.rules.map((rule) => ({ ...rule, component })));
-}
-
-function expandedSemanticSelector(rule, compositeRoles) {
-  if (rule.kind !== 'forbid-composite-roles') {
-    return rule.selector;
-  }
-  return compositeRoles.map((role) => `${rule.selector}[role="${role}"]`).join(', ');
-}
-
-function authoredName(element, document) {
-  const label = element.getAttribute('aria-label');
-  if (label?.trim()) {
-    return label.trim();
-  }
-  const labelledBy = element.getAttribute('aria-labelledby');
-  if (!labelledBy) {
-    return '';
-  }
-  return labelledBy
-    .split(/\s+/u)
-    .map((id) => document.getElementById(id)?.textContent ?? '')
-    .join(' ')
-    .trim();
-}
-
-function accessibleName(element, document) {
-  const authored = authoredName(element, document);
-  if (authored) {
-    return authored;
-  }
-  const clone = element.cloneNode(true);
-  clone.querySelectorAll('[aria-hidden="true"]').forEach((node) => node.remove());
-  return clone.textContent.trim();
-}
-
 function markInspectionTruncated(issues, reason) {
   Object.defineProperty(issues, 'truncatedReason', { value: reason, enumerable: false });
   return issues;
@@ -1081,15 +1125,41 @@ function markupStructureExceedsLimit(snippet) {
   return false;
 }
 
+// An HTML template's parsed markup lives in its content fragment, which outerHTML still
+// serializes. A `template` inside SVG or MathML (Vue's v-for) is an ordinary element.
+function childElements(element) {
+  return element.localName === 'template' && element.content
+    ? [...element.children, ...element.content.children]
+    : element.children;
+}
+
+function markupNestingExceedsLimit(root) {
+  const stack = [[root, 0]];
+  while (stack.length) {
+    const [element, depth] = stack.pop();
+    if (depth > MAX_STATIC_MARKUP_DEPTH) return true;
+    for (const child of childElements(element)) stack.push([child, depth + 1]);
+  }
+  return false;
+}
+
+// Parses a snippet, or names the limit that stops it: tag count before parsing, depth after.
+function parseInspectableMarkup(snippet, prefix, includeNodeLocations) {
+  if (markupStructureExceedsLimit(snippet)) return { reason: 'markup structure limit reached' };
+  // Loaded on first use: jsdom takes ~0.3 s to load, and most server starts never inspect markup.
+  const { JSDOM } = createRequire(import.meta.url)('jsdom');
+  const dom = new JSDOM(`${prefix}${snippet}</body>`, { includeNodeLocations });
+  if (markupNestingExceedsLimit(dom.window.document.body)) return { reason: 'markup nesting limit reached' };
+  return { dom };
+}
+
 function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline = Infinity) {
   const { semantics, frameworkVersion } = loadSemanticsContract();
   if (maxIssues <= 0) return markInspectionTruncated([], 'issue limit reached');
-  if (markupStructureExceedsLimit(snippet)) return markInspectionTruncated([], 'markup structure limit reached');
   const prefix = '<!doctype html><body>';
   const includeNodeLocations = snippet.length * (snippet.split('<').length - 1) <= MAX_LOCATED_MARKUP_WORK;
-  // Loaded on first use: jsdom takes ~0.3 s to load, and most server starts never inspect markup.
-  const { JSDOM } = createRequire(import.meta.url)('jsdom');
-  const dom = new JSDOM(`${prefix}${snippet}</body>`, { includeNodeLocations });
+  const { dom, reason } = parseInspectableMarkup(snippet, prefix, includeNodeLocations);
+  if (reason) return markInspectionTruncated([], reason);
   const { document } = dom.window;
   // Elements the parser creates without a start tag have no source offset, so they report the start.
   const locate = (element) => {
@@ -1098,34 +1168,14 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
   };
   const issues = [];
 
-  for (const rule of enforcedSemanticRules(semantics)) {
+  for (const rule of enforcedRules(semantics)) {
     const beforeRule = inspectionStopReason(issues, maxIssues, deadline);
     if (beforeRule) return markInspectionTruncated(issues, beforeRule);
-    const hits = document.querySelectorAll(expandedSemanticSelector(rule, semantics.compositeRoles));
-    if (rule.kind === 'forbid' || rule.kind === 'forbid-composite-roles') {
-      for (const element of hits) {
-        const stop = inspectionStopReason(issues, maxIssues, deadline);
-        if (stop) return markInspectionTruncated(issues, stop);
-        issues.push(semanticIssue(rule, element, frameworkVersion, locate(element)));
-      }
-    } else if (rule.kind === 'require-attr') {
-      for (const element of hits) {
-        const stop = inspectionStopReason(issues, maxIssues, deadline);
-        if (stop) return markInspectionTruncated(issues, stop);
-        const value = element.getAttribute(rule.attr);
-        const valid = rule.equals ? value === rule.equals : value !== null && value !== '';
-        if (!valid) {
-          issues.push(semanticIssue(rule, element, frameworkVersion, locate(element)));
-        }
-      }
-    } else if (rule.kind === 'require-accessible-name') {
-      for (const element of hits) {
-        const stop = inspectionStopReason(issues, maxIssues, deadline);
-        if (stop) return markInspectionTruncated(issues, stop);
-        if (!accessibleName(element, document)) {
-          issues.push(semanticIssue(rule, element, frameworkVersion, locate(element)));
-        }
-      }
+    const breaks = ruleBreach(rule);
+    for (const element of document.querySelectorAll(expandedSelector(rule, semantics.compositeRoles))) {
+      const stop = inspectionStopReason(issues, maxIssues, deadline);
+      if (stop) return markInspectionTruncated(issues, stop);
+      if (breaks(element, document)) issues.push(semanticIssue(rule, element, frameworkVersion, locate(element)));
     }
   }
 
@@ -1173,6 +1223,9 @@ function lineForMatch(text, index) {
   return { line, column: col };
 }
 
+// The legacy and retired-markup rules, for tests that check each one alone.
+export const authoringRules = LegacyPatternList;
+
 export function inspectAuthoringRules(
   snippet,
   maxIssues = MAX_STATIC_ISSUES,
@@ -1511,10 +1564,15 @@ function summarizeGuide(guide, { sections, detail, includeCapabilities }) {
 
 function summarizeProjectFiles(files, projectRoot) {
   const resolvedRoot = realpathSync(path.resolve(projectRoot));
+  const roots = [resolvedRoot, path.resolve(projectRoot)];
   const absoluteFiles = files.map((filePath) => {
     const requestedPath = path.isAbsolute(filePath)
       ? path.resolve(filePath)
       : path.resolve(resolvedRoot, filePath);
+    // Touch nothing outside the root, so the reply cannot say whether a host path exists.
+    if (!roots.some((root) => isPathInside(root, requestedPath))) {
+      return { requested: filePath, absolute: requestedPath, exists: false, insideProject: false };
+    }
     const exists = existsSync(requestedPath);
     const absolute = exists ? realpathSync(requestedPath) : requestedPath;
     return {
@@ -1533,14 +1591,14 @@ function summarizeProjectFiles(files, projectRoot) {
       skipped.push({ ...item, reason: 'file limit reached' });
       continue;
     }
-    if (!item.exists) {
-      skipped.push({ ...item, reason: 'file does not exist' });
-      continue;
-    }
     if (!item.insideProject) {
       skipped.push({ ...item, reason: 'file is outside projectRoot' });
       continue;
     }
+    if (!item.exists) {
+      skipped.push({ ...item, reason: 'file does not exist' });
+      continue;
+    }
     if (path.relative(resolvedRoot, item.absolute).split(path.sep).includes('node_modules')) {
       skipped.push({ ...item, reason: 'node_modules is excluded' });
       continue;
@@ -1594,6 +1652,10 @@ function commandEnvironment(projectRoot) {
   return env;
 }
 
+// Commands run in their own process group, so a signal to the server does not reach them.
+// startServer kills these on shutdown.
+const liveCommands = new Set();
+
 function stopProcessTree(proc, signal) {
   if (!proc.pid) return;
   if (process.platform === 'win32') {
@@ -1633,48 +1695,14 @@ export function redactSensitiveText(value) {
     .replace(/[A-Z]:\\+Users\\+[^\\\s]+(?:\\+[^\s]*)?/giu, '[LOCAL_PATH]');
 }
 
+// Directories above the file may be links (callers pass realpaths beside lexical roots);
+// the file itself may not, and it must resolve inside projectRoot.
 export async function readInspectionFile(filePath, projectRoot, byteLimit) {
-  const resolvedRoot = await realpath(projectRoot);
-  const noFollow = Number.isInteger(fsConstants.O_NOFOLLOW) ? fsConstants.O_NOFOLLOW : 0;
-  const handle = await open(filePath, fsConstants.O_RDONLY | noFollow);
-  try {
-    const before = await handle.stat({ bigint: true });
-    const pathBefore = await lstat(filePath, { bigint: true });
-    if (pathBefore.isSymbolicLink()) throw new Error('path is a symbolic link');
-    if (!before.isFile() || !pathBefore.isFile()) throw new Error('path is not a regular file');
-    if (before.dev !== pathBefore.dev || before.ino !== pathBefore.ino) throw new Error('file identity changed before reading');
-    const openedPath = await realpath(`/proc/self/fd/${handle.fd}`).catch(() => realpath(filePath));
-    if (!isPathInside(resolvedRoot, openedPath)) throw new Error('opened file is outside projectRoot');
-    if (before.size > BigInt(byteLimit)) {
-      const error = new Error(`file exceeds ${byteLimit} byte read limit`);
-      error.code = 'INSPECTION_FILE_TOO_LARGE';
-      throw error;
-    }
-
-    // Size the buffer to the file, not the limit. The spare byte exposes growth
-    // and files such as /proc entries that report a smaller size than they hold.
-    const capacity = Number(before.size) + 1;
-    const bytes = Buffer.allocUnsafe(capacity);
-    let total = 0;
-    while (total < capacity) {
-      const chunk = await handle.read(bytes, total, capacity - total, total);
-      if (chunk.bytesRead === 0) break;
-      total += chunk.bytesRead;
-    }
-    if (total > before.size) throw new Error('file changed while reading');
-
-    const after = await handle.stat({ bigint: true });
-    const pathAfter = await lstat(filePath, { bigint: true });
-    if (pathAfter.isSymbolicLink() || !pathAfter.isFile()
-      || before.dev !== after.dev || before.ino !== after.ino
-      || before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs
-      || after.dev !== pathAfter.dev || after.ino !== pathAfter.ino) {
-      throw new Error('file changed while reading');
-    }
-    return { text: bytes.subarray(0, total).toString('utf8'), bytes: total, sha256: createHash('sha256').update(bytes.subarray(0, total)).digest('hex') };
-  } finally {
-    await handle.close();
-  }
+  const root = await realpath(projectRoot);
+  const target = path.join(await realpath(path.dirname(path.resolve(filePath))), path.basename(filePath));
+  if (!isPathInside(root, target)) throw new Error('opened file is outside projectRoot');
+  const bytes = await readBoundedRegularFile(target, byteLimit, 'inspected', root, null);
+  return { text: bytes.toString('utf8'), bytes: bytes.length, sha256: hash('sha256', bytes) };
 }
 
 async function findFileViolations(fileInfoList, projectRoot) {
@@ -1728,7 +1756,7 @@ async function findFileViolations(fileInfoList, projectRoot) {
         inspected.push(file.requested);
       }
     } catch (error) {
-      const aggregateLimit = error.code === 'INSPECTION_FILE_TOO_LARGE' && maxTotalBytes - totalBytes < maxBytes;
+      const aggregateLimit = error.code === 'oversized' && maxTotalBytes - totalBytes < maxBytes;
       uninspected.push({
         file: file.requested,
         reason: aggregateLimit
@@ -1748,7 +1776,7 @@ async function findFileViolations(fileInfoList, projectRoot) {
   return { findings, inspected, uninspected, sourcePins };
 }
 
-async function runCommandInProject(projectRoot, manager, script, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
+async function runCommandInProject(projectRoot, manager, script, timeoutMs, signal) {
   const args = ['run', script];
   const command = `${manager} ${args.join(' ')}`;
   const configuredTimeout = Number.isFinite(SETTINGS.commandTimeoutMs) && SETTINGS.commandTimeoutMs > 0
@@ -1792,6 +1820,9 @@ async function runCommandInProject(projectRoot, manager, script, timeoutMs = DEF
       env: commandEnvironment(projectRoot),
     });
     closeSync(directoryFd);
+    liveCommands.add(proc);
+    const abort = () => stopProcessTree(proc, 'SIGKILL');
+    signal.addEventListener('abort', abort, { once: true });
 
     let stdout = '';
     let stderr = '';
@@ -1802,6 +1833,7 @@ async function runCommandInProject(projectRoot, manager, script, timeoutMs = DEF
       if (settled) return;
       settled = true;
       clearTimeout(timer);
+      signal.removeEventListener('abort', abort);
       if (!timedOut) clearTimeout(forceKillTimer);
       resolve(result);
     };
@@ -1838,6 +1870,7 @@ async function runCommandInProject(projectRoot, manager, script, timeoutMs = DEF
 
     proc.on('close', (code) => {
       stopProcessTree(proc, 'SIGKILL'); // Stop descendants before checking the resulting source state.
+      liveCommands.delete(proc);
       const output = redactSensitiveText(`${stdout}\n${stderr}`);
       finish({
         manager,
@@ -1852,6 +1885,7 @@ async function runCommandInProject(projectRoot, manager, script, timeoutMs = DEF
     });
 
     proc.on('error', (error) => {
+      liveCommands.delete(proc);
       finish({
         manager,
         command,
@@ -1881,13 +1915,17 @@ async function pinsUnchanged(projectRoot, pins) {
   return true;
 }
 
-async function runQualityCommands(projectRoot, commands, packageManager, pins) {
+// Exported for the smoke test, which cancels a run while the source pins are being checked.
+export async function runQualityCommands(projectRoot, commands, packageManager, pins, signal) {
   const results = [];
   let unchanged = true;
   for (const script of commands) {
     unchanged = await pinsUnchanged(projectRoot, pins);
+    // Checked after the await, with nothing awaited before the spawn: an abort listener added
+    // to a signal that is already aborted never fires. The SDK drops a cancelled call's result.
+    signal.throwIfAborted();
     if (!unchanged) break;
-    const result = await runCommandInProject(projectRoot, packageManager, script, script === 'typecheck' ? 180_000 : 360_000);
+    const result = await runCommandInProject(projectRoot, packageManager, script, script === 'typecheck' ? 180_000 : 360_000, signal);
     results.push(result);
     unchanged = await pinsUnchanged(projectRoot, pins);
     if (!unchanged || !result.completed || result.exitStatus !== 0) break;
@@ -2434,7 +2472,7 @@ function buildCatalogPayload(catalog, version, parsed) {
   }, parsed.workflowId);
 }
 
-async function qualityInspectorHandler(args) {
+async function qualityInspectorHandler(args, extra) {
   if (skipTool('qualityInspector')) {
     return skippedStage('quality_inspector', 'SKIP_QUALITY_INSPECTOR', args?.workflowId);
   }
@@ -2476,7 +2514,7 @@ async function qualityInspectorHandler(args) {
   }
   let inputsUnchanged = await pinsUnchanged(projectRoot, pins);
   if (commandsRequested && !commandRootBlocked && !commandScopeBlocked && !packageManagerBlocked && !manifestBlocked && expectedMatched !== false && inputsUnchanged) {
-    const run = await runQualityCommands(executionPolicy.projectRoot, commands, version.packageManager, pins);
+    const run = await runQualityCommands(executionPolicy.projectRoot, commands, version.packageManager, pins, extra.signal);
     commandChecks.push(...run.results);
     inputsUnchanged = run.unchanged;
   }
@@ -2840,11 +2878,19 @@ async function startServer() {
   const close = transport.close.bind(transport);
   transport.close = async () => { try { await close(); } finally { scopedRequests.clear(); } };
   await server.connect(transport);
+  // The client closing stdin or signalling the server ends the session; take running commands with it.
+  const shutdown = () => {
+    for (const proc of liveCommands) stopProcessTree(proc, 'SIGKILL');
+    process.exit();
+  };
+  process.once('SIGINT', shutdown);
+  process.once('SIGTERM', shutdown);
+  process.stdin.once('end', shutdown);
   console.error('ExpressiveCSS MCP server running on stdio transport.');
 }
 
 // Only run as the entry point; lint.mjs imports the static checks without starting the server.
-if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) {
+if (import.meta.main) {
   startServer().catch((error) => {
     console.error('ExpressiveCSS MCP server failed to start:', error);
     process.exitCode = 1;