@expressivecss/mcp-server 0.4.1 → 0.5.0

package/contract.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
   "generatedBy": "scripts/gen-expressivecss-skill.mjs",
-  "frameworkVersion": "0.15.0",
-  "skillVersion": "0.11.0",
-  "matchingTag": "v0.15.0",
+  "frameworkVersion": "0.16.0",
+  "skillVersion": "0.12.0",
+  "matchingTag": "v0.16.0",
   "releaseTags": [
     "v0.10.0",
     "v0.10.1",
@@ -14,6 +14,7 @@
     "v0.14.0",
     "v0.14.1",
     "v0.15.0",
+    "v0.16.0",
     "v0.5.0",
     "v0.6.0",
     "v0.7.0",
@@ -30,5 +31,5 @@
     "package.json",
     "CHANGELOG.md"
   ],
-  "sourceHash": "e1c777a1bcd53d5a6ed4615075a7a500fb6f488050e727487804f8cc421b5902"
+  "sourceHash": "d005fbd1fc75538ac5f20a4024adbd044ab3d31d3a3ff9c34b268a74c26b1d5a"
 }

package/lint.mjs

@@ -9,9 +9,8 @@
  *                                    it is a markup file, exit 2 on findings
  *                                    so the message goes back to the agent.
  */
-import { readFileSync, realpathSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { inspectAuthoringRules, readInspectionFile } from './server.js';
 
 // Markdown is left out: a doc concatenates many independent examples, so page-level rules misfire.
@@ -28,7 +27,12 @@ export async function lintFile(file) {
     return [problem('file-not-inspected', `Skipped: ${error.message}. Files must be regular, inside the working directory, and at most ${MAX_BYTES} bytes.`)];
   }
   // ponytail: JSX/Astro/Vue are parsed as HTML after `className` -> `class`; expression-heavy markup can hide from selector rules.
-  const issues = inspectAuthoringRules(text.replace(/\bclassName=/gu, 'class='));
+  let issues;
+  try {
+    issues = inspectAuthoringRules(text.replace(/\bclassName=/gu, 'class='));
+  } catch (error) {
+    return [problem('file-not-inspected', `Static inspection failed: ${error.message}.`)];
+  }
   if (issues.truncatedReason) issues.push(problem('inspection-truncated', `Static inspection stopped early: ${issues.truncatedReason}. Split the file or reduce its markup.`));
   return issues;
 }
@@ -63,6 +67,6 @@ async function main(argv) {
   return total ? 1 : 0;
 }
 
-if (process.argv[1] && pathToFileURL(realpathSync(process.argv[1])).href === import.meta.url) {
+if (import.meta.main) {
   process.exitCode = await main(process.argv.slice(2));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expressivecss/mcp-server",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "ExpressiveCSS MCP server with Design→QA workflow tools.",
   "homepage": "https://www.expressivecss.com",
   "repository": {
@@ -32,6 +32,8 @@
     "semantics-data.json",
     "smoke.mjs",
     "scripts/resolve-version.mjs",
+    "scripts/bounded-file.mjs",
+    "scripts/semantics-rules.mjs",
     "README.md",
     "mcp.json",
     ".claude-plugin/plugin.json",
@@ -45,6 +47,6 @@
     "zod": "^4.6.5"
   },
   "overrides": {
-    "qs": "6.16.0"
+    "qs": "6.16.1"
   }
 }

package/scripts/bounded-file.mjs

@@ -0,0 +1,73 @@
+// Generated from scripts/lib/bounded-file.mjs. Do not edit.
+import { constants as fsConstants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+
+function isPathInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+// Codes let callers that report a status instead of throwing map each refusal.
+const fail = (message, code) => Object.assign(new Error(message), { code });
+
+export async function readBoundedRegularFile(filePath, byteLimit, label, expectedRoot = null, encoding = 'utf8') {
+  const target = path.resolve(filePath);
+  let resolvedRoot = null;
+  if (expectedRoot) {
+    const rootPrefix = path.join(path.resolve(expectedRoot), path.sep);
+    if (!target.startsWith(rootPrefix)) {
+      throw fail(`${label} file is outside the repository`, 'outside-root');
+    }
+    resolvedRoot = await realpath(expectedRoot);
+    const relative = path.relative(rootPrefix, target);
+    let current = resolvedRoot;
+    for (const segment of relative.split(path.sep)) {
+      current = path.join(current, segment);
+      const entry = await lstat(current, { bigint: true });
+      if (entry.isSymbolicLink()) throw fail(`${label} file path contains a symbolic link`, 'symbolic-link');
+    }
+  }
+
+  const noFollow = Number.isInteger(fsConstants.O_NOFOLLOW) ? fsConstants.O_NOFOLLOW : 0;
+  const nonBlocking = Number.isInteger(fsConstants.O_NONBLOCK) ? fsConstants.O_NONBLOCK : 0;
+  const handle = await open(target, fsConstants.O_RDONLY | noFollow | nonBlocking);
+  try {
+    const before = await handle.stat({ bigint: true });
+    const pathBefore = await lstat(target, { bigint: true });
+    if (pathBefore.isSymbolicLink()) throw fail(`${label} file is a symbolic link`, 'symbolic-link');
+    if (!before.isFile() || !pathBefore.isFile()) throw fail(`${label} file is not a regular file`, 'not-regular-file');
+    if (before.dev !== pathBefore.dev || before.ino !== pathBefore.ino) {
+      throw fail(`${label} file identity changed before reading`, 'identity-changed');
+    }
+    if (resolvedRoot) {
+      const openedPath = await realpath(`/proc/self/fd/${handle.fd}`).catch(() => realpath(target));
+      if (!isPathInside(resolvedRoot, openedPath)) throw fail(`${label} file is outside the repository`, 'outside-root');
+    }
+    if (before.size > BigInt(byteLimit)) throw fail(`${label} file exceeds ${byteLimit} bytes`, 'oversized');
+
+    // 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 fail(`${label} file changed while reading`, 'identity-changed');
+
+    const after = await handle.stat({ bigint: true });
+    const pathAfter = await lstat(target, { bigint: true });
+    const handleChanged = before.dev !== after.dev || before.ino !== after.ino
+      || before.size !== after.size || before.mtimeNs !== after.mtimeNs || before.ctimeNs !== after.ctimeNs;
+    const pathChanged = pathAfter.isSymbolicLink() || !pathAfter.isFile()
+      || after.dev !== pathAfter.dev || after.ino !== pathAfter.ino;
+    if (handleChanged || pathChanged) throw fail(`${label} file changed while reading`, 'identity-changed');
+    const content = bytes.subarray(0, total);
+    return encoding === null ? content : content.toString(encoding);
+  } finally {
+    await handle.close();
+  }
+}

package/scripts/resolve-version.mjs

@@ -1,8 +1,8 @@
 // Generated from scripts/lib/resolve-expressivecss-version.mjs. Do not edit.
-import { constants as fsConstants } from 'node:fs';
-import { lstat, open, realpath } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { readBoundedRegularFile } from './bounded-file.mjs';
 
 const PACKAGE_NAME = '@expressivecss/expressive';
 const MAX_MANIFEST_BYTES = 1 * 1024 * 1024;
@@ -16,46 +16,17 @@ function readLimit(filePath) {
   return MAX_MANIFEST_BYTES;
 }
 
-function sameFile(left, right) {
-  return left.dev === right.dev && left.ino === right.ino && left.size === right.size
-    && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
-}
+const READ_REFUSALS = new Set(['symbolic-link', 'not-regular-file', 'identity-changed', 'oversized']);
+const OPEN_LINK_ERRORS = new Set(['ELOOP', 'EMLINK']);
 
+// No root: node_modules may be a link farm (pnpm), so only the file itself must not be a link.
 async function readBounded(filePath) {
-  let handle;
   try {
-    const pathBefore = await lstat(filePath, { bigint: true });
-    if (pathBefore.isSymbolicLink()) return { error: 'symbolic-link' };
-    if (!pathBefore.isFile()) return { error: 'not-regular-file' };
-    const noFollow = fsConstants.O_NOFOLLOW ?? 0;
-    handle = await open(filePath, fsConstants.O_RDONLY | noFollow);
-    const before = await handle.stat({ bigint: true });
-    if (!before.isFile() || !sameFile(before, pathBefore)) return { error: 'identity-changed' };
-    const limit = readLimit(filePath);
-    if (before.size > BigInt(limit)) return { error: 'oversized' };
-    // Size the buffer to the file, not the limit. The spare byte exposes growth.
-    const buffer = Buffer.allocUnsafe(Number(before.size) + 1);
-    let offset = 0;
-    while (offset < buffer.length) {
-      const { bytesRead } = await handle.read(buffer, offset, buffer.length - offset, offset);
-      if (bytesRead === 0) break;
-      offset += bytesRead;
-    }
-    if (offset > before.size) return { error: 'identity-changed' };
-    const after = await handle.stat({ bigint: true });
-    const pathAfter = await lstat(filePath, { bigint: true });
-    const currentResolved = await realpath(filePath);
-    const openedResolved = await realpath(`/proc/self/fd/${handle.fd}`).catch(() => currentResolved);
-    if (!sameFile(before, after) || !sameFile(after, pathAfter) || currentResolved !== openedResolved) {
-      return { error: 'identity-changed' };
-    }
-    return { text: buffer.subarray(0, offset).toString('utf8') };
+    return { text: await readBoundedRegularFile(filePath, readLimit(filePath), path.basename(filePath)) };
   } catch (error) {
     if (error?.code === 'ENOENT') return { missing: true };
-    if (error?.code === 'ELOOP' || error?.code === 'EMLINK') return { error: 'symbolic-link' };
-    return { error: 'unreadable' };
-  } finally {
-    await handle?.close().catch(() => {});
+    if (OPEN_LINK_ERRORS.has(error?.code)) return { error: 'symbolic-link' };
+    return { error: READ_REFUSALS.has(error?.code) ? error.code : 'unreadable' };
   }
 }
 
@@ -76,10 +47,10 @@ async function readJson(filePath) {
 
 function cleanVersion(value) {
   if (typeof value !== 'string') return null;
-  const cleaned = value.trim().replace(/^['"]|['"]$/gu, '').replace(/\(.+\)$/u, '');
-  return /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/u.test(cleaned)
-    ? cleaned
-    : null;
+  // One anchored pass: a free-floating /\(.+\)$/ retried from every "(" and
+  // went quadratic on a long run of them.
+  const cleaned = value.trim().replace(/^['"]|['"]$/gu, '');
+  return /^(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?)(?:\(.+\))?$/u.exec(cleaned)?.[1] ?? null;
 }
 
 export function parseSemver(value) {
@@ -312,8 +283,9 @@ function pnpmLockResolution(text, declaredRange) {
     if (targetLines[index].trim() && /^\s*/u.exec(targetLines[index])[0].length <= 6) break;
     dependencyLines.push(targetLines[index]);
   }
-  const specifier = /^\s+specifier:\s*['"]?([^'"\s]+)['"]?\s*$/mu.exec(dependencyLines.join('\n'))?.[1] ?? null;
-  const rawVersion = /^\s+version:\s*['"]?([^'"\s]+)['"]?\s*$/mu.exec(dependencyLines.join('\n'))?.[1] ?? null;
+  // [ \t], not \s: \s crossed newlines, so blank lines made the scan quadratic.
+  const specifier = /^[ \t]+specifier:[ \t]*['"]?([^'"\s]+)['"]?[ \t]*$/mu.exec(dependencyLines.join('\n'))?.[1] ?? null;
+  const rawVersion = /^[ \t]+version:[ \t]*['"]?([^'"\s]+)['"]?[ \t]*$/mu.exec(dependencyLines.join('\n'))?.[1] ?? null;
   if (specifier !== declaredRange) {
     return {
       version: null,
@@ -689,16 +661,13 @@ export async function resolveExpressiveVersion({
     projectRoot: root,
     packageManager: lock.packageManager,
     declaredRange,
-    declaredVersion: declaredRange,
     resolvedVersion,
     exactInstalledVersion: resolutionSource === 'installed-package' ? resolvedVersion : null,
     resolutionSource,
     skillVersion: normalizedSkillVersion,
-    skillContractVersion: normalizedContract,
     contractVersion: normalizedContract,
     contractSourceHash: contract?.sourceHash ?? null,
     matchingTag,
-    matchingCommit: null,
     status,
     contractStatus: status,
     documentationMode,
@@ -712,22 +681,10 @@ export async function resolveExpressiveVersion({
   };
 }
 
-function cliArguments(argv) {
-  const values = {};
-  for (let index = 0; index < argv.length; index += 1) {
-    const argument = argv[index];
-    if (!argument.startsWith('--')) continue;
-    const [key, ...rest] = argument.slice(2).split('=');
-    if (rest.length) values[key] = rest.join('=');
-    else if (argv[index + 1] && !argv[index + 1].startsWith('--')) values[key] = argv[index += 1];
-    else values[key] = true;
-  }
-  return values;
-}
-
 const invokedPath = process.argv[1] ? path.resolve(process.argv[1]) : null;
 if (invokedPath === fileURLToPath(import.meta.url)) {
-  const args = cliArguments(process.argv.slice(2));
+  const option = { type: 'string' };
+  const { values: args } = parseArgs({ strict: false, allowPositionals: true, options: { 'project-root': option, 'contract-version': option, 'skill-version': option } });
   const result = await resolveExpressiveVersion({
     projectRoot: typeof args['project-root'] === 'string' ? args['project-root'] : process.cwd(),
     contractVersion: typeof args['contract-version'] === 'string' ? args['contract-version'] : null,

package/scripts/semantics-rules.mjs

@@ -0,0 +1,184 @@
+// Generated from scripts/semantics-rules.mjs. Do not edit.
+/**
+ * The semantics.json rule engine, shared by the two seams that run it.
+ *
+ * tests/semantics.test.js runs it over authored fragments -- the examples a
+ * reader copies, in llm.md, the documentation pages and tests/fixtures.js.
+ * scripts/verify-site.mjs runs it over the built pages, where chrome and
+ * content finally meet and document-level rules like main-not-nested become
+ * answerable at all.
+ *
+ * It lives under scripts/ rather than tests/ because a test file cannot be
+ * imported without running its tests. The MCP server ships a generated copy
+ * and walks the hits itself, so it can stop early and report locations.
+ */
+
+import { createRequire } from 'node:module';
+
+// Loaded on first parse: jsdom takes ~0.3 s, and most MCP server starts never inspect markup.
+const parse = (html) => new (createRequire(import.meta.url)('jsdom').JSDOM)(html).window.document;
+
+export const FORBID_KINDS = ['forbid', 'forbid-composite-roles'];
+
+/**
+ * What a rule actually matches.
+ *
+ * `forbid-composite-roles` states the component's own selector and is expanded
+ * over the vocabulary, so the ten roles are named once in semantics.json rather
+ * than once per component - and adding one tightens every such rule instead of
+ * leaving each a role short. Expansion is root-only on purpose: a slide may
+ * legitimately contain a menu, it just may not *be* one.
+ */
+export function expandedSelector(rule, compositeRoles) {
+  if (rule.kind !== 'forbid-composite-roles') return rule.selector;
+  return compositeRoles.map((r) => `${rule.selector}[role="${r}"]`).join(', ');
+}
+
+/** Every rule of every component the sweep has reached. */
+export function enforcedRules(data) {
+  return Object.entries(data.rows)
+    .filter(([, c]) => c.status === 'enforced')
+    .flatMap(([name, c]) => c.rules.map((r) => ({ ...r, component: name })));
+}
+
+// ponytail: a fixed cap on aria-labelledby ids. A real label names a handful;
+// raise it if a page ever needs more.
+const MAX_LABEL_REFS = 32;
+
+/**
+ * The name an element is given outright, by `aria-label` or `aria-labelledby`.
+ * Empty when it has neither.
+ *
+ * The two callers below diverge on what happens next, which is why this stops
+ * here: buttons can fall back to their own text, while landmarks and selects
+ * need a name apart from the links or options they contain.
+ */
+export function authoredName(el, document) {
+  const label = el.getAttribute('aria-label');
+  if (label && label.trim()) return label.trim();
+  const ref = el.getAttribute('aria-labelledby');
+  if (!ref) return '';
+  // Each id once, and only the first few: repeating one id thousands of times
+  // made a small snippet walk a large subtree thousands of times.
+  return [...new Set(ref.split(/\s+/))]
+    .slice(0, MAX_LABEL_REFS)
+    .map((id) => document.getElementById(id)?.textContent ?? '')
+    .join(' ')
+    .trim();
+}
+
+/**
+ * Enough of the accessible-name computation to answer "is this control
+ * nameless?" - the authored name, then the text that is left once the
+ * aria-hidden subtrees are taken out. Not the full algorithm: no title, no
+ * alt on a descendant image, because a control relying on those is
+ * not what this is looking for.
+ */
+function accessibleName(el, document) {
+  const authored = authoredName(el, document);
+  if (authored) return authored;
+  const labels = [...(el.labels ?? [])].map((label) => accessibleName(label, document)).join(' ').trim();
+  if (labels) return labels;
+  // Landmarks and selects are not named by their descendant links or options.
+  if (el.matches('nav, select')) return '';
+  const clone = el.cloneNode(true);
+  clone.querySelectorAll('[aria-hidden="true"], select').forEach((n) => n.remove());
+  return clone.textContent.trim();
+}
+
+/**
+ * An authored fragment, parsed into a body of its own.
+ *
+ * Never for a whole document: nesting one inside <body> reparses its <head> in
+ * body context, so a rule keyed on anything up there would silently match
+ * nothing. Whole pages go through `checkPage`.
+ */
+export function violations(html, rules, compositeRoles, opts) {
+  return violationsIn(parse(`<!doctype html><body>${html}</body>`), rules, compositeRoles, opts);
+}
+
+const idrefTargets = (rule, el, document) => {
+  const container = rule.container ? el.closest(rule.container) : document;
+  return new Set(container?.querySelectorAll(rule.targetSelector));
+};
+
+const ownedBy = (rule, el) => (candidate) => {
+  if (candidate.closest(rule.ownerSelector) !== el) return false;
+  const excludedAncestor = rule.excludeAncestorSelector && candidate.closest(rule.excludeAncestorSelector);
+  return !excludedAncestor || !el.contains(excludedAncestor);
+};
+
+/** Per rule kind: does this hit break the rule? */
+const BROKEN = {
+  forbid: () => true,
+  'forbid-composite-roles': () => true,
+  'require-attr': (rule, el) => {
+    const v = el.getAttribute(rule.attr);
+    return rule.equals ? v !== rule.equals : v === null || v === '';
+  },
+  'require-idref': (rule, el, document) => {
+    const ids = (el.getAttribute(rule.attr) ?? '').trim().split(/\s+/).filter(Boolean);
+    const targets = idrefTargets(rule, el, document);
+    return !ids.length || !ids.every((id) => targets.has(document.getElementById(id)));
+  },
+  'require-owned-descendant': (rule, el) => ![...el.querySelectorAll(rule.descendantSelector)].some(ownedBy(rule, el)),
+  // The one thing a selector cannot ask. "Has no accessible name" depends
+  // on text *nodes*, and CSS cannot see them: `:has(> .icon:only-child)`
+  // counts elements, so it flags <a><span icon/>Five</a> - a link that is
+  // perfectly well named. This reads the content instead.
+  'require-accessible-name': (rule, el, document) => !accessibleName(el, document),
+};
+
+/** The predicate for one rule: `(element, document) => true` when that hit breaks it. */
+export function ruleBreach(rule) {
+  const broken = BROKEN[rule.kind];
+  if (!broken) throw new Error(`unknown rule kind: ${rule.kind}`);
+  return (el, document) => broken(rule, el, document);
+}
+
+export function violationsIn(document, rules, compositeRoles, { fragmentSafe = false } = {}) {
+  const found = [];
+  for (const rule of rules) {
+    if (fragmentSafe && !rule.fragmentSafe) continue;
+    const breaks = ruleBreach(rule);
+    for (const el of document.querySelectorAll(expandedSelector(rule, compositeRoles))) {
+      if (breaks(el, document)) found.push({ rule, tag: el.outerHTML.slice(0, 90) });
+    }
+  }
+  return found;
+}
+
+/**
+ * The landmarks on one page that share a name.
+ *
+ * No semantics.json rule can state this: a name is only ambiguous relative to
+ * the other landmarks on the same page, and there is no fragment to write it
+ * against. Two <nav>s both called "Main" is a landmark menu with two identical
+ * rows, which is the problem labelling them was meant to solve. Shipped once.
+ */
+function duplicateLandmarkNames(document) {
+  const seen = new Set();
+  const dupes = [];
+  for (const nav of document.querySelectorAll('nav')) {
+    const name = authoredName(nav, document);
+    if (!name) continue;
+    if (seen.has(name)) dupes.push(name);
+    seen.add(name);
+  }
+  return dupes;
+}
+
+/**
+ * One built page, checked as the document it is: every enforced rule, plus the
+ * landmark names, which are only ambiguous relative to each other.
+ *
+ * Parsed once, and as a document rather than a fragment - `<!doctype html>` and
+ * `<head>` survive, so a rule may be written against either.
+ */
+export function checkPage(html, rules, compositeRoles) {
+  const document = parse(html);
+  return {
+    violations: violationsIn(document, rules, compositeRoles),
+    duplicateNames: duplicateLandmarkNames(document)
+  };
+}