@chemx/starter-kit 26.9.9-786 → 26.9.11-481

package/cli/audit/rules-registry.js

@@ -0,0 +1,97 @@
+export const PILLARS = {
+  PILLAR_1: 'Line Budgets & Monolith Decomposition',
+  PILLAR_2: 'Control Flow & Boolean Logic',
+  PILLAR_3: 'Reactivity & Composable Contracts',
+  PILLAR_4: 'Type Architecture & Data Integrity',
+  PILLAR_5: 'Design System & Styling Hygiene',
+  PILLAR_6: 'Timers & Macro-Task Discipline',
+  PILLAR_7: 'Global Hygiene & Typography'
+};
+
+export const RULE_REGISTRY = {
+  LINE_BUDGET_FILE: {
+    pillar: PILLARS.PILLAR_1,
+    severity: 'MEDIUM',
+    directive: 'Decompose monolith into domain capsules and molecules'
+  },
+  LINE_BUDGET_MOLECULE: {
+    pillar: PILLARS.PILLAR_1,
+    severity: 'MEDIUM',
+    directive: 'Split molecule into focused sub-molecules or extract state to hook'
+  },
+  VIEW_MONOLITH: {
+    pillar: PILLARS.PILLAR_1,
+    severity: 'HIGH',
+    directive: 'Refactor top-level view to a 10 to 20 line Table of Contents'
+  },
+  CONTROL_FLOW_INLINE_BOOLEAN: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'MEDIUM',
+    directive: 'Compose booleans into Stage 1 concepts and Stage 2 decision variables'
+  },
+  CONTROL_FLOW_NESTED_TERNARY: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'CRITICAL',
+    directive: 'Extract display states into computed descriptor objects or early returns'
+  },
+  HOOK_SATURATION: {
+    pillar: PILLARS.PILLAR_3,
+    severity: 'HIGH',
+    directive: 'Extract related state and effects into dedicated domain hooks'
+  },
+  HOOK_RETURN_OVERLOAD: {
+    pillar: PILLARS.PILLAR_3,
+    severity: 'HIGH',
+    directive: 'Limit hook return values to 3 to 5 properties (State + Status + Actions)'
+  },
+  TIMER_DISCIPLINE: {
+    pillar: PILLARS.PILLAR_6,
+    severity: 'CRITICAL',
+    directive: 'Wrap timers in self-cleaning hooks returning lifecycle cleanup disposers'
+  },
+  RENDER_HACK_TIMEOUT: {
+    pillar: PILLARS.PILLAR_6,
+    severity: 'CRITICAL',
+    directive: 'Replace render-hack setTimeout(0) with await nextTick() or RAF'
+  },
+  TYPE_COLOCATION: {
+    pillar: PILLARS.PILLAR_4,
+    severity: 'MEDIUM',
+    directive: 'Define co-located domain interfaces in types/*.d.ts'
+  },
+  TYPE_MONOLITH: {
+    pillar: PILLARS.PILLAR_4,
+    severity: 'HIGH',
+    directive: 'Decompose root type monolith into co-located capsule types'
+  },
+  SYNTHETIC_MOCK_DATA: {
+    pillar: PILLARS.PILLAR_4,
+    severity: 'MEDIUM',
+    directive: 'Use live API data or explicit empty states instead of mock placeholders'
+  },
+  RAW_INLINE_STYLE: {
+    pillar: PILLARS.PILLAR_5,
+    severity: 'MEDIUM',
+    directive: 'Decouple into Level 1 atom props, SCSS mixins, or scoped classes via @apply'
+  },
+  ICON_SVG_STYLE_LEAK: {
+    pillar: PILLARS.PILLAR_5,
+    severity: 'LOW',
+    directive: 'Avoid text-* utility classes on FontAwesome icons; use color prop or CSS'
+  },
+  TYPOGRAPHY_EM_DASH: {
+    pillar: PILLARS.PILLAR_7,
+    severity: 'LOW',
+    directive: 'Replace em dashes with hyphens or colons per typography standard'
+  },
+  UNGUARDED_LOGGING: {
+    pillar: PILLARS.PILLAR_7,
+    severity: 'LOW',
+    directive: 'Route runtime diagnostics through a production-silenced debug proxy'
+  },
+  SYNTAX_PARSE_ERROR: {
+    pillar: PILLARS.PILLAR_1,
+    severity: 'CRITICAL',
+    directive: 'Fix syntax errors before static analysis'
+  }
+};

package/cli/audit/rules.js

@@ -0,0 +1,123 @@
+import { parse } from '@babel/parser';
+import traverse from '@babel/traverse';
+import path from 'node:path';
+import { PILLARS, RULE_REGISTRY } from './rules-registry.js';
+import {
+  extractParseableCode,
+  checkTypographyEmDash,
+  checkMockDataPatterns,
+  resolveMonolithTier,
+  resolveMoleculeTier
+} from './rules-helpers.js';
+import { createAstVisitors } from './ast-visitors.js';
+
+export { PILLARS, RULE_REGISTRY };
+
+export const auditCode = (content, filePath, relativePath) => {
+  const violations = [];
+  const lines = content.split('\n');
+  const lineCount = lines.length;
+  const ext = path.extname(filePath);
+  const baseName = path.basename(filePath);
+
+  const isMolecule = relativePath.includes('molecules') || relativePath.includes('/m-') || baseName.startsWith('m-');
+  const isView = relativePath.includes('/views/') || relativePath.includes('/pages/') || /View\.[tj]sx?$/.test(baseName);
+  const isRootTypeFile = baseName === 'types.ts' || baseName === 'global.d.ts';
+
+  // Pillar 1: Sliding Scale Monolith Detection
+  if (lineCount > 500) {
+    const tier = resolveMonolithTier(lineCount);
+    violations.push({
+      filePath: relativePath,
+      line: 1,
+      column: 1,
+      hazard: tier.hazard,
+      rule: 'LINE_BUDGET_FILE',
+      severity: tier.severity,
+      pillar: PILLARS.PILLAR_1,
+      directive: tier.directive
+    });
+  } else if (isMolecule && lineCount > 100) {
+    const tier = resolveMoleculeTier(lineCount);
+    violations.push({
+      filePath: relativePath,
+      line: 1,
+      column: 1,
+      hazard: tier.hazard,
+      rule: 'LINE_BUDGET_MOLECULE',
+      severity: tier.severity,
+      pillar: PILLARS.PILLAR_1,
+      directive: tier.directive
+    });
+  } else if (isView && lineCount > 200) {
+    const isSevere = lineCount >= 500;
+    const severity = isSevere ? 'CRITICAL' : 'MEDIUM';
+    const hazardLabel = isSevere
+      ? `Extreme view monolith (${lineCount} >= 500 lines)`
+      : `View template budget warning (${lineCount} > 200 lines)`;
+
+    violations.push({
+      filePath: relativePath,
+      line: 1,
+      column: 1,
+      hazard: hazardLabel,
+      rule: 'VIEW_MONOLITH',
+      severity,
+      pillar: PILLARS.PILLAR_1,
+      directive: 'Refactor top-level view to a 10 to 20 line Table of Contents'
+    });
+  }
+
+  // Pillar 4: Type Monolith
+  if (isRootTypeFile && lineCount > 150) {
+    const meta = RULE_REGISTRY.TYPE_MONOLITH;
+    violations.push({
+      filePath: relativePath,
+      line: 1,
+      column: 1,
+      hazard: `Root type file monolith detected (${lineCount} > 150 lines)`,
+      rule: 'TYPE_MONOLITH',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+  }
+
+  // Pillar 7: Typography & Mock Data Fast Checks
+  checkTypographyEmDash(content, lines, relativePath, violations);
+  checkMockDataPatterns(content, lines, relativePath, violations);
+
+  const codeToParse = extractParseableCode(content, ext);
+  if (!codeToParse.trim()) {
+    return violations;
+  }
+
+  let ast;
+  try {
+    ast = parse(codeToParse, {
+      sourceType: 'module',
+      plugins: ['typescript', 'jsx']
+    });
+  } catch (err) {
+    const errorMsg = err instanceof Error ? err.message : String(err);
+    const meta = RULE_REGISTRY.SYNTAX_PARSE_ERROR;
+    violations.push({
+      filePath: relativePath,
+      line: 1,
+      column: 1,
+      hazard: `Parse error: ${errorMsg}`,
+      rule: 'SYNTAX_PARSE_ERROR',
+      severity: meta.severity,
+      pillar: meta.pillar,
+      directive: meta.directive
+    });
+    return violations;
+  }
+
+  const traverseFn = traverse.default || traverse;
+  const visitors = createAstVisitors({ relativePath, violations });
+
+  traverseFn(ast, visitors);
+
+  return violations;
+};

package/cli/audit/social-constants.js

@@ -0,0 +1,4 @@
+export const DISCUSSION_CATEGORY = 'npx chemx audit';
+export const DISCUSSION_CATEGORY_SLUG = 'npx-chemx-audit';
+export const ORG_DISCUSSIONS_URL = 'https://github.com/orgs/Chemical-X-Protocol/discussions';
+export const DEFAULT_DISCUSSION_REPO = 'Chemical-X-Protocol/.github';

package/cli/audit/social-gh.js

@@ -0,0 +1,126 @@
+import { spawnSync } from 'node:child_process';
+import {
+  DISCUSSION_CATEGORY,
+  DISCUSSION_CATEGORY_SLUG
+} from './social-constants.js';
+
+export const publishDiscussionViaGh = (repo, title, body, category = DISCUSSION_CATEGORY) => {
+  try {
+    let res = spawnSync(
+      'gh',
+      ['discussion', 'create', '-R', repo, '--title', title, '--body', body, '--category', category],
+      { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }
+    );
+    if (res.status === 0) {
+      return { success: true, url: (res.stdout || '').trim(), error: null };
+    }
+
+    const errText = (res.stderr || '').trim();
+
+    if (errText.includes('category') && category !== DISCUSSION_CATEGORY_SLUG) {
+      res = spawnSync(
+        'gh',
+        ['discussion', 'create', '-R', repo, '--title', title, '--body', body, '--category', DISCUSSION_CATEGORY_SLUG],
+        { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }
+      );
+      if (res.status === 0) {
+        return { success: true, url: (res.stdout || '').trim(), error: null };
+      }
+    }
+
+    if (errText.includes('category') && category !== 'Audits') {
+      res = spawnSync(
+        'gh',
+        ['discussion', 'create', '-R', repo, '--title', title, '--body', body, '--category', 'Audits'],
+        { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }
+      );
+      if (res.status === 0) {
+        return { success: true, url: (res.stdout || '').trim(), error: null };
+      }
+    }
+
+    if (errText.includes('category')) {
+      res = spawnSync(
+        'gh',
+        ['discussion', 'create', '-R', repo, '--title', title, '--body', body, '--category', 'General'],
+        { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }
+      );
+      if (res.status === 0) {
+        return { success: true, url: (res.stdout || '').trim(), error: null };
+      }
+    }
+
+    return { success: false, url: null, error: errText };
+  } catch (err) {
+    return { success: false, url: null, error: err.message };
+  }
+};
+
+export const viewDiscussionViaGh = (repo, discussionNumber) => {
+  try {
+    const res = spawnSync(
+      'gh',
+      ['discussion', 'view', String(discussionNumber), '-R', repo, '--json', 'id,number,title,body,url'],
+      { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }
+    );
+    if (res.status === 0 && res.stdout) {
+      return JSON.parse(res.stdout);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};
+
+export const postDiscussionCommentViaGh = (repo, discussionNumber, commentBody) => {
+  try {
+    const res = spawnSync(
+      'gh',
+      ['discussion', 'comment', String(discussionNumber), '-R', repo, '--body', commentBody],
+      { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }
+    );
+    return res.status === 0;
+  } catch {
+    return false;
+  }
+};
+
+export const editDiscussionViaGh = (repo, discussionNumber, title, body) => {
+  try {
+    const res = spawnSync(
+      'gh',
+      ['discussion', 'edit', String(discussionNumber), '-R', repo, '--title', title, '--body', body],
+      { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }
+    );
+    return res.status === 0;
+  } catch {
+    return false;
+  }
+};
+
+export const findExistingDiscussionViaGh = (repo, projectName) => {
+  try {
+    const res = spawnSync(
+      'gh',
+      ['discussion', 'list', '-R', repo, '--limit', '25', '--json', 'id,number,title,body,url'],
+      { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] }
+    );
+    if (res.status === 0 && res.stdout) {
+      const list = JSON.parse(res.stdout);
+      const targetLower = projectName.toLowerCase();
+      const match = list.find((d) => {
+        const titleLower = (d.title || '').toLowerCase();
+        return (
+          titleLower.includes(` ${targetLower} :`) ||
+          titleLower.includes(` ${targetLower} [`) ||
+          titleLower.includes(`: ${targetLower}`) ||
+          titleLower.includes(`${targetLower} audit`)
+        );
+      });
+      return match || null;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+};

package/cli/audit/social-git.js

@@ -0,0 +1,214 @@
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+
+export const parseGitRemoteUrl = (url) => {
+  if (!url || typeof url !== 'string') return null;
+  const clean = url.trim().replace(/^git\+/, '').replace(/\.git$/, '');
+
+  // Match HTTPS / SSH: https://github.com/owner/repo or ssh://git@github.com/owner/repo
+  const httpMatch = clean.match(/^(?:https?|ssh|git):\/\/[^/]+\/([^/]+)\/([^/]+)$/);
+  if (httpMatch) {
+    const owner = httpMatch[1];
+    const repo = httpMatch[2];
+    return {
+      owner,
+      repo,
+      nameWithOwner: `${owner}/${repo}`,
+      url: `https://github.com/${owner}/${repo}`
+    };
+  }
+
+  // Match SCP-like SSH: git@github.com:owner/repo
+  const scpMatch = clean.match(/^[\w\-]+@[^:]+:([^/]+)\/([^/]+)$/);
+  if (scpMatch) {
+    const owner = scpMatch[1];
+    const repo = scpMatch[2];
+    return {
+      owner,
+      repo,
+      nameWithOwner: `${owner}/${repo}`,
+      url: `https://github.com/${owner}/${repo}`
+    };
+  }
+
+  return null;
+};
+
+export const detectGitRepoInfo = (cwd = process.cwd()) => {
+  // 1. Try git remote get-url origin
+  try {
+    const res = spawnSync('git', ['remote', 'get-url', 'origin'], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    if (res.status === 0 && res.stdout) {
+      const parsed = parseGitRemoteUrl(res.stdout);
+      if (parsed) return parsed;
+    }
+  } catch {}
+
+  // 2. Try git config --get remote.origin.url
+  try {
+    const res = spawnSync('git', ['config', '--get', 'remote.origin.url'], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    if (res.status === 0 && res.stdout) {
+      const parsed = parseGitRemoteUrl(res.stdout);
+      if (parsed) return parsed;
+    }
+  } catch {}
+
+  // 3. Try any available remote if origin is not configured
+  try {
+    const remotesRes = spawnSync('git', ['remote'], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    if (remotesRes.status === 0 && remotesRes.stdout) {
+      const firstRemote = (remotesRes.stdout.trim().split(/\s+/)[0] || '').trim();
+      if (firstRemote) {
+        const urlRes = spawnSync('git', ['remote', 'get-url', firstRemote], {
+          cwd,
+          encoding: 'utf-8',
+          stdio: ['ignore', 'pipe', 'ignore']
+        });
+        if (urlRes.status === 0 && urlRes.stdout) {
+          const parsed = parseGitRemoteUrl(urlRes.stdout);
+          if (parsed) return parsed;
+        }
+      }
+    }
+  } catch {}
+
+  // 4. Try package.json repository or name field
+  try {
+    const pkgPath = path.resolve(cwd, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+      const repoUrl = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
+      if (repoUrl) {
+        const parsed = parseGitRemoteUrl(repoUrl);
+        if (parsed) return parsed;
+      }
+      if (pkg.name) {
+        if (pkg.name.startsWith('@') && pkg.name.includes('/')) {
+          const [scope, pkgRepo] = pkg.name.slice(1).split('/');
+          return {
+            owner: scope,
+            repo: pkgRepo,
+            nameWithOwner: `${scope}/${pkgRepo}`,
+            url: `https://github.com/${scope}/${pkgRepo}`
+          };
+        }
+        return {
+          owner: '',
+          repo: pkg.name,
+          nameWithOwner: pkg.name,
+          url: ''
+        };
+      }
+    }
+  } catch {}
+
+  // 5. Try git rev-parse toplevel folder name
+  try {
+    const topRes = spawnSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd,
+      encoding: 'utf-8',
+      stdio: ['ignore', 'pipe', 'ignore']
+    });
+    if (topRes.status === 0 && topRes.stdout) {
+      const topDir = topRes.stdout.trim();
+      const repoName = path.basename(topDir);
+      if (repoName) {
+        return {
+          owner: '',
+          repo: repoName,
+          nameWithOwner: repoName,
+          url: ''
+        };
+      }
+    }
+  } catch {}
+
+  const fallback = path.basename(cwd) || 'Codebase';
+  return {
+    owner: '',
+    repo: fallback,
+    nameWithOwner: fallback,
+    url: ''
+  };
+};
+
+export const detectGitHubUser = (preferredUser) => {
+  if (preferredUser && typeof preferredUser === 'string') {
+    const trimmed = preferredUser.trim();
+    if (trimmed && trimmed !== 'Architect') return trimmed;
+  }
+
+  // 1. Try gh api if authenticated with valid token
+  try {
+    const res = spawnSync('gh', ['api', 'user', '-q', '.login'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    if (res.status === 0) {
+      const user = (res.stdout || '').trim();
+      if (user && /^[a-zA-Z0-9_\-]+$/.test(user)) return user;
+    }
+  } catch {}
+
+  // 2. Try gh auth status account name (persists in config even if token is temporarily expired)
+  try {
+    const statusRes = spawnSync('gh', ['auth', 'status'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+    const output = `${statusRes.stdout || ''} ${statusRes.stderr || ''}`.trim();
+    const match = output.match(/account\s+([a-zA-Z0-9_\-]+)/i) || output.match(/Logged in to [^\s]+ account ([a-zA-Z0-9_\-]+)/i);
+    if (match && match[1]) {
+      const user = match[1].trim();
+      if (user && user !== 'default') return user;
+    }
+  } catch {}
+
+  // 3. Try git config github.user
+  try {
+    const ghUser = spawnSync('git', ['config', 'github.user'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const u = (ghUser.stdout || '').trim();
+    if (u && /^[a-zA-Z0-9_\-]+$/.test(u)) return u;
+  } catch {}
+
+  // 4. Try git config user.name
+  try {
+    const gitRes = spawnSync('git', ['config', 'user.name'], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] });
+    const name = (gitRes.stdout || '').trim();
+    if (name && /^[a-zA-Z0-9_\-]+$/.test(name)) return name;
+  } catch {}
+
+  return 'Architect';
+};
+
+export const copyToClipboard = (text) => {
+  try {
+    if (process.platform === 'darwin') {
+      const res = spawnSync('pbcopy', [], { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
+      return res.status === 0;
+    }
+    if (process.platform === 'win32') {
+      const res = spawnSync('clip', [], { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
+      return res.status === 0;
+    }
+    // Linux: try wl-copy then xclip
+    const wl = spawnSync('which', ['wl-copy'], { stdio: 'ignore' });
+    if (wl.status === 0) {
+      const res = spawnSync('wl-copy', [], { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
+      if (res.status === 0) return true;
+    }
+    const xc = spawnSync('which', ['xclip'], { stdio: 'ignore' });
+    if (xc.status === 0) {
+      const res = spawnSync('xclip', ['-selection', 'clipboard'], { input: text, stdio: ['pipe', 'ignore', 'ignore'] });
+      if (res.status === 0) return true;
+    }
+  } catch {}
+  return false;
+};