@adia-ai/mcp 0.8.37 → 0.8.39

package/factory/vendor/adia-contract-check.mjs

@@ -0,0 +1,432 @@
+#!/usr/bin/env node
+// adia-contract-check — the class-5 contract checker (REQ-03, factory-dx-ws5-
+// consumer-verify SPEC): authored markup attributes vs the shipped component
+// contracts. This is the class with no gate anywhere (gh#1024, gh#982, gh#924;
+// D8's class-5 anchor) — a `color=` on <icon-ui> (gh#982's most frequent dead
+// attribute) silently no-ops today; this script turns it red.
+//
+// Contract source: the SHIPPED JSON derivatives, never the yaml SoT (which
+// does not ship) — node_modules/@adia-ai/web-components/custom-elements.json
+// (attribute-name existence) and node_modules/@adia-ai/web-components/
+// components/<slug>/<slug>.a2ui.json (enum-value membership, best-effort per
+// tag — see resolveA2uiDoc()).
+//
+// v1 scope (stated honestly, per the SPEC's Non-goals): attribute names +
+// enum values on `*-ui` tags; class/id/slot/style/role/data-*/aria-*/
+// framework-global attributes allowlisted; one content-model rule — raw <thead>/
+// <tbody> children of <table-ui> (3 of 3 occurrences broken, gh#924). Slot
+// and composition semantics are v2.
+//
+// The shipped contract mixes kebab-case and camelCase attribute names across
+// components (an existing inconsistency in the generated manifest — e.g.
+// pane-ui ships `maxWidth` while tour-ui ships `auto-start`) — this script
+// normalizes both the authored name and every contract name to lowercase-
+// no-hyphens before comparing, so that drift never produces a false flag.
+// The a2ui.json `$ref`s a `common_types.json` that does NOT ship in the
+// package — this checker never attempts full $ref resolution; only inline
+// enums are read.
+//
+// KNOWN LIMITATION (gh#1154): the shipped custom-elements.json manifest
+// itself is missing a small number of real `reflect: true` properties for at
+// least 14 tags (e.g. icon-ui's `tone`) — a generator defect, not a bug in
+// this checker, which faithfully asserts against whatever the contract says
+// per REQ-03. Until gh#1154 lands, this checker can false-flag those
+// specific attributes; consumers should check the tag's yaml SoT (or gh#1154)
+// before assuming a flagged attribute is truly dead.
+//
+// Usage:
+//   node adia-contract-check.mjs <dir-or-file>...
+//   node adia-contract-check.mjs selftest    # embedded fixtures, no node_modules needed
+//
+// Exit: 0 = clean, 1 = violation(s) found, 2 = setup error (contract missing).
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+
+const __filename = fileURLToPath(import.meta.url);
+
+const MARKUP_EXT = new Set(['.html', '.htm', '.vue', '.svelte', '.astro']);
+const SKIP_DIRS = new Set(['node_modules', 'dist', 'build', '.git', '.next', 'coverage']);
+
+// `role` is a host-language global (like `aria-*`) — text.yaml itself documents
+// role="heading" + aria-level as the sanctioned semantic-heading path (gh#1256);
+// globals are never component contract members and never CLASS-5-UNKNOWN.
+const ALLOWLIST_EXACT = new Set(['class', 'classname', 'id', 'slot', 'style', 'key', 'ref', 'part', 'role']);
+const ALLOWLIST_PREFIX = ['data-', 'aria-'];
+
+function normalize(name) {
+  return name.toLowerCase().replace(/-/g, '');
+}
+
+function isAllowlisted(attrName) {
+  const lower = attrName.toLowerCase();
+  if (ALLOWLIST_EXACT.has(lower)) return true;
+  return ALLOWLIST_PREFIX.some((p) => lower.startsWith(p));
+}
+
+// ---- contract index (pure — no I/O; testable with inline fixtures) --------
+
+export function buildAttrIndex(customElementsJson) {
+  const index = new Map(); // tag -> Map(normalized -> originalName)
+  for (const mod of customElementsJson.modules || []) {
+    for (const decl of mod.declarations || []) {
+      if (!decl.tagName) continue;
+      const m = index.get(decl.tagName) || new Map();
+      for (const attr of decl.attributes || []) {
+        m.set(normalize(attr.name), attr.name);
+      }
+      index.set(decl.tagName, m);
+    }
+  }
+  return index;
+}
+
+export function buildEnumIndex(a2uiDoc) {
+  const m = new Map(); // normalized attr -> enum string[]
+  const props = (a2uiDoc && a2uiDoc.properties) || {};
+  for (const [key, val] of Object.entries(props)) {
+    if (val && Array.isArray(val.enum)) {
+      m.set(normalize(key), val.enum);
+    }
+  }
+  return m;
+}
+
+function editDistance(a, b) {
+  const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+  for (let j = 0; j <= b.length; j++) dp[0][j] = j;
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      dp[i][j] = a[i - 1] === b[j - 1]
+        ? dp[i - 1][j - 1]
+        : 1 + Math.min(dp[i - 1][j - 1], dp[i - 1][j], dp[i][j - 1]);
+    }
+  }
+  return dp[a.length][b.length];
+}
+
+function nearestAttr(attrName, attrMap) {
+  let best = null;
+  let bestDist = Infinity;
+  for (const original of attrMap.values()) {
+    const d = editDistance(attrName.toLowerCase(), original.toLowerCase());
+    if (d < bestDist) {
+      bestDist = d;
+      best = original;
+    }
+  }
+  return best;
+}
+
+// ---- markup scanning --------------------------------------------------------
+
+const TAG_RE = /<([a-z][a-z0-9]*(?:-[a-z0-9]+)*-ui)\b([^>]*)>/g;
+const ATTR_RE = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*(?:=\s*("[^"]*"|'[^']*'|\{[^}]*\}|[^\s>]+))?/g;
+const TABLE_CONTENT_MODEL_RE = /<table-ui\b[^>]*>(?:(?!<\/table-ui>)[\s\S])*?<t(?:head|body)\b/g;
+
+function lineOf(text, index) {
+  return text.slice(0, index).split('\n').length;
+}
+
+export function checkMarkup(text, filePath, attrIndex) {
+  const findings = [];
+
+  for (const m of text.matchAll(TAG_RE)) {
+    const tag = m[1];
+    const attrString = m[2];
+    const attrMap = attrIndex.get(tag);
+    if (!attrMap) continue; // unknown tag (third-party or typo'd) — not this checker's v1 concern
+
+    ATTR_RE.lastIndex = 0;
+    let am;
+    while ((am = ATTR_RE.exec(attrString))) {
+      const attrName = am[1];
+      if (attrName === tag) continue;
+      if (isAllowlisted(attrName)) continue;
+      const norm = normalize(attrName);
+      if (!attrMap.attrs.has(norm)) {
+        const suggestion = nearestAttr(attrName, attrMap.attrs);
+        findings.push({
+          type: 'CLASS-5-UNKNOWN-ATTR',
+          line: lineOf(text, m.index),
+          tag,
+          attr: attrName,
+          message: `${tag} has no attribute "${attrName}" — it renders as a silent no-op.`,
+          suggestion: suggestion ? `Did you mean: ${suggestion}="..."?` : null,
+        });
+        continue;
+      }
+      const rawValue = am[2];
+      if (!rawValue) continue;
+      const quoted = /^"([^"]*)"$|^'([^']*)'$/.exec(rawValue);
+      if (!quoted) continue; // {expr} / bare token — not a static literal we can enum-check
+      const value = quoted[1] !== undefined ? quoted[1] : quoted[2];
+      const allowed = attrMap.enums.get(norm);
+      if (allowed && !allowed.includes(value)) {
+        findings.push({
+          type: 'CLASS-5-ENUM-VIOLATION',
+          line: lineOf(text, m.index),
+          tag,
+          attr: attrName,
+          message: `${tag}[${attrName}="${value}"] is not a recognized value.`,
+          suggestion: `Allowed: ${allowed.join(', ')}`,
+        });
+      }
+    }
+  }
+
+  for (const m of text.matchAll(TABLE_CONTENT_MODEL_RE)) {
+    findings.push({
+      type: 'CLASS-5-CONTENT-MODEL',
+      line: lineOf(text, m.index),
+      tag: 'table-ui',
+      attr: null,
+      message: 'raw <thead>/<tbody> markup as a <table-ui> child is not a supported content model.',
+      suggestion: 'use the `.columns`/`.data` properties (or <col-def> children) instead of raw table markup.',
+    });
+  }
+
+  findings.sort((a, b) => a.line - b.line);
+  return findings;
+}
+
+function render(filePath, findings) {
+  const lines = [];
+  for (const f of findings) {
+    lines.push(`${filePath}:${f.line}  ${f.type}`);
+    lines.push(`  ${f.message}`);
+    if (f.suggestion) lines.push(`  ${f.suggestion}`);
+  }
+  return lines.join('\n');
+}
+
+// ---- consumer-side contract loading (I/O — not exercised by selftest) ------
+
+function findPackageRoot(startDir) {
+  let dir = path.resolve(startDir);
+  while (true) {
+    const candidate = path.join(dir, 'node_modules', '@adia-ai', 'web-components');
+    if (fs.existsSync(path.join(candidate, 'custom-elements.json'))) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+function slugFromTag(tag) {
+  return tag.endsWith('-ui') ? tag.slice(0, -3) : null;
+}
+
+function loadContract(cwd) {
+  const pkgRoot = findPackageRoot(cwd);
+  if (!pkgRoot) return null;
+  const customElementsJson = JSON.parse(fs.readFileSync(path.join(pkgRoot, 'custom-elements.json'), 'utf8'));
+  const attrsByTag = buildAttrIndex(customElementsJson);
+  const index = new Map(); // tag -> { attrs, enums }
+  for (const [tag, attrs] of attrsByTag) {
+    let enums = new Map();
+    const slug = slugFromTag(tag);
+    if (slug) {
+      const a2uiPath = path.join(pkgRoot, 'components', slug, `${slug}.a2ui.json`);
+      if (fs.existsSync(a2uiPath)) {
+        try {
+          enums = buildEnumIndex(JSON.parse(fs.readFileSync(a2uiPath, 'utf8')));
+        } catch {
+          // malformed a2ui.json for this tag — existence check still runs, enum check just skips
+        }
+      }
+    }
+    index.set(tag, { attrs, enums });
+  }
+  return index;
+}
+
+function collectFiles(target) {
+  const stat = fs.statSync(target);
+  if (stat.isFile()) return [target];
+  const out = [];
+  for (const entry of fs.readdirSync(target, { withFileTypes: true })) {
+    if (entry.name.startsWith('.')) continue;
+    const full = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      out.push(...collectFiles(full));
+    } else if (MARKUP_EXT.has(path.extname(entry.name))) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+// ---- selftest — embedded fixtures, no real node_modules required -----------
+
+function selftest() {
+  const fails = [];
+
+  const customElementsJson = {
+    modules: [
+      {
+        path: 'components/icon/icon.js',
+        declarations: [{
+          tagName: 'icon-ui',
+          attributes: [
+            { name: 'name' }, { name: 'label' }, { name: 'size' }, { name: 'weight' }, { name: 'tone' },
+          ],
+        }],
+      },
+      {
+        path: 'components/table/table.js',
+        declarations: [{ tagName: 'table-ui', attributes: [{ name: 'sortable' }, { name: 'density' }] }],
+      },
+      {
+        path: 'components/pane/pane.js',
+        declarations: [{ tagName: 'pane-ui', attributes: [{ name: 'maxWidth' }, { name: 'side' }] }],
+      },
+      {
+        path: 'components/text/text.js',
+        declarations: [{ tagName: 'text-ui', attributes: [{ name: 'variant' }, { name: 'tone' }] }],
+      },
+    ],
+  };
+  const iconA2ui = {
+    properties: {
+      tone: { type: 'string', enum: ['accent', 'info', 'success', 'warning', 'danger', 'muted', 'neutral'] },
+      weight: { type: 'string', enum: ['thin', 'light', 'regular', 'bold', 'fill', 'duotone'] },
+    },
+  };
+
+  const attrsByTag = buildAttrIndex(customElementsJson);
+  const index = new Map();
+  index.set('icon-ui', { attrs: attrsByTag.get('icon-ui'), enums: buildEnumIndex(iconA2ui) });
+  index.set('table-ui', { attrs: attrsByTag.get('table-ui'), enums: new Map() });
+  index.set('pane-ui', { attrs: attrsByTag.get('pane-ui'), enums: new Map() });
+  index.set('text-ui', { attrs: attrsByTag.get('text-ui'), enums: new Map() });
+
+  // 1. gh#982's named example: icon-ui color= is a dead attribute.
+  const deadAttr = checkMarkup('<icon-ui color="primary"></icon-ui>', 'f.html', index);
+  if (deadAttr.length !== 1 || deadAttr[0].type !== 'CLASS-5-UNKNOWN-ATTR') fails.push('icon-ui color= not flagged');
+
+  // 2. A clean, real icon-ui markup must stay clean.
+  const clean = checkMarkup('<icon-ui name="house" tone="success" weight="fill" class="x" data-id="1" aria-label="y"></icon-ui>', 'f.html', index);
+  if (clean.length !== 0) fails.push(`clean markup flagged: ${JSON.stringify(clean)}`);
+
+  // 3. Enum violation on a real attribute.
+  const enumBad = checkMarkup('<icon-ui name="house" tone="purple"></icon-ui>', 'f.html', index);
+  if (enumBad.length !== 1 || enumBad[0].type !== 'CLASS-5-ENUM-VIOLATION') fails.push('bad enum value not flagged');
+
+  // 4. camelCase (pane-ui maxWidth) authored as kebab-case must still resolve — the
+  //    normalization this checker exists to provide (no false flag on manifest drift).
+  const camelOk = checkMarkup('<pane-ui max-width="300"></pane-ui>', 'f.html', index);
+  if (camelOk.length !== 0) fails.push(`kebab-authored maxWidth should normalize-match, got: ${JSON.stringify(camelOk)}`);
+
+  // 5. gh#924: raw thead/tbody inside table-ui is a content-model violation.
+  const tableBad = checkMarkup('<table-ui><thead><tr><th>x</th></tr></thead></table-ui>', 'f.html', index);
+  if (!tableBad.some((f) => f.type === 'CLASS-5-CONTENT-MODEL')) fails.push('raw thead/tbody in table-ui not flagged');
+
+  // 6. table-ui using the real API stays clean.
+  const tableOk = checkMarkup('<table-ui sortable density="compact"></table-ui>', 'f.html', index);
+  if (tableOk.length !== 0) fails.push(`table-ui with real props flagged: ${JSON.stringify(tableOk)}`);
+
+  // 7. An unrecognized *-ui tag (not in the contract) is silently skipped, not flagged —
+  //    v1 doesn't judge tags outside the shipped catalog.
+  const unknownTag = checkMarkup('<some-third-party-ui bogus="x"></some-third-party-ui>', 'f.html', index);
+  if (unknownTag.length !== 0) fails.push('unknown tag should be skipped, not flagged');
+
+  // 8. Removing the seeded violation restores green (AC-3's both-directions check).
+  const fixed = checkMarkup('<icon-ui name="house"></icon-ui>', 'f.html', index);
+  if (fixed.length !== 0) fails.push('fixed markup still flagged');
+
+  // 9. gh#1256 regression: `role` (+ aria-*) are host-language globals — text.yaml's
+  //    own sanctioned semantic-heading pattern must exit clean, never CLASS-5-UNKNOWN.
+  const roleGlobal = checkMarkup('<text-ui variant="title" role="heading" aria-level="1">Dashboard</text-ui>', 'f.html', index);
+  if (roleGlobal.length !== 0) fails.push(`role="heading" aria-level flagged (gh#1256): ${JSON.stringify(roleGlobal)}`);
+
+  // 10. Setup-error path (AC-4's 0/1/2 matrix): no @adia-ai/web-components in
+  // node_modules anywhere up the tree must resolve to null (drives exit 2 in
+  // main()), never a thrown exception or a silent empty-clean pass.
+  const emptyDir = fs.mkdtempSync(path.join(os.tmpdir(), 'adia-contract-check-empty-'));
+  try {
+    if (loadContract(emptyDir) !== null) fails.push('loadContract should return null when the contract is missing');
+  } finally {
+    fs.rmSync(emptyDir, { recursive: true, force: true });
+  }
+
+  // 11. AC-4 — -h/--help exits 0 and prints usage, never a data payload.
+  // Spawned for real (main() calls process.exit() directly).
+  for (const flag of ['-h', '--help']) {
+    let out, code;
+    try {
+      out = execFileSync(process.execPath, [__filename, flag], { encoding: 'utf8' });
+      code = 0;
+    } catch (e) {
+      out = e.stdout || '';
+      code = e.status;
+    }
+    if (code !== 0) fails.push(`${flag} did not exit 0 (got ${code})`);
+    if (!out.startsWith('usage:')) fails.push(`${flag} did not print usage (got ${JSON.stringify(out)})`);
+  }
+
+  if (fails.length) {
+    console.error('selftest FAIL: ' + fails.join(' | '));
+    return 1;
+  }
+  console.log('selftest OK — 11 fixtures (unknown attr, clean, enum, camelCase-normalize, table content-model, unknown tag, seed+un-seed, role/aria globals, setup-error, -h/--help)');
+  return 0;
+}
+
+function main(argv) {
+  if (argv[0] === 'selftest') {
+    process.exit(selftest());
+  }
+  if (argv.includes('-h') || argv.includes('--help')) {
+    console.log('usage: adia-contract-check.mjs <dir-or-file>...');
+    process.exit(0);
+  }
+  const targets = argv.filter((a) => !a.startsWith('-'));
+  if (targets.length === 0) {
+    console.error('usage: adia-contract-check.mjs <dir-or-file>...');
+    process.exit(2);
+  }
+  const index = loadContract(process.cwd());
+  if (!index) {
+    console.error('adia-contract-check: @adia-ai/web-components not found in node_modules — npm install');
+    process.exit(2);
+  }
+  let total = 0;
+  for (const target of targets) {
+    let files;
+    try {
+      files = collectFiles(target);
+    } catch (e) {
+      console.error(`adia-contract-check: cannot read ${target}: ${(e && e.message) || e}`);
+      process.exit(2);
+    }
+    for (const file of files) {
+      const text = fs.readFileSync(file, 'utf8');
+      const findings = checkMarkup(text, file, index);
+      if (findings.length) {
+        total += findings.length;
+        console.log(render(file, findings));
+      }
+    }
+  }
+  process.exit(total ? 1 : 0);
+}
+
+// Only runs when invoked directly — never on import (this module is also loaded
+// as a library for its pure functions, e.g. by tests). realpathSync guards
+// against a symlinked invocation the way gate-roster.mjs's identical check does.
+const isMain = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    return realpathSync(fileURLToPath(import.meta.url)) === realpathSync(process.argv[1]);
+  } catch {
+    return false;
+  }
+})();
+if (isMain) main(process.argv.slice(2));