@chemx/create-chemx 26.9.17-309 → 26.9.20-228

package/README.md

@@ -31,15 +31,190 @@ starter-kit/
 │   ├── useSelfCleaningTimer.ts # Unmount-safe timer and RAF hook
 │   └── useTwoStageDecision.ts  # Concept to Decision composition
 └── cli/
-    └── index.js                # Interactive capsule generator
+    ├── index.js                # CLI router & capsule generator
+    ├── verify.js               # Zero-token-burn verification engine
+    ├── audit.js                # 7-Pillar static AST audit
+    └── mcp/                    # Model Context Protocol stdio server
 ```
 
+---
+
+## Zero-Token-Burn Verification Pipeline
+
+Running raw, unthrottled `npm test`, `tsc --noEmit`, or build tools dumps thousands of lines of passing checkmarks, compiler noise, and bundle asset tables into an AI agent's context window. This burns tokens prematurely and degrades context quality.
+
+Chemical X wraps tests, typechecks, and builds into silent, failure-focused verification tools available via CLI and native MCP tools:
+
+### Side-by-Side Benchmark Reports
+
+#### 1. Test Suite: `npm test` vs `chemx test`
+
+Ran across the starter-kit test suite (143 test cases across 8 spec suites):
+
+| Metric | Raw `npm test` | Chemical X `chemx test` | Improvement |
+| :--- | :--- | :--- | :--- |
+| **Execution Time** | **~3.1s - 7.5s** | **~3.5s - 3.7s** | Identical underlying test speed |
+| **Output Lines** | **957 lines** | **1 line** | **99.9% line reduction** |
+| **Characters Streamed** | **49,246 characters** | **44 characters** | **99.9% character reduction** |
+| **Agent Token Cost** | **~12,960 tokens** | **~12 tokens** | **12,948 tokens saved (99.9%)** |
+
+```
+# Raw npm test: Floods context with ~13,000 tokens of passing checkmarks
+✔ resolveTargetDir: returns custom directory if provided as first argument (1.64ms)
+✔ search-db: indexes symbols with line ranges and finds definition (56.65ms)
+✔ Verify: parseTestOutput strips passing checkmarks and extracts only failing tests (1.01ms)
+... [940 MORE LINES OF PASSING CHECKMARKS & TIMINGS] ...
+ℹ tests 143 | pass 143 | fail 0 | duration_ms 3002.57ms
+
+# Chemical X: Pinpoint single-line summary
+$ npx chemx test
+  ✔ All tests passed (143 tests in 3500ms)
+```
+
+#### 2. TypeScript Typecheck: `npm run typecheck` vs `chemx typecheck`
+
+| Metric | Raw `npm run typecheck` | Chemical X `chemx typecheck` | Difference |
+| :--- | :--- | :--- | :--- |
+| **Execution Time** | **1.85s** | **2.06s** | **+0.21s** (lightweight wrapper) |
+| **Output Characters** | 54 characters | **40 characters** | **26% reduction** |
+| **Context Token Cost** | ~14 tokens | **~10 tokens** | **~28% reduction** |
+| **Clean Output** | npm script banner noise | Single clean status line | Zero CLI banner noise |
+| **JSON Mode (`--json`)** | Not supported | **~30 tokens** structured JSON | Direct agent ingestion |
+
+```bash
+# Clean, banner-free terminal verification
+$ npx chemx typecheck
+  ✔ TypeScript typecheck clean (1820ms)
+
+# Machine-readable output for AI agents
+$ npx chemx typecheck --json
+{
+  "success": true,
+  "exitCode": 0,
+  "command": "npm run typecheck",
+  "durationMs": 1820,
+  "errorCount": 0,
+  "errors": []
+}
+```
+
+#### 3. Production Build: Raw Build vs `chemx build`
+
+| Metric | Raw Production Build | Chemical X `chemx build` | Chemical X `--silent` |
+| :--- | :--- | :--- | :--- |
+| **Terminal Output** | Multi-page asset size tables & chunks | Single status line | **0 lines (completely silent)** |
+| **Token Cost (Success)** | **~2,000 - 8,000 tokens** | **~15 tokens** | **0 tokens** |
+| **Failure Diagnosis** | Scatted across hundreds of lines | Categorized diagnostic buckets | Exact failure lines only |
+
+```bash
+$ npx chemx build
+Auditing build: npx tsc --noEmit
+✔ Build Succeeded (5.20s)
+```
+
+#### 4. Full Pipeline: `chemx verify` Grand Total
+
+When an AI agent runs a complete pre-commit or post-refactor verification pass:
+
+| Verification Stage | Raw Unthrottled Shell Commands | Chemical X `chemx verify` |
+| :--- | :--- | :--- |
+| **7-Pillar AST Audit** | ~4,000 tokens | Included |
+| **TypeScript Compilation** | ~14 tokens | Included |
+| **Project Test Suite** | ~12,960 tokens | Included |
+| **Total Context Burn** | **~17,000+ tokens** | **~45 tokens** |
+| **Context Savings** | Baseline | **99.7% Token Reduction** |
+
+```
+$ npx chemx verify --dir=blueprints
+
+  ⚡ Chemical X: Token-Conserving Project Verification
+
+  ✔ AST Architecture:  A+ (100/100, 0 violations)
+  ✔ TypeScript:        Clean (0 errors)
+  ✔ Test Suite:        Passed (143/143)
+
+  All verification checks passed with zero context burn!
+```
+
+---
+
+## Model Context Protocol (MCP) Server
+
+Chemical X includes a high-performance, zero-dependency JSON-RPC 2.0 Stdio MCP server that connects directly to AI agent hosts (Cursor, Claude Desktop, Windsurf, Antigravity, VS Code).
+
+### Automatic 1-Step Installation
+
+Run the interactive installer in your workspace root:
+
+```bash
+npx chemx install-mcp
+```
+
+This automatically registers the Chemical X server in:
+- `.cursor/mcp.json` (Cursor IDE)
+- `.vscode/mcp.json` (VS Code)
+- `~/.gemini/config/mcp_config.json` (Antigravity)
+- Injects `chemx:mcp`, `chemx:verify`, `chemx:test`, and `chemx:typecheck` into your `package.json` scripts
+
+### Manual MCP Server Configuration
+
+To configure manually in your MCP client settings (e.g. `claude_desktop_config.json` or `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "chemical-x": {
+      "command": "npx",
+      "args": ["-y", "chemx", "mcp"]
+    }
+  }
+}
+```
+
+### Available MCP Tools (14 Tools)
+
+| Tool Name | Scope | Purpose |
+| :--- | :--- | :--- |
+| `chemx_verify` | Verification | Full pipeline gatekeeper: AST Audit + Typecheck + Tests into a ~45-token card. |
+| `chemx_typecheck` | Verification | Silent TypeScript typecheck audit. Drops compiler noise; returns structured diagnostics on error. |
+| `chemx_test` | Verification | Silent project test runner. Suppresses passing checkmarks; returns ONLY failing test assertions. |
+| `chemx_audit_build` | Verification | Wrap build commands with silent execution and catalog compiler diagnostics into structured categories. |
+| `chemx_audit` | Quality | Run the full 7-Pillar Chemical X static AST audit. Returns health score, grade (A+ to F), and hazard list. |
+| `chemx_check` | Quality | Verify a single file or capsule against molecular boundary rules (< 100L, 2-stage booleans, zero raw DOM). |
+| `chemx_q` | Discovery | AST search index query machine. Query symbols, capsules, props, and hooks with minimal token burn. |
+| `chemx_query_patterns` | Discovery | Detect duplicated state machines, cloned UI layouts, and parallel hooks before decomposing monoliths. |
+| `chemx_read` | Reading | Token-minified file reader. Extracts AST outlines, stripped comments, or symbol blocks (80%+ token savings). |
+| `chemx_patch` | Editing | Surgically patch files with exact search and replace blocks without whole-file context dumps. |
+| `chemx_write` | Editing | Create or overwrite files with automatic SQLite AST indexing and boundary compliance checks. |
+| `chemx_autofix` | Remediation | Deterministically remediate safe violations (typography hyphens, markdown fences, AI slop comments). |
+| `chemx_generate_capsule` | Scaffolding | Deterministically generate a crystalline capsule directory (component, controller, SCSS, types, index). |
+| `chemx_get_refactor_prompt` | Prompting | Synthesize targeted refactoring prompts for Grade F critical hazards, hotspots, and slop artifacts. |
+
+### Living Resources & Prompts
+
+* **Resources**:
+  * `chemx://directives`: Mandatory Chemical X Molecular Architecture directives (AGENTS.md).
+  * `chemx://scorecard`: Live Molecular Health Index (MHI) grade, score, metrics, and active hazards.
+  * `chemx://blueprints/molecule`: Compliant molecule blueprint adhering to zero raw DOM standards.
+  * `chemx://blueprints/view-template`: Declarative 10-20 line Table-of-Contents view blueprint.
+* **Prompts**:
+  * `chemx_remediate_hotspot`: Dynamically inspects candidate file AST metrics and generates targeted decomposition instructions.
+  * `chemx_harmonize_patterns`: Generates Pre-Split Pattern Discovery instructions to extract shared capsules.
+
+---
+
 ## Release Versioning: Minute-Precision CalVer
 
 This package adheres to **Minute-Precision Calendar Versioning** (`YY.MM.DD-MMMM`):
-- `YY.MM.DD`: Release date (e.g. `26.9.14` for Sept 14, 2026).
+- `YY.MM.DD`: Release date (e.g. `26.9.17` for Sept 17, 2026).
 - `MMMM`: Minute of the day (0 to 1439).
 
+Check installed version at any time:
+```bash
+npx chemx --version
+# create-chemx v26.9.17-606
+```
+
 Because autonomous coding agent models update frequently, this package is continuously integrated and deployed via automated CI whenever new agent directives, AST checks, or framework rules are tuned. Rapid version iterations reflect active, daily alignment rather than breaking SemVer shifts.
 
 > [!NOTE]

package/blueprints/molecule-capsule/m-tab-button/m-tab-button.controller.ts

@@ -1,21 +1,18 @@
 import { computed } from 'vue';
 import type { TabButtonProps, TabTone } from './types';
 
+const TONE_CLASSES: Record<TabTone, string> = {
+  lime: 'm-tab-button--lime',
+  pink: 'm-tab-button--pink',
+  slate: 'm-tab-button--slate',
+  sky: 'm-tab-button--sky'
+};
+
 export function useTabButtonController(props: TabButtonProps, emit: (event: 'click' | 'select') => void) {
   const isSelected = computed((): boolean => Boolean(props.isActive));
 
   const resolveToneClass = (tone: TabTone = 'sky'): string => {
-    switch (tone) {
-      case 'lime':
-        return 'm-tab-button--lime';
-      case 'pink':
-        return 'm-tab-button--pink';
-      case 'slate':
-        return 'm-tab-button--slate';
-      case 'sky':
-      default:
-        return 'm-tab-button--sky';
-    }
+    return TONE_CLASSES[tone] || TONE_CLASSES.sky;
   };
 
   const stateClass = computed((): string => {

package/cli/audit/ast-visitors.js

@@ -89,6 +89,29 @@ export const createAstVisitors = ({ relativePath, violations }) => {
       }
     },
 
+    IfStatement(astPath) {
+      const expr = astPath.node.test;
+      if (t.isLogicalExpression(expr)) {
+        const opCount = countLogicalOperators(expr);
+        const hasBinaryClauses = (t.isBinaryExpression(expr.left) || t.isLogicalExpression(expr.left)) &&
+                                 (t.isBinaryExpression(expr.right) || t.isLogicalExpression(expr.right));
+        if (opCount > 2 || (opCount >= 2 && hasBinaryClauses)) {
+          const line = resolveStartLine(expr, astPath.node, 1);
+          const meta = RULE_REGISTRY.CONTROL_FLOW_INLINE_BOOLEAN;
+          violations.push({
+            filePath: relativePath,
+            line,
+            column: expr.loc?.start.column || 1,
+            hazard: `Inline multi-clause boolean comparison in if statement (${opCount} operators). Decompose into 2-stage booleans per Directive 3.A.`,
+            rule: 'CONTROL_FLOW_INLINE_BOOLEAN',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+        }
+      }
+    },
+
     ConditionalExpression(astPath) {
       if (t.isConditionalExpression(astPath.node.consequent) || t.isConditionalExpression(astPath.node.alternate)) {
         const line = astPath.node.loc?.start.line || 1;
@@ -106,6 +129,56 @@ export const createAstVisitors = ({ relativePath, violations }) => {
       }
     },
 
+    SwitchStatement(astPath) {
+      const cases = astPath.node.cases || [];
+      if (cases.length < 3) return;
+
+      const isDispatchConsequent = (statements) => {
+        if (!statements || statements.length === 0) return false;
+        if (statements.length === 1) {
+          const s = statements[0];
+          if (t.isReturnStatement(s)) return true;
+          if (t.isBlockStatement(s)) {
+            return s.body.length === 1 && t.isReturnStatement(s.body[0]);
+          }
+        }
+        if (statements.length === 2) {
+          const [first, second] = statements;
+          if (t.isBreakStatement(second)) {
+            return t.isExpressionStatement(first) || t.isAssignmentExpression(first);
+          }
+        }
+        return false;
+      };
+
+      let dispatchCaseCount = 0;
+      let nonDefaultCount = 0;
+
+      for (const switchCase of cases) {
+        if (!switchCase.test) continue;
+        nonDefaultCount += 1;
+        if (isDispatchConsequent(switchCase.consequent)) {
+          dispatchCaseCount += 1;
+        }
+      }
+
+      const isDispatchSmell = nonDefaultCount >= 3 && (dispatchCaseCount / nonDefaultCount) >= 0.7;
+      if (isDispatchSmell) {
+        const line = astPath.node.loc?.start.line || 1;
+        const meta = RULE_REGISTRY.CONTROL_FLOW_DISPATCH_SWITCH;
+        violations.push({
+          filePath: relativePath,
+          line,
+          column: astPath.node.loc?.start.column || 1,
+          hazard: `Dispatch switch smell detected (${dispatchCaseCount} repetitive case branches)`,
+          rule: 'CONTROL_FLOW_DISPATCH_SWITCH',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      }
+    },
+
     // Pillar 5: Design System & Inline Styles
     JSXAttribute(astPath) {
       const attrName = astPath.node.name?.name;

package/cli/audit/extended-text-patterns.js

@@ -0,0 +1,218 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { RULE_REGISTRY } from './rules-registry.js';
+import { toResultSync } from './rules-helpers.js';
+import {
+  isComponentExtension,
+  isTemplateExtension,
+  isCommentLine
+} from './rules-predicates.js';
+
+const SECRET_PATTERNS = [
+  /(['"])(?:sk-[a-zA-Z0-9_-]{24,}|ghp_[a-zA-Z0-9]{30,}|AKIA[0-9A-Z]{16}|AIza[0-9A-Za-z-_]{35})\1/
+];
+
+const FAKE_GREEN_PATTERNS = [
+  /expect\s*\(\s*(true|false|1|0)\s*\)\s*\.\s*to(?:Be|Equal|StrictEqual)\s*\(\s*\1\s*\)/,
+  /assert\s*\.\s*(?:strictEqual|equal|deepEqual)\s*\(\s*(true|false|1|0)\s*,\s*\1\s*\)/,
+  /assert\s*\.\s*ok\s*\(\s*(?:true|1)\s*\)/
+];
+
+const IMG_WITHOUT_ALT_PATTERN = new RegExp(['<', 'img\\b', '(?![^>]*\\balt\\s*=)', '[^>]*>'].join(''), 'i');
+const CLICKABLE_CONTAINER_PATTERN = new RegExp(['<', '(div|span)\\b', '(?![^>]*\\brole\\s*=\\s*[\'"](?:button|link|tab)[\'"])', '[^>]*\\b(?:@click|v-on:click)\\s*='].join(''), 'i');
+const TABNABBING_TEMPLATE_PATTERN = /<a\b[^>]*\btarget\s*=\s*["']_blank["'][^>]*>/i;
+const JAVASCRIPT_URL_TEMPLATE_PATTERN = /\b(?:href|src|action|formaction)\s*=\s*["']\s*javascript:/i;
+
+/**
+ * Pillar 10: Check for co-located test files for molecule capsules.
+ */
+export const checkMoleculeCoLocatedTest = (filePath, relativePath, violations) => {
+  const baseName = path.basename(filePath);
+  const ext = path.extname(filePath);
+
+  // Stage 1: Atomic Concept Declarations
+  const isMoleculePath = relativePath.includes('molecules') || baseName.startsWith('m-');
+  const isComponentExt = isComponentExtension(ext);
+  const isTestOrSpecFile = baseName.includes('.spec.') || baseName.includes('.test.');
+
+  // Stage 2: Unified Decision Variable & Early Guard Clause
+  const isCandidateComponent = isMoleculePath && isComponentExt;
+  const isMoleculeComponent = isCandidateComponent && !isTestOrSpecFile;
+  if (!isMoleculeComponent) return;
+
+  const dir = path.dirname(filePath);
+  const [siblings, dirError] = toResultSync(() => (fs.existsSync(dir) ? fs.readdirSync(dir) : []));
+
+  // Stage 1: Atomic Guard Check
+  const hasDirError = Boolean(dirError);
+  const hasSiblings = Boolean(siblings);
+  const canInspectSiblings = !hasDirError && hasSiblings;
+  if (!canInspectSiblings) return;
+
+  const isTestSibling = (fileName) => /\.(test|spec)\.[jt]sx?$/.test(fileName);
+  const hasCoLocatedTest = siblings.some(isTestSibling);
+  if (hasCoLocatedTest) return;
+
+  const meta = RULE_REGISTRY.TEST_MISSING_COLOCATED;
+  violations.push({
+    filePath: relativePath,
+    line: 1,
+    column: 1,
+    hazard: 'Molecule capsule missing co-located test file (*.spec.ts or *.test.ts)',
+    rule: 'TEST_MISSING_COLOCATED',
+    severity: meta.severity,
+    pillar: meta.pillar,
+    directive: meta.directive
+  });
+};
+
+export const checkExtendedTextPatterns = (content, lines, relativePath, filePath, violations) => {
+  checkMoleculeCoLocatedTest(filePath, relativePath, violations);
+
+  const isTestFile = /\.(test|spec)\.[jt]sx?$/.test(filePath);
+  const ext = path.extname(filePath);
+  const isTemplateFile = isTemplateExtension(ext);
+
+  lines.forEach((lineText, idx) => {
+    const lineNum = idx + 1;
+    const trimmed = lineText.trim();
+    const isComment = isCommentLine(trimmed);
+
+    // Pillar 9: Hardcoded Secret Detection
+    const hasEnvReference = trimmed.includes('process.env') || trimmed.includes('import.meta.env');
+    const canScanSecrets = !isComment && !hasEnvReference;
+
+    if (canScanSecrets) {
+      for (const pat of SECRET_PATTERNS) {
+        const matchesSecretPattern = pat.test(lineText);
+        const hasPlaceholder = lineText.includes('dummy') || lineText.includes('placeholder');
+        const isHardcodedSecret = matchesSecretPattern && !hasPlaceholder;
+
+        if (isHardcodedSecret) {
+          const meta = RULE_REGISTRY.SECURITY_HARDCODED_SECRET;
+          violations.push({
+            filePath: relativePath,
+            line: lineNum,
+            column: 1,
+            hazard: 'High-entropy API key or secret token detected in source code',
+            rule: 'SECURITY_HARDCODED_SECRET',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+          break;
+        }
+      }
+    }
+
+    // Pillar 9: Unsanitized v-html injection (Vue / HTML templates)
+    const hasVHtml = isTemplateFile && /\bv-html\s*=\s*["']/.test(lineText);
+    if (hasVHtml) {
+      const hasSanitizer = /(?:sanitize|DOMPurify|escapeHtml|filterXSS)/i.test(lineText);
+      const isUnsanitizedVHtml = !hasSanitizer;
+
+      if (isUnsanitizedVHtml) {
+        const meta = RULE_REGISTRY.SECURITY_RAW_HTML_INJECTION;
+        violations.push({
+          filePath: relativePath,
+          line: lineNum,
+          column: 1,
+          hazard: 'Unsanitized HTML injection via v-html detected without DOMPurify',
+          rule: 'SECURITY_RAW_HTML_INJECTION',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      }
+    }
+
+    // Pillar 9: Reverse Tabnabbing in HTML / Vue templates
+    const hasTargetBlank = isTemplateFile && TABNABBING_TEMPLATE_PATTERN.test(lineText);
+    if (hasTargetBlank) {
+      const hasRelProtection = /\brel\s*=\s*["'][^"']*(?:noopener|noreferrer)[^"']*["']/i.test(lineText);
+      if (!hasRelProtection) {
+        const meta = RULE_REGISTRY.SECURITY_REVERSE_TABNABBING;
+        violations.push({
+          filePath: relativePath,
+          line: lineNum,
+          column: 1,
+          hazard: 'External link with target="_blank" missing rel="noopener noreferrer"',
+          rule: 'SECURITY_REVERSE_TABNABBING',
+          severity: meta.severity,
+          pillar: meta.pillar,
+          directive: meta.directive
+        });
+      }
+    }
+
+    // Pillar 9: javascript: pseudo-protocol in HTML / Vue templates
+    const hasJsUrl = isTemplateFile && JAVASCRIPT_URL_TEMPLATE_PATTERN.test(lineText);
+    if (hasJsUrl) {
+      const meta = RULE_REGISTRY.SECURITY_JAVASCRIPT_URL;
+      violations.push({
+        filePath: relativePath,
+        line: lineNum,
+        column: 1,
+        hazard: 'javascript: pseudo-protocol detected in template attribute',
+        rule: 'SECURITY_JAVASCRIPT_URL',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+    }
+
+    // Pillar 8: Non-semantic clickable containers in templates (@click on div/span)
+    const hasClickableContainer = isTemplateFile && CLICKABLE_CONTAINER_PATTERN.test(lineText);
+    if (hasClickableContainer) {
+      const meta = RULE_REGISTRY.A11Y_CLICKABLE_NON_SEMANTIC;
+      violations.push({
+        filePath: relativePath,
+        line: lineNum,
+        column: 1,
+        hazard: 'Clickable generic container detected without native button/link semantics',
+        rule: 'A11Y_CLICKABLE_NON_SEMANTIC',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+    }
+
+    // Pillar 8: Missing alt attribute on img tags
+    const hasMissingAltImg = isTemplateFile && IMG_WITHOUT_ALT_PATTERN.test(lineText);
+    if (hasMissingAltImg) {
+      const meta = RULE_REGISTRY.A11Y_IMAGE_MISSING_ALT;
+      violations.push({
+        filePath: relativePath,
+        line: lineNum,
+        column: 1,
+        hazard: 'Image element missing alt text attribute',
+        rule: 'A11Y_IMAGE_MISSING_ALT',
+        severity: meta.severity,
+        pillar: meta.pillar,
+        directive: meta.directive
+      });
+    }
+
+    // Pillar 10: Fake green tests (only in spec/test files)
+    const canCheckFakeGreen = isTestFile && !isComment;
+    if (canCheckFakeGreen) {
+      for (const pat of FAKE_GREEN_PATTERNS) {
+        const isFakeGreenMatch = pat.test(lineText);
+        if (isFakeGreenMatch) {
+          const meta = RULE_REGISTRY.TEST_FAKE_GREEN;
+          violations.push({
+            filePath: relativePath,
+            line: lineNum,
+            column: 1,
+            hazard: 'Fake green test assertion detected (asserting literal against itself)',
+            rule: 'TEST_FAKE_GREEN',
+            severity: meta.severity,
+            pillar: meta.pillar,
+            directive: meta.directive
+          });
+          break;
+        }
+      }
+    }
+  });
+};