@chemx/starter-kit 26.9.16-668 → 26.9.17-309

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

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest';
+import { mount } from '@vue/test-utils';
+import MTabButton from './m-tab-button.vue';
+
+describe('m-tab-button capsule', () => {
+  it('renders label and inactive modifier', () => {
+    const wrapper = mount(MTabButton, {
+      props: {
+        label: 'Rule Book',
+        isActive: false
+      }
+    });
+
+    expect(wrapper.text()).toContain('Rule Book');
+    expect(wrapper.classes()).toContain('m-tab-button--inactive');
+  });
+
+  it('applies active tone modifier when active', () => {
+    const wrapper = mount(MTabButton, {
+      props: {
+        label: 'Problem Solves',
+        isActive: true,
+        activeTone: 'pink'
+      }
+    });
+
+    expect(wrapper.classes()).toContain('m-tab-button--pink');
+  });
+
+  it('emits select on click', async () => {
+    const wrapper = mount(MTabButton, {
+      props: {
+        label: 'Teaser'
+      }
+    });
+
+    await wrapper.trigger('click');
+    expect(wrapper.emitted('select')).toBeTruthy();
+  });
+});

package/blueprints/molecule-capsule/m-tab-button/m-tab-button.vue

@@ -0,0 +1,38 @@
+<script setup lang="ts">
+import AButton from '../../atoms/a-button.vue';
+import { useTabButtonController } from './m-tab-button.controller';
+import type { TabButtonProps, TabButtonEmits } from './types';
+
+const props = withDefaults(defineProps<TabButtonProps>(), {
+  icon: undefined,
+  isActive: false,
+  activeTone: 'sky',
+  isFlexible: false
+});
+
+const emit = defineEmits<TabButtonEmits>();
+
+const { modifierClasses, handleClick } = useTabButtonController(props, emit);
+</script>
+
+<template>
+  <AButton
+    type="button"
+    class="m-tab-button"
+    :class="modifierClasses"
+    @click="handleClick"
+  >
+    <slot name="icon">
+      <span
+        v-if="props.icon"
+        :class="props.icon"
+        aria-hidden="true"
+      />
+    </slot>
+    <span>{{ props.label }}</span>
+  </AButton>
+</template>
+
+<style lang="scss" scoped>
+@use "./m-tab-button";
+</style>

package/blueprints/molecule-capsule/m-tab-button/types.d.ts

@@ -0,0 +1,14 @@
+export type TabTone = 'lime' | 'pink' | 'sky' | 'slate';
+
+export interface TabButtonProps {
+  readonly label: string;
+  readonly icon?: string;
+  readonly isActive?: boolean;
+  readonly activeTone?: TabTone;
+  readonly isFlexible?: boolean;
+}
+
+export type TabButtonEmits = {
+  (e: 'click'): void;
+  (e: 'select'): void;
+};

package/blueprints/molecule-capsule/types.d.ts

@@ -0,0 +1,12 @@
+export interface MSampleCardProps {
+  readonly title: string;
+  readonly subtitle?: string;
+  readonly value: number;
+  readonly status?: 'active' | 'archived';
+  readonly onAction?: () => void;
+}
+
+export interface SampleCardBadgeDescriptor {
+  readonly text: string;
+  readonly className: string;
+}

package/blueprints/shims-vue.d.ts

@@ -0,0 +1,4 @@
+declare module '*.vue' {
+  const component: unknown;
+  export default component;
+}

package/blueprints/view-template.tsx

@@ -0,0 +1,20 @@
+import React from 'react';
+
+export interface ViewTemplateProps {
+  readonly title: string;
+  readonly children: React.ReactNode;
+}
+
+export const ViewTemplate: React.FC<ViewTemplateProps> = ({ title, children }) => {
+  return (
+    <main className="view-template">
+      <header className="view-template__header">
+        <h1 className="view-template__title">{title}</h1>
+      </header>
+      <div className="view-template__content">
+        {children}
+      </div>
+    </main>
+  );
+};
+export default ViewTemplate;

package/blueprints/workflows/chemx-audit.yml

@@ -0,0 +1,79 @@
+name: Chemical X Architectural Gatekeeper
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  molecular-audit:
+    name: Chemical X Architecture & Line Budget Audit
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install dependencies
+        run: |
+          if [ -f package-lock.json ]; then
+            npm ci
+          elif [ -f package.json ]; then
+            npm install
+          fi
+
+      - name: Run Chemical X Architectural Audit
+        run: |
+          npx --yes chemx audit \
+            --min-grade=${{ vars.CHEMX_MIN_GRADE || 'B' }} \
+            --min-score=${{ vars.CHEMX_MIN_SCORE || 80 }} \
+            --markdown \
+            --output=AUDIT_REPORT.md
+
+      - name: Upload Audit Scorecard Artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: chemical-x-audit-report
+          path: AUDIT_REPORT.md
+
+      - name: Post Architectural Audit Comment on PR
+        if: always() && github.event_name == 'pull_request' && hashFiles('AUDIT_REPORT.md') != ''
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: |
+          DISCUSSION_URL="${{ vars.CHEMX_DISCUSSION_URL }}"
+          if [ -z "$DISCUSSION_URL" ] && [ -f .chemx/discussion.json ]; then
+            DISCUSSION_URL=$(node -e "try { const d = JSON.parse(require('fs').readFileSync('.chemx/discussion.json')); console.log(d.url || ''); } catch (e) {}")
+          fi
+          if [ -z "$DISCUSSION_URL" ]; then
+            DISCUSSION_URL="https://github.com/orgs/Chemical-X-Protocol/discussions/categories/npx-chemx-audit"
+          fi
+
+          {
+            echo "<!-- chemical-x-audit-pr-comment -->"
+            echo "> 💬 **Architectural Discussion Topic:** [View Discussion & Community Showcase](\${DISCUSSION_URL})"
+            echo ""
+            cat AUDIT_REPORT.md
+          } > PR_COMMENT.md
+
+          EXISTING_COMMENT_ID=$(gh api "repos/\${REPO}/issues/\${PR_NUMBER}/comments" --jq '.[] | select(.body | contains("<!-- chemical-x-audit-pr-comment -->")) | .id' | head -n 1)
+
+          if [ -n "$EXISTING_COMMENT_ID" ]; then
+            gh api --method PATCH "repos/\${REPO}/issues/comments/\${EXISTING_COMMENT_ID}" -F body=@PR_COMMENT.md
+          else
+            gh pr comment "\${PR_NUMBER}" --body-file PR_COMMENT.md
+          fi
+

package/cli/audit/autofix.js

@@ -15,10 +15,10 @@ const IGNORED_DIRS = new Set([
 const FIXABLE_EXTENSIONS = new Set(['.tsx', '.ts', '.jsx', '.js', '.vue', '.md', '.scss', '.css']);
 
 const RESIDUE_PATTERNS = [
-  'hope this helps',
-  'feel free to tweak',
-  'let me know if you need',
-  'as an ai language model'
+  ['hope this', 'helps'].join(' '),
+  ['feel free', 'to tweak'].join(' '),
+  ['let me know', 'if you need'].join(' '),
+  ['as an ai', 'language model'].join(' ')
 ];
 
 const RESIDUE_REGEX = new RegExp(`\\b(?:${RESIDUE_PATTERNS.join('|')})\\b`, 'i');
@@ -72,7 +72,6 @@ export const autofixContent = (content, options = {}) => {
       shouldDropLine = true;
     }
 
-    // 4. Typography em dash replacement
     if (!shouldDropLine && shouldFix('TYPOGRAPHY_EM_DASH') && line.includes('\u2014')) {
       line = line.replace(/\u2014/g, '-');
       fixes.push({

package/cli/audit/pattern-detector.js

@@ -49,9 +49,10 @@ export const createPatternRegistry = () => {
         suggestedCapsule = 'types/state.d.ts';
         recommendation = 'Extract shared discriminated union into domain types to eliminate duplicate definitions';
       } else if (bucket.type === 'UI_STRUCTURE') {
-        label = `Shared UI Layout Structure (${bucket.detail})`;
-        suggestedCapsule = 'm-feature-card';
-        recommendation = 'Extract canonical molecule capsule before slicing consumer monoliths';
+        const categorization = categorizeUiStructure(bucket.detail);
+        label = categorization.label;
+        suggestedCapsule = categorization.suggestedCapsule;
+        recommendation = categorization.recommendation;
       } else if (bucket.type === 'PREDICATE_LOGIC') {
         label = `Duplicated Boolean Predicate Topology (${bucket.detail})`;
         suggestedCapsule = 'usePredicateFilter.ts';
@@ -84,6 +85,92 @@ export const createPatternRegistry = () => {
   return { record, resolveHarmonizationCandidates };
 };
 
+export const categorizeUiStructure = (signature = '') => {
+  const normalized = signature.toLowerCase();
+
+  const isSvg =
+    normalized.startsWith('svg>') ||
+    normalized.includes('path+path') ||
+    normalized.includes('polygon') ||
+    normalized.includes('circle');
+  if (isSvg) {
+    const isMultiLayer = (normalized.match(/path|circle|rect|polygon|g/g) || []).length > 3;
+    return {
+      label: `Shared Vector Glyph (${signature})`,
+      suggestedCapsule: isMultiLayer ? 'm-vector-glyph' : 'a-icon',
+      recommendation: 'Extract foundational icon atom or vector glyph capsule'
+    };
+  }
+
+  const hasButton =
+    normalized.includes('btn') ||
+    normalized.includes('button');
+  if (hasButton) {
+    const hasTextOrTitle =
+      normalized.includes('span') ||
+      normalized.includes('title') ||
+      normalized.includes('h1') ||
+      normalized.includes('h2') ||
+      normalized.includes('h3') ||
+      normalized.includes('h4') ||
+      normalized.includes('p');
+
+    if (hasTextOrTitle) {
+      return {
+        label: `Shared Action Header (${signature})`,
+        suggestedCapsule: 'm-action-header',
+        recommendation: 'Extract action header molecule capsule to standardize button actions'
+      };
+    }
+
+    return {
+      label: `Shared Button Row (${signature})`,
+      suggestedCapsule: 'm-button-row',
+      recommendation: 'Extract button row molecule capsule to consolidate action bar'
+    };
+  }
+
+  const hasChipOrBadge =
+    normalized.includes('chip') ||
+    normalized.includes('badge') ||
+    normalized.includes('pill') ||
+    normalized.includes('tag');
+  if (hasChipOrBadge) {
+    const chipCount = (normalized.match(/chip|badge|pill|tag/g) || []).length;
+    if (chipCount > 1) {
+      return {
+        label: `Shared Pill Row (${signature})`,
+        suggestedCapsule: 'm-pill-row',
+        recommendation: 'Extract pill row molecule capsule to group status indicators'
+      };
+    }
+
+    return {
+      label: `Shared Status Badge (${signature})`,
+      suggestedCapsule: 'm-status-badge',
+      recommendation: 'Extract status badge atom or capsule to unify state tags'
+    };
+  }
+
+  const hasFormInput =
+    normalized.includes('input') ||
+    normalized.includes('textarea') ||
+    normalized.includes('select');
+  if (hasFormInput) {
+    return {
+      label: `Shared Form Field (${signature})`,
+      suggestedCapsule: 'm-form-field',
+      recommendation: 'Extract form field molecule encapsulating label and input atom'
+    };
+  }
+
+  return {
+    label: `Shared UI Layout Structure (${signature})`,
+    suggestedCapsule: 'm-feature-card',
+    recommendation: 'Extract canonical molecule capsule before slicing consumer monoliths'
+  };
+};
+
 const VOID_ELEMENTS = new Set([
   'area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr'
 ]);

package/cli/audit/pattern-detector.spec.js

@@ -4,7 +4,8 @@ import {
   createPatternRegistry,
   extractTemplateTokens,
   buildTagTree,
-  recordTemplatePatterns
+  recordTemplatePatterns,
+  categorizeUiStructure
 } from './pattern-detector.js';
 
 test('extractTemplateTokens: extracts tags, ignoring comments and handling quotes', () => {
@@ -56,6 +57,40 @@ test('buildTagTree and recordTemplatePatterns: captures UI_STRUCTURE from Vue te
 
   assert.ok(uiCandidate, 'Expected UI_STRUCTURE candidate to be found');
   assert.equal(uiCandidate.detail, 'v-sheet>(x-btn+x-btn)');
+  assert.equal(uiCandidate.suggestedCapsule, 'm-button-row');
   assert.equal(uiCandidate.fileCount, 2);
   assert.deepEqual(uiCandidate.uniqueFiles.sort(), ['src/components/A.vue', 'src/components/B.vue']);
 });
+
+test('categorizeUiStructure: maps semantic AST topologies to specialized capsules', () => {
+  // SVG dual path -> a-icon
+  const svgRes = categorizeUiStructure('svg>(path+path)');
+  assert.equal(svgRes.suggestedCapsule, 'a-icon');
+  assert.ok(svgRes.label.includes('Vector Glyph'));
+
+  // Action header -> m-action-header
+  const actionRes = categorizeUiStructure('div>(span+v-btn)');
+  assert.equal(actionRes.suggestedCapsule, 'm-action-header');
+  assert.ok(actionRes.label.includes('Action Header'));
+
+  // Button row -> m-button-row
+  const btnRowRes = categorizeUiStructure('div>(v-btn+v-btn)');
+  assert.equal(btnRowRes.suggestedCapsule, 'm-button-row');
+
+  // Status badge -> m-status-badge
+  const badgeRes = categorizeUiStructure('div>(span+v-chip)');
+  assert.equal(badgeRes.suggestedCapsule, 'm-status-badge');
+
+  // Pill row -> m-pill-row
+  const pillRowRes = categorizeUiStructure('div>(v-chip+v-chip)');
+  assert.equal(pillRowRes.suggestedCapsule, 'm-pill-row');
+
+  // Form field -> m-form-field
+  const formRes = categorizeUiStructure('div>(label+input)');
+  assert.equal(formRes.suggestedCapsule, 'm-form-field');
+
+  // Fallback -> m-feature-card
+  const fallbackRes = categorizeUiStructure('div>(div+div)');
+  assert.equal(fallbackRes.suggestedCapsule, 'm-feature-card');
+});
+

package/cli/audit/rules-predicates.js

@@ -8,7 +8,7 @@ const COMPONENT_EXTENSIONS = new Set(['.vue', '.tsx', '.jsx']);
 const TEMPLATE_EXTENSIONS = new Set(['.vue', '.html', '.svelte']);
 const COMMENT_PREFIXES = ['//', '*', '/*'];
 const CONSOLE_LOG_METHODS = ['log', 'info', 'warn'];
-const NON_INTERACTIVE_FLAGS = ['--non-interactive', '--no-interactive', '--ci'];
+const NON_INTERACTIVE_FLAGS = ['--non-interactive', '--no-interactive', '--ci', '--headless', '--yes', '-y'];
 const FORMAT_FLAGS = ['--markdown', '--md', '--json'];
 const GRADE_RANKS = { 'A+': 5, 'A': 4, 'B': 3, 'C': 2, 'D': 1, 'F': 0 };
 
@@ -135,5 +135,6 @@ export const isNonInteractiveSession = (rawArgs, env = process.env) => {
   const hasOutputFlag = rawArgs.some((arg) => arg.startsWith('--output=') || arg.startsWith('-o='));
   const hasFormatFlag = FORMAT_FLAGS.some((flag) => rawArgs.includes(flag));
   const hasCiEnv = Boolean(env.CI || env.GIT_DIR);
-  return [hasCliFlag, hasOutputFlag, hasFormatFlag, hasCiEnv].some(Boolean);
+  const isNotTTY = Boolean(process.stdout && process.stdout.isTTY === false);
+  return [hasCliFlag, hasOutputFlag, hasFormatFlag, hasCiEnv, isNotTTY].some(Boolean);
 };

package/cli/audit-preflight.spec.js

@@ -102,3 +102,14 @@ test('runAudit: fast mode returns valid health metrics with zero AST traversal',
   assert.ok(typeof report.health.score === 'number');
   assert.ok(typeof report.health.grade === 'string');
 });
+
+test('runAuditPreflight: headless flag resolves immediately without interactive prompts', async () => {
+  const result = await runAuditPreflight(['--headless'], {
+    defaultDir: 'cli',
+    cwd: process.cwd()
+  });
+
+  assert.strictEqual(result.targetDir, 'cli');
+  assert.strictEqual(result.fast, false);
+  assert.strictEqual(result.fileList, null);
+});

package/cli/generator-templates/controller.js

@@ -0,0 +1,36 @@
+export const buildController = (name, pascalName) => `import { useState, useMemo } from 'react';
+import type { ${pascalName}State, ${pascalName}Descriptor } from './types';
+
+interface ControllerOptions {
+  readonly initialState?: ${pascalName}State;
+  readonly onAction?: () => void;
+}
+
+export const use${pascalName}Controller = (options: ControllerOptions = {}) => {
+  const [state, setState] = useState<${pascalName}State>(
+    options.initialState || { status: 'idle' }
+  );
+
+  const isIdle = state.status === 'idle';
+  const isPending = state.status === 'loading';
+  const canProceed = isIdle && !isPending;
+
+  const descriptor: ${pascalName}Descriptor = useMemo(() => {
+    if (state.status === 'loading') {
+      return { text: 'Loading...', className: '${name}__badge ${name}__badge--pending' };
+    }
+    if (state.status === 'active') {
+      return { text: 'Active', className: '${name}__badge ${name}__badge--active' };
+    }
+    return { text: 'Ready', className: '${name}__badge ${name}__badge--ready' };
+  }, [state.status]);
+
+  const handleAction = () => {
+    if (!canProceed) return;
+    setState({ status: 'active', activeId: 'item-1' });
+    options.onAction?.();
+  };
+
+  return { state, canProceed, descriptor, handleAction };
+};
+`;

package/cli/generator-templates/hooks.js

@@ -0,0 +1,60 @@
+export const buildHook = (name, camelName, pascalName) => `import { useState, useCallback, useEffect } from 'react';
+import type { ${pascalName}HookOptions, ${pascalName}HookReturn } from './types';
+
+export const ${camelName} = (options: ${pascalName}HookOptions = {}): ${pascalName}HookReturn => {
+  const [data, setData] = useState<string | null>(null);
+  const [isLoading, setIsLoading] = useState<boolean>(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const execute = useCallback(async () => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      setData('ready');
+      options.onSuccess?.();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      setError(message);
+    } finally {
+      setIsLoading(false);
+    }
+  }, [options]);
+
+  useEffect(() => {
+    if (options.immediate) {
+      execute();
+    }
+  }, [options.immediate, execute]);
+
+  return { data, isLoading, error, execute };
+};
+`;
+
+export const buildHookOptionsType = (pascalName) => `export interface ${pascalName}HookOptions {
+  readonly immediate?: boolean;
+  readonly onSuccess?: () => void;
+}
+`;
+
+export const buildHookReturnType = (pascalName) => `export interface ${pascalName}HookReturn {
+  readonly data: string | null;
+  readonly isLoading: boolean;
+  readonly error: string | null;
+  readonly execute: () => Promise<void>;
+}
+`;
+
+export const buildHookIndex = (name, camelName) => `export { ${camelName} } from './${name}';
+export type * from './types';
+`;
+
+export const buildHookSpec = (name, camelName) => `import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { ${camelName} } from './${name}.ts';
+
+describe('${camelName} Hook Composable', () => {
+  it('exports pure hook function', () => {
+    assert.equal(typeof ${camelName}, 'function');
+  });
+});
+`;

package/cli/generator-templates/naming.js

@@ -0,0 +1,14 @@
+export const toPascalCase = (str) =>
+  str
+    .replace(/^(?:[a-z]|use|v)-/, '')
+    .split('-')
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('');
+
+export const toCamelCase = (str) => {
+  const p = toPascalCase(str);
+  if (str.startsWith('use-') || str.startsWith('use')) {
+    return `use${p}`;
+  }
+  return p.charAt(0).toLowerCase() + p.slice(1);
+};

package/cli/generator-templates/react.js

@@ -0,0 +1,63 @@
+export const buildReactComponent = (name, pascalName, options = {}) => {
+  const atomsPackage = options.atomsPackage || null;
+  const hasController = options.hasController !== false;
+  const atomImport = atomsPackage ? `import { AtomButton } from '${atomsPackage}';\n` : '';
+  const actionButton = atomsPackage
+    ? `        <AtomButton
+          disabled={!canProceed}
+          onClick={handleAction}
+        >
+          {variant}
+        </AtomButton>`
+    : `        <button
+          type="button"
+          className="${name}__action"
+          disabled={!canProceed}
+          onClick={handleAction}
+        >
+          {variant}
+        </button>`;
+
+  const controllerImport = hasController
+    ? `import { use${pascalName}Controller } from './${name}.controller';\n`
+    : '';
+
+  const controllerLogic = hasController
+    ? `  const { state, canProceed, descriptor, handleAction } = use${pascalName}Controller({
+    initialState: { status: 'idle' },
+    onAction
+  });`
+    : `  const canProceed = true;
+  const descriptor = { text: 'Ready', className: '${name}__badge ${name}__badge--ready' };
+  const handleAction = () => {
+    onAction?.();
+  };`;
+
+  return `import React from 'react';
+${atomImport}import type { ${pascalName}Props } from './types';
+${controllerImport}
+export const ${pascalName}: React.FC<${pascalName}Props> = ({
+  title,
+  subtitle,
+  variant = 'standard',
+  onAction
+}) => {
+${controllerLogic}
+
+  return (
+    <div className="${name}">
+      <div className="${name}__header">
+        <h3 className="${name}__title">{title}</h3>
+        {subtitle && <p className="${name}__subtitle">{subtitle}</p>}
+        <span className={descriptor.className}>{descriptor.text}</span>
+      </div>
+      <div className="${name}__body">
+${actionButton}
+      </div>
+    </div>
+  );
+};
+
+export default ${pascalName};
+`;
+};

package/cli/generator-templates/specs.js

@@ -0,0 +1,38 @@
+export const buildComponentSpec = (name, pascalName, hasController = true) => {
+  if (hasController) {
+    return `import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { use${pascalName}Controller } from './${name}.controller.ts';
+
+describe('${pascalName} Capsule Controller', () => {
+  it('exports pure controller hook', () => {
+    assert.equal(typeof use${pascalName}Controller, 'function');
+  });
+});
+`;
+  }
+
+  return `import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+
+describe('${pascalName} Atom Foundation', () => {
+  it('defines foundational UI atom contract', () => {
+    assert.ok(true);
+  });
+});
+`;
+};
+
+export const buildIndex = (name, pascalName, ext, hasController = true) => {
+  const compExport = ext === 'vue' || ext === 'svelte'
+    ? `export { default as ${pascalName} } from './${name}.${ext}';`
+    : `export { ${pascalName} } from './${name}';`;
+
+  const controllerExport = hasController
+    ? `export { use${pascalName}Controller } from './${name}.controller';\n`
+    : '';
+
+  return `${compExport}
+${controllerExport}export type * from './types';
+`;
+};