@expressivecss/mcp-server 0.2.1 → 0.2.2

package/contract.json

@@ -1,13 +1,14 @@
 {
   "schemaVersion": 1,
   "generatedBy": "scripts/gen-expressivecss-skill.mjs",
-  "frameworkVersion": "0.11.0",
+  "frameworkVersion": "0.12.0",
   "skillVersion": "0.7.0",
-  "matchingTag": "v0.11.0",
+  "matchingTag": "v0.12.0",
   "releaseTags": [
     "v0.10.0",
     "v0.10.1",
     "v0.11.0",
+    "v0.12.0",
     "v0.5.0",
     "v0.6.0",
     "v0.7.0",
@@ -24,5 +25,5 @@
     "package.json",
     "CHANGELOG.md"
   ],
-  "sourceHash": "425faa2b1b68a0dd95d0718e81b94405ff8ab3b34a2c95e5cfc1b71ef2894a65"
+  "sourceHash": "270b7d8fd0ec2f1174cba3f2793c061d3b4f494903520e2eaaa7fa640a680859"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expressivecss/mcp-server",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "ExpressiveCSS MCP server with Design→QA workflow tools.",
   "homepage": "https://www.expressivecss.com",
   "repository": {

package/semantics-data.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "generatedBy": "mcp/expressivecss/scripts/sync-guides.mjs",
-  "frameworkVersion": "0.11.0",
+  "frameworkVersion": "0.12.0",
   "semantics": {
     "about": "Normative HTML semantics for ExpressiveCSS. This data file is the single source of truth: SEMANTICS.md is generated from it by scripts/gen-semantics.mjs, and tests/semantics.test.js enforces it. One row per roster entry, each stating its kind - component, foundation or behavior, as CONTEXT.md defines them. CONTEXT.md defines the rest of the vocabulary.",
     "scope": "Element choice, landmark structure, and the ARIA that element choice implies. Keyboard interaction, focus management and colour contrast are deliberately out of scope.",

package/server.js

@@ -24,6 +24,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;
+// 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;
 const STATIC_INSPECTION_TIMEOUT_MS = 5_000;
 const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
 const MAX_PROJECT_ROOT_CHARS = 4_096;
@@ -96,19 +99,19 @@ const LegacyPatternList = [
   {
     id: 'legacy-nav-wrapper',
     severity: 'high',
-    description: '`.nav-wrapper` is legacy Materialize structure; use ExpressiveCSS nav components directly.',
+    description: '`.nav-wrapper` is retired markup structure; use ExpressiveCSS nav components directly.',
     pattern: /\bnav-wrapper\b/g,
   },
   {
     id: 'legacy-brand-logo',
     severity: 'medium',
-    description: '`.brand-logo` is Materialize-era naming; prefer native layout semantics in ExpressiveCSS pages.',
+    description: '`.brand-logo` is retired naming; prefer native layout semantics in ExpressiveCSS pages.',
     pattern: /\bbrand-logo\b/g,
   },
   {
     id: 'legacy-lever',
     severity: 'medium',
-    description: '`.lever` is a Materialize switch token, replace with Expressive switches per component guide.',
+    description: '`.lever` is a retired switch token, replace with Expressive switches per component guide.',
     pattern: /\blever\b/g,
   },
   {
@@ -879,7 +882,15 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
   const { semantics, frameworkVersion } = loadSemanticsContract();
   if (maxIssues <= 0) return markInspectionTruncated([], 'issue limit reached');
   if (markupStructureExceedsLimit(snippet)) return markInspectionTruncated([], 'markup structure limit reached');
-  const { document } = new JSDOM(`<!doctype html><body>${snippet}</body>`).window;
+  const prefix = '<!doctype html><body>';
+  const includeNodeLocations = snippet.length * (snippet.split('<').length - 1) <= MAX_LOCATED_MARKUP_WORK;
+  const dom = new JSDOM(`${prefix}${snippet}</body>`, { includeNodeLocations });
+  const { document } = dom.window;
+  // Elements the parser creates without a start tag have no source offset, so they report the start.
+  const locate = (element) => {
+    const offset = includeNodeLocations ? dom.nodeLocation(element)?.startOffset ?? -1 : -1;
+    return offset >= prefix.length ? lineForMatch(snippet, offset - prefix.length) : { line: 1, column: 1 };
+  };
   const issues = [];
 
   for (const rule of enforcedSemanticRules(semantics)) {
@@ -890,7 +901,7 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
       for (const element of hits) {
         const stop = inspectionStopReason(issues, maxIssues, deadline);
         if (stop) return markInspectionTruncated(issues, stop);
-        issues.push(semanticIssue(rule, element, frameworkVersion));
+        issues.push(semanticIssue(rule, element, frameworkVersion, locate(element)));
       }
     } else if (rule.kind === 'require-attr') {
       for (const element of hits) {
@@ -899,7 +910,7 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
         const value = element.getAttribute(rule.attr);
         const valid = rule.equals ? value === rule.equals : value !== null && value !== '';
         if (!valid) {
-          issues.push(semanticIssue(rule, element, frameworkVersion));
+          issues.push(semanticIssue(rule, element, frameworkVersion, locate(element)));
         }
       }
     } else if (rule.kind === 'require-accessible-name') {
@@ -907,7 +918,7 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
         const stop = inspectionStopReason(issues, maxIssues, deadline);
         if (stop) return markInspectionTruncated(issues, stop);
         if (!accessibleName(element, document)) {
-          issues.push(semanticIssue(rule, element, frameworkVersion));
+          issues.push(semanticIssue(rule, element, frameworkVersion, locate(element)));
         }
       }
     }
@@ -928,7 +939,7 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
         component: 'landmarks',
         frameworkVersion,
         rule: `Navigation landmarks on one page need distinct names; "${name}" is repeated.`,
-        location: { line: 1, column: 1 },
+        location: locate(nav),
         snippet: nav.outerHTML.slice(0, 140),
       });
     }
@@ -938,14 +949,14 @@ function inspectSemanticRules(snippet, maxIssues = MAX_STATIC_ISSUES, deadline =
   return issues;
 }
 
-function semanticIssue(rule, element, frameworkVersion) {
+function semanticIssue(rule, element, frameworkVersion, location) {
   return {
     id: rule.id,
     severity: 'high',
     component: rule.component,
     frameworkVersion,
     rule: rule.message,
-    location: { line: 1, column: 1 },
+    location,
     snippet: element.outerHTML.slice(0, 140),
   };
 }
@@ -1920,7 +1931,7 @@ async function rulesEnforcerHandler(args) {
       ],
       guidance: {
         alwaysPrefer: 'Read component guides before adding structure.',
-        compatibility: 'Avoid Materialize-era selectors and prefer source-of-truth component contracts.',
+        compatibility: 'Avoid retired selectors and prefer source-of-truth component contracts.',
       },
     },
     workflowId,

package/smoke.mjs

@@ -248,6 +248,18 @@ const transport = new StdioClientTransport({
   assert.equal(failing.status, 1, failing.stderr);
   assert.match(failing.stdout, /navigation-bar-marks-current/u);
   assert.match(failing.stdout, /retired-markup\.html:1:\d+ legacy-input-field/u);
+  // Semantics findings report the element's line and column, also in JSX after lint rewrites className.
+  const locatedMarkup = path.join(outsideDir, 'located.jsx');
+  await writeFile(locatedMarkup, 'export const Nav = () => (\n  <>\n    <nav className="navigation-bar"><a href="/">Home</a></nav>\n    <nav aria-label="Main"><a href="/">Home</a></nav>\n    <nav aria-label="Main"><a href="/a">A</a></nav>\n  </>\n);\n');
+  const located = lint([locatedMarkup]);
+  assert.match(located.stdout, /located\.jsx:3:5 nav-needs-label/u);
+  assert.match(located.stdout, /located\.jsx:5:5 duplicate-navigation-landmark-name/u);
+  // Large files within the structure limit still finish inside the inspection budget.
+  const longMarkup = path.join(outsideDir, 'long.html');
+  await writeFile(longMarkup, `<nav><a href="/">Home</a></nav>${'<br>'.repeat(3_990)}${'x\n'.repeat(235_000)}`);
+  const long = lint([longMarkup]);
+  assert.match(long.stdout, /long\.html:1:1 nav-needs-label/u);
+  assert.doesNotMatch(long.stdout, /inspection-truncated/u);
   assert.equal(lint([outsideFile]).status, 0);
   // Files the bounded reader refuses, and inspections that stop early, fail instead of passing silently.
   const linkedMarkup = path.join(outsideDir, 'linked.html');