@adia-ai/a2ui-validator 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -7,6 +7,23 @@ Follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 
 _No pending changes._
 
+## [0.4.1] - 2026-05-10
+
+### Added
+
+- **Semantic-validator Phase 3 foundation** (per [docs/specs/semantic-validator.md](../../../docs/specs/semantic-validator.md) § Phase 3 — rule-based fast-path):
+  - `semantic/intent-specs.js` — registry of 10 `IntentSpec` entries covering dominant intent classes: `auth.signup`, `auth.signin`, `auth.password-reset`, `dashboard.analytics`, `data-table.list`, `form.settings`, `form.contact`, `chat.conversation`, `commerce.cart`, `errors.not-found`.
+  - `semantic/classify-intent.js` — `classifyIntent()` regex classifier + `scoreAgainstSpec()` deterministic A2UI-tree scorer. Returns rule verdict with certainty 0..1 (≥ 0.9 = LLM-skip eligible per spec § 3c hybrid).
+  - 18 unit tests covering registry hygiene, regex match against 6 dominant intents, clean-pass / clean-fail / partial-verdict scoring, nested A2UI tree traversal.
+
+### Changed
+
+- Spec status updated in `docs/specs/semantic-validator.md` to reflect Phase 3 foundation shipped (NOT yet wired into `validateSemantics()` — integration deferred until shadow-compare runs prove ≥ 95% agreement with LLM judge).
+
+### Notes
+
+- The classifier is NOT yet called from `validateSemantics()`. Phase 3 integration requires (a) the shadow-compare runs from the spec's exit criteria, and (b) a `judge.js` extension to accept rule-verdict hints when falling through to LLM. Both planned for a follow-up cut.
+
 ## [0.4.0] - 2026-05-10
 
 ### Ride-along (no source changes)

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adia-ai/a2ui-validator",
-  "version": "0.4.0",
-  "description": "AdiaUI A2UI validator \u2014 JSON Schema structural validation plus catalog-aware semantic validation (component exists, props match YAML). Split out from the compose engine so non-compose tooling (tests, MCP validator tools, CI gates) can depend on validation without pulling the whole generator graph.",
+  "version": "0.4.1",
+  "description": "AdiaUI A2UI validator — JSON Schema structural validation plus catalog-aware semantic validation (component exists, props match YAML). Split out from the compose engine so non-compose tooling (tests, MCP validator tools, CI gates) can depend on validation without pulling the whole generator graph.",
   "type": "module",
   "main": "./index.js",
   "exports": {

package/semantic/classify-intent.js

@@ -0,0 +1,128 @@
+/**
+ * Intent classifier — Phase 3 kickoff (semantic-validator)
+ *
+ * Spec: docs/specs/semantic-validator.md § Phase 3
+ *
+ * Two-stage classification:
+ *
+ *   1. Find the best-matching IntentSpec from the registry via regex
+ *   2. Score the emitted A2UI tree against the spec deterministically
+ *
+ * High-confidence matches (intent.confidence ≥ 0.9 AND verdict.certainty ≥ 0.9)
+ * can short-circuit the LLM judge per § 3c (hybrid).
+ *
+ * Status: kickoff — not yet wired into validateSemantics(). Use for
+ * shadow-compare runs (the test harness in classify-intent.test.js).
+ */
+
+import { findIntentSpec } from './intent-specs.js';
+
+/**
+ * Classify an intent prompt against the IntentSpec registry.
+ *
+ * @param {string} intent — natural-language prompt
+ * @returns {{ spec: IntentSpec | null, confidence: number }}
+ */
+export function classifyIntent(intent) {
+  return findIntentSpec(intent);
+}
+
+/**
+ * Score an A2UI tree against an IntentSpec deterministically.
+ *
+ * Returns a SemanticVerdict-shaped object with rule-based certainty.
+ * The caller decides whether to skip the LLM judge based on `certainty`.
+ *
+ * @param {object} a2ui — emitted A2UI tree (root object with `nodes` or
+ *                        equivalent traversable shape)
+ * @param {IntentSpec} spec — the classified IntentSpec
+ * @returns {RuleVerdict}
+ */
+export function scoreAgainstSpec(a2ui, spec) {
+  const { distinct, instances } = collectComponentTypes(a2ui);
+
+  const requiredMissing = spec.required.filter((t) => !distinct.includes(t));
+  const forbiddenPresent = spec.forbidden.filter((t) => distinct.includes(t));
+  const componentCount = instances;  // total instance count (matches existing validator semantics)
+
+  // Clean pass: all required present, no forbidden, meets minComponents
+  const cleanPass =
+    requiredMissing.length === 0 &&
+    forbiddenPresent.length === 0 &&
+    componentCount >= spec.minComponents;
+
+  // Clean fail: 2+ required missing (per spec § 3c "cleanly fails")
+  const cleanFail = requiredMissing.length >= 2;
+
+  // Certainty: 1.0 on clean pass/fail; 0.5 on partial (ambiguous)
+  let certainty = 0.5;
+  let verdict = 'partial';
+  if (cleanPass) {
+    certainty = 1.0;
+    verdict = 'pass';
+  } else if (cleanFail) {
+    certainty = 1.0;
+    verdict = 'fail';
+  }
+
+  // Build a structured findings payload — useful as hints to the LLM
+  // judge on fall-through
+  return {
+    verdict,
+    certainty,
+    score: cleanPass ? 100 : cleanFail ? 0 : 50,
+    spec: spec.id,
+    findings: {
+      required_missing: requiredMissing,
+      forbidden_present: forbiddenPresent,
+      component_count: componentCount,
+      min_components: spec.minComponents,
+    },
+  };
+}
+
+/**
+ * Walk an A2UI tree and collect (a) the set of distinct component types
+ * and (b) the total instance count. The A2UI tree shape varies — sometimes
+ * flat arrays, sometimes nested under `nodes` / `children` / `body`. This
+ * walker handles both.
+ *
+ * @param {*} node — root or nested A2UI shape
+ * @returns {{ distinct: string[], instances: number }}
+ */
+function collectComponentTypes(node) {
+  const distinct = new Set();
+  const counter = { n: 0 };
+  walk(node, distinct, counter);
+  return { distinct: Array.from(distinct), instances: counter.n };
+}
+
+function walk(node, distinct, counter) {
+  if (!node) return;
+  if (Array.isArray(node)) {
+    for (const item of node) walk(item, distinct, counter);
+    return;
+  }
+  if (typeof node !== 'object') return;
+  // Count instances + collect distinct
+  if (typeof node.component === 'string') {
+    distinct.add(node.component);
+    counter.n += 1;
+  } else if (typeof node.type === 'string') {
+    distinct.add(node.type);
+    counter.n += 1;
+  }
+  // Recurse children
+  if (node.children) walk(node.children, distinct, counter);
+  if (node.nodes) walk(node.nodes, distinct, counter);
+  if (node.body) walk(node.body, distinct, counter);
+}
+
+/**
+ * @typedef {object} RuleVerdict
+ * @property {'pass' | 'fail' | 'partial'} verdict
+ * @property {number} certainty — 0..1; ≥ 0.9 allows LLM-skip per § 3c
+ * @property {number} score — 0..100; aligned with LLM judge scale
+ * @property {string} spec — IntentSpec.id that produced this verdict
+ * @property {object} findings — required_missing / forbidden_present / counts
+ */

package/semantic/classify-intent.test.js

@@ -0,0 +1,192 @@
+import { describe, it, expect } from 'vitest';
+import { INTENT_SPECS, findIntentSpec } from './intent-specs.js';
+import { classifyIntent, scoreAgainstSpec } from './classify-intent.js';
+
+describe('intent-specs registry', () => {
+  it('exports at least 10 IntentSpec entries', () => {
+    expect(INTENT_SPECS.length).toBeGreaterThanOrEqual(10);
+  });
+
+  it('has unique IntentSpec.id values', () => {
+    const ids = INTENT_SPECS.map((s) => s.id);
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it('every IntentSpec has the required fields', () => {
+    for (const spec of INTENT_SPECS) {
+      expect(spec.id).toBeTruthy();
+      expect(spec.keywords).toBeInstanceOf(RegExp);
+      expect(Array.isArray(spec.required)).toBe(true);
+      expect(spec.required.length).toBeGreaterThan(0);
+      expect(Array.isArray(spec.forbidden)).toBe(true);
+      expect(typeof spec.minComponents).toBe('number');
+      expect(spec.minComponents).toBeGreaterThan(0);
+      expect(typeof spec.domain).toBe('string');
+      expect(typeof spec.description).toBe('string');
+    }
+  });
+});
+
+describe('findIntentSpec', () => {
+  it('matches "create a signup form" to auth.signup', () => {
+    const { spec, confidence } = findIntentSpec('create a signup form for new users');
+    expect(spec?.id).toBe('auth.signup');
+    expect(confidence).toBe(1.0);
+  });
+
+  it('matches "sign in page" to auth.signin', () => {
+    const { spec, confidence } = findIntentSpec('build a sign in page with email and password');
+    expect(spec?.id).toBe('auth.signin');
+    expect(confidence).toBe(1.0);
+  });
+
+  it('matches "admin dashboard" to dashboard.analytics', () => {
+    const { spec, confidence } = findIntentSpec('an admin dashboard with charts and stats');
+    expect(spec?.id).toBe('dashboard.analytics');
+    expect(confidence).toBe(1.0);
+  });
+
+  it('matches "contact form" to form.contact', () => {
+    const { spec, confidence } = findIntentSpec('a contact us form with name email and message');
+    expect(spec?.id).toBe('form.contact');
+    expect(confidence).toBe(1.0);
+  });
+
+  it('matches "404 page" to errors.not-found', () => {
+    const { spec, confidence } = findIntentSpec('a 404 page not found error');
+    expect(spec?.id).toBe('errors.not-found');
+    expect(confidence).toBe(1.0);
+  });
+
+  it('matches "shopping cart" to commerce.cart', () => {
+    const { spec, confidence } = findIntentSpec('a shopping cart with line items');
+    expect(spec?.id).toBe('commerce.cart');
+    expect(confidence).toBe(1.0);
+  });
+
+  it('returns null + 0 confidence on unknown intent', () => {
+    const { spec, confidence } = findIntentSpec('a kaleidoscope of avian taxonomies');
+    expect(spec).toBeNull();
+    expect(confidence).toBe(0);
+  });
+
+  it('returns null + 0 confidence on empty/invalid input', () => {
+    expect(findIntentSpec('').spec).toBeNull();
+    expect(findIntentSpec(null).spec).toBeNull();
+    expect(findIntentSpec(undefined).spec).toBeNull();
+    expect(findIntentSpec(42).spec).toBeNull();
+  });
+});
+
+describe('classifyIntent (alias)', () => {
+  it('classifies the same as findIntentSpec', () => {
+    const a = classifyIntent('sign up new user');
+    const b = findIntentSpec('sign up new user');
+    expect(a.spec?.id).toBe(b.spec?.id);
+    expect(a.confidence).toBe(b.confidence);
+  });
+});
+
+describe('scoreAgainstSpec', () => {
+  const signupSpec = INTENT_SPECS.find((s) => s.id === 'auth.signup');
+
+  it('returns clean pass for an A2UI tree with all required + no forbidden', () => {
+    const a2ui = {
+      nodes: [
+        { component: 'Card', children: [
+          { component: 'Input' },
+          { component: 'Input' },
+          { component: 'Input' },
+          { component: 'Button' },
+          { component: 'CheckBox' },
+          { component: 'Text' },
+          { component: 'Link' },
+        ]},
+      ],
+    };
+    const verdict = scoreAgainstSpec(a2ui, signupSpec);
+    expect(verdict.verdict).toBe('pass');
+    expect(verdict.certainty).toBe(1.0);
+    expect(verdict.score).toBe(100);
+    expect(verdict.findings.required_missing).toEqual([]);
+    expect(verdict.findings.forbidden_present).toEqual([]);
+  });
+
+  it('returns clean fail when 2+ required missing', () => {
+    const a2ui = {
+      nodes: [{ component: 'Toast' }],  // no Card, Input, Button
+    };
+    const verdict = scoreAgainstSpec(a2ui, signupSpec);
+    expect(verdict.verdict).toBe('fail');
+    expect(verdict.certainty).toBe(1.0);
+    expect(verdict.score).toBe(0);
+    expect(verdict.findings.required_missing.length).toBeGreaterThanOrEqual(2);
+  });
+
+  it('returns partial when 1 required missing (ambiguous — defer to LLM)', () => {
+    const a2ui = {
+      nodes: [
+        { component: 'Card', children: [
+          { component: 'Input' },
+          { component: 'Input' },
+          { component: 'Input' },
+          { component: 'Input' },
+          { component: 'CheckBox' },
+          { component: 'Text' },
+          { component: 'Link' },
+        ]},
+      ],
+    };
+    const verdict = scoreAgainstSpec(a2ui, signupSpec);
+    expect(verdict.verdict).toBe('partial');
+    expect(verdict.certainty).toBeLessThan(0.9);  // signals LLM fallback
+    expect(verdict.findings.required_missing).toEqual(['Button']);
+  });
+
+  it('returns partial when forbidden present (even with all required)', () => {
+    const a2ui = {
+      nodes: [
+        { component: 'Card' },
+        { component: 'Input' },
+        { component: 'Input' },
+        { component: 'Input' },
+        { component: 'Button' },
+        { component: 'Toast' },  // forbidden
+        { component: 'CheckBox' },
+        { component: 'Text' },
+      ],
+    };
+    const verdict = scoreAgainstSpec(a2ui, signupSpec);
+    expect(verdict.verdict).toBe('partial');
+    expect(verdict.findings.forbidden_present).toContain('Toast');
+  });
+
+  it('returns partial when below minComponents (even with all required)', () => {
+    const a2ui = {
+      nodes: [
+        { component: 'Card' },
+        { component: 'Input' },
+        { component: 'Button' },
+      ],
+    };
+    const verdict = scoreAgainstSpec(a2ui, signupSpec);
+    expect(verdict.verdict).toBe('partial');
+    expect(verdict.findings.component_count).toBeLessThan(signupSpec.minComponents);
+  });
+
+  it('walks nested A2UI trees (children + nodes + body)', () => {
+    const a2ui = {
+      body: {
+        children: [
+          { component: 'Card', nodes: [
+            { component: 'Input' },
+            { component: 'Button' },
+          ]},
+        ],
+      },
+    };
+    const verdict = scoreAgainstSpec(a2ui, signupSpec);
+    // Card, Input, Button found — but Input only once + below min
+    expect(verdict.findings.component_count).toBe(3);
+  });
+});

package/semantic/intent-specs.js

@@ -0,0 +1,162 @@
+/**
+ * IntentSpec Registry — Phase 3 kickoff (semantic-validator)
+ *
+ * Spec: docs/specs/semantic-validator.md § 5.1, § Phase 3
+ *
+ * An IntentSpec is a deterministic recipe for one common intent class.
+ * The classify-intent.js classifier matches user prompts against these
+ * specs; high-confidence matches (confidence ≥ 0.9) can bypass the LLM
+ * judge entirely.
+ *
+ * Status: kickoff — 10 IntentSpec entries covering the dominant intent
+ * classes from the existing keyword map in validator.js. NOT YET wired
+ * into validateSemantics() (Phase 3 integration deferred to a follow-up
+ * cut once shadow-compare runs prove ≥95% agreement with the LLM judge).
+ *
+ * Schema (subset of § 5.2 in the spec):
+ *
+ *   IntentSpec {
+ *     id:           string                // e.g. 'auth.signup'
+ *     keywords:     RegExp                // bag-of-words match
+ *     required:     string[]              // component types that MUST appear
+ *     forbidden:    string[]              // component types that MUST NOT appear
+ *     minComponents:number                // structural floor
+ *     domain:       'data-entry' | 'data-display' | 'action' | 'identity' | 'navigation' | 'media' | 'layout' | 'notification' | 'overlay'
+ *     description:  string                // for catalog / docs
+ *   }
+ *
+ * Adding a new spec:
+ *   1. Author the entry below
+ *   2. Add a row to the test file: `classify-intent.test.js`
+ *   3. Run shadow-compare for 1 week (Phase 3 exit criteria § Phase 3)
+ *   4. Promote to fast-path if rule verdict agrees with LLM verdict ≥ 95%
+ */
+
+/** @type {Array<IntentSpec>} */
+export const INTENT_SPECS = [
+  {
+    id: 'auth.signup',
+    keywords: /\b(?:sign[\s-]*up|register|create\s+account|new\s+user)\b/i,
+    required: ['Card', 'Input', 'Button'],
+    forbidden: ['Toast', 'Alert'],  // a signup page should not be primarily a toast/alert
+    minComponents: 7,
+    domain: 'data-entry',
+    description: 'New-user account creation flow — email/password Card with explicit submit Button',
+  },
+  {
+    id: 'auth.signin',
+    keywords: /\b(?:sign[\s-]*in|log[\s-]*in|login)\b/i,
+    required: ['Card', 'Input', 'Button'],
+    forbidden: ['Toast'],
+    minComponents: 6,
+    domain: 'data-entry',
+    description: 'Authentication form — credentials Card with submit Button',
+  },
+  {
+    id: 'auth.password-reset',
+    keywords: /\b(?:reset\s+password|forgot\s+password|recover\s+account)\b/i,
+    required: ['Card', 'Input', 'Button'],
+    forbidden: ['Toast'],
+    minComponents: 5,
+    domain: 'data-entry',
+    description: 'Password reset / forgot-password flow — single-email-input Card',
+  },
+  {
+    id: 'dashboard.analytics',
+    keywords: /\b(?:dashboard|analytics|metrics|admin\s+dashboard)\b/i,
+    required: ['Grid', 'Card'],
+    forbidden: ['Toast', 'Alert'],
+    minComponents: 10,
+    domain: 'data-display',
+    description: 'Metrics dashboard — Grid of Stat/Chart Cards with optional Nav',
+  },
+  {
+    id: 'data-table.list',
+    keywords: /\b(?:table|list|directory|roster|catalog|index)\b/i,
+    required: ['Table'],
+    forbidden: ['Toast'],
+    minComponents: 4,
+    domain: 'data-display',
+    description: 'Tabular data list — sortable/filterable Table',
+  },
+  {
+    id: 'form.settings',
+    keywords: /\b(?:settings|preferences|configuration|account\s+settings|profile\s+settings)\b/i,
+    required: ['Form', 'Input', 'Button'],
+    forbidden: ['Toast'],
+    minComponents: 8,
+    domain: 'data-entry',
+    description: 'Multi-field settings/preferences Form with explicit save Button',
+  },
+  {
+    id: 'form.contact',
+    keywords: /\b(?:contact\s+(?:us|form)|reach\s+out|get\s+in\s+touch|inquiry\s+form)\b/i,
+    required: ['Form', 'Input', 'TextArea', 'Button'],
+    forbidden: ['Toast'],
+    minComponents: 6,
+    domain: 'data-entry',
+    description: 'Contact form — name/email/message TextArea with submit Button',
+  },
+  {
+    id: 'chat.conversation',
+    keywords: /\b(?:chat|conversation|messaging|messenger)\b/i,
+    required: ['Input', 'Button'],
+    forbidden: ['Table', 'Grid'],
+    minComponents: 4,
+    domain: 'data-entry',
+    description: 'Conversational chat surface — Input + send Button stream',
+  },
+  {
+    id: 'commerce.cart',
+    keywords: /\b(?:cart|checkout|basket|shopping\s+cart)\b/i,
+    required: ['Card', 'Button'],
+    forbidden: ['Toast'],
+    minComponents: 6,
+    domain: 'data-display',
+    description: 'Shopping cart — line-item Cards with checkout Button',
+  },
+  {
+    id: 'errors.not-found',
+    keywords: /\b(?:404|not\s+found|page\s+not\s+found|page\s+missing)\b/i,
+    required: ['Card', 'Button'],
+    forbidden: ['Form', 'Table'],
+    minComponents: 3,
+    domain: 'action',
+    description: '404 error page — reassurance Card with back-to-home Button',
+  },
+];
+
+/**
+ * Find the IntentSpec matching the prompt (if any), with a confidence score.
+ *
+ * Confidence semantics:
+ *   - 1.0   = exact keyword regex match
+ *   - 0.0   = no match
+ *
+ * Returns { spec, confidence } or { spec: null, confidence: 0 }.
+ *
+ * @param {string} intent — natural-language intent prompt
+ * @returns {{ spec: IntentSpec | null, confidence: number }}
+ */
+export function findIntentSpec(intent) {
+  if (!intent || typeof intent !== 'string') {
+    return { spec: null, confidence: 0 };
+  }
+  for (const spec of INTENT_SPECS) {
+    if (spec.keywords.test(intent)) {
+      return { spec, confidence: 1.0 };
+    }
+  }
+  return { spec: null, confidence: 0 };
+}
+
+/**
+ * @typedef {object} IntentSpec
+ * @property {string} id — dot-namespaced identifier
+ * @property {RegExp} keywords — pattern that matches user prompts
+ * @property {string[]} required — A2UI component types that MUST appear
+ * @property {string[]} forbidden — component types that MUST NOT appear
+ * @property {number} minComponents — minimum total component count
+ * @property {string} domain — semantic category
+ * @property {string} description — human-readable summary
+ */