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

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/reporter-utils.js

@@ -36,31 +36,22 @@ export const groupViolationsBySeverity = (violations) => {
 };
 
 export const getSeverityBadge = (severity) => {
-  switch (severity) {
-    case 'CRITICAL':
-      return `${RED}[CRITICAL]${RESET}`;
-    case 'HIGH':
-      return `${ORANGE}[HIGH]${RESET}`;
-    case 'MEDIUM':
-      return `${ORANGE}[MEDIUM]${RESET}`;
-    case 'LOW':
-      return `${YELLOW}[LOW]${RESET}`;
-    default:
-      return `[${severity}]`;
-  }
+  const SEVERITY_BADGES = {
+    CRITICAL: `${RED}[CRITICAL]${RESET}`,
+    HIGH: `${ORANGE}[HIGH]${RESET}`,
+    MEDIUM: `${ORANGE}[MEDIUM]${RESET}`,
+    LOW: `${YELLOW}[LOW]${RESET}`
+  };
+  return SEVERITY_BADGES[severity] || `[${severity}]`;
 };
 
 export const getStatusBadge = (status) => {
-  switch (status) {
-    case 'PASSED':
-      return `${GREEN}✔ PASS${RESET}`;
-    case 'WARN':
-      return `${YELLOW}⚠ WARN${RESET}`;
-    case 'FAILED':
-      return `${RED}✕ FAIL${RESET}`;
-    default:
-      return status;
-  }
+  const STATUS_BADGES = {
+    PASSED: `${GREEN}✔ PASS${RESET}`,
+    WARN: `${YELLOW}⚠ WARN${RESET}`,
+    FAILED: `${RED}✕ FAIL${RESET}`
+  };
+  return STATUS_BADGES[status] || status;
 };
 
 export const resolveIndividualPillarGrade = (pillarData) => {

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/rules-registry.js

@@ -36,6 +36,26 @@ export const RULE_REGISTRY = {
     severity: 'CRITICAL',
     directive: 'Extract hardcoded API keys and secrets into environment variables or secrets manager'
   },
+  SECURITY_REVERSE_TABNABBING: {
+    pillar: PILLARS.PILLAR_9,
+    severity: 'MEDIUM',
+    directive: 'Add rel="noopener noreferrer" to external links with target="_blank" to prevent tab hijacking'
+  },
+  SECURITY_JAVASCRIPT_URL: {
+    pillar: PILLARS.PILLAR_9,
+    severity: 'CRITICAL',
+    directive: 'Do not use javascript: pseudo-protocol in links or action attributes; use event handlers'
+  },
+  SECURITY_DYNAMIC_CODE_EXECUTION: {
+    pillar: PILLARS.PILLAR_9,
+    severity: 'CRITICAL',
+    directive: 'Avoid eval(), new Function(), and string-based setTimeout/setInterval code execution'
+  },
+  SECURITY_SENSITIVE_LOGGING: {
+    pillar: PILLARS.PILLAR_9,
+    severity: 'HIGH',
+    directive: 'Never log sensitive credentials, tokens, or passwords to console diagnostics'
+  },
 
   // Pillar 10: Testing Discipline
   TEST_FAKE_GREEN: {
@@ -86,6 +106,11 @@ export const RULE_REGISTRY = {
     severity: 'CRITICAL',
     directive: 'Extract display states into computed descriptor objects or early returns'
   },
+  CONTROL_FLOW_DISPATCH_SWITCH: {
+    pillar: PILLARS.PILLAR_2,
+    severity: 'MEDIUM',
+    directive: 'Replace repetitive dispatch switch with an O(1) keyed dictionary or method map (Directive 3.E)'
+  },
   HOOK_SATURATION: {
     pillar: PILLARS.PILLAR_3,
     severity: 'HIGH',

package/cli/audit/rules.spec.js

@@ -0,0 +1,205 @@
+import test from "node:test";
+import assert from "node:assert";
+import { auditCode } from "./rules.js";
+
+test("Audit Rules: flags repetitive dispatch switch statement as CONTROL_FLOW_DISPATCH_SWITCH", () => {
+  const code = `
+export const resolveColor = (type) => {
+  switch (type) {
+    case "primary":
+      return "blue";
+    case "secondary":
+      return "gray";
+    case "danger":
+      return "red";
+    case "warning":
+      return "yellow";
+    default:
+      return "white";
+  }
+};
+`;
+
+  const violations = auditCode(code, "src/utils/colors.js", "src/utils/colors.js");
+  const dispatchViolation = violations.find((v) => v.rule === "CONTROL_FLOW_DISPATCH_SWITCH");
+  assert.ok(dispatchViolation, "Expected CONTROL_FLOW_DISPATCH_SWITCH violation");
+  assert.strictEqual(dispatchViolation.severity, "MEDIUM");
+  assert.ok(dispatchViolation.hazard.includes("Dispatch switch smell detected"));
+});
+
+test("Audit Rules: does NOT flag non-dispatch complex switch statements", () => {
+  const code = `
+export const processOrder = (status, order) => {
+  switch (status) {
+    case "pending": {
+      validatePayment(order);
+      sendNotification(order.userId);
+      return queueForFulfillment(order);
+    }
+    case "completed": {
+      archiveOrder(order);
+      emitAnalytics("order_completed", order);
+      break;
+    }
+    default:
+      throw new Error("Invalid status");
+  }
+};
+`;
+
+  const violations = auditCode(code, "src/order.js", "src/order.js");
+  const dispatchViolation = violations.find((v) => v.rule === "CONTROL_FLOW_DISPATCH_SWITCH");
+  assert.strictEqual(dispatchViolation, undefined, "Complex switch should not be flagged as dispatch smell");
+});
+
+test("Audit Rules: clean keyed map implementation produces 0 violations", () => {
+  const code = `
+const COLOR_MAP = {
+  primary: "blue",
+  secondary: "gray",
+  danger: "red",
+  warning: "yellow"
+};
+
+export const resolveColor = (type) => {
+  return Object.prototype.hasOwnProperty.call(COLOR_MAP, type) ? COLOR_MAP[type] : "white";
+};
+`;
+
+  const violations = auditCode(code, "src/utils/colors.js", "src/utils/colors.js");
+  const dispatchViolation = violations.find((v) => v.rule === "CONTROL_FLOW_DISPATCH_SWITCH");
+  assert.strictEqual(dispatchViolation, undefined);
+});
+
+test("Audit Security: flags external link target=_blank missing rel=noopener noreferrer in JSX", () => {
+  const code = `
+export const ExternalLink = () => (
+  <a href="https://example.com" target="_blank">External</a>
+);
+`;
+  const violations = auditCode(code, "src/Link.tsx", "src/Link.tsx");
+  const violation = violations.find((v) => v.rule === "SECURITY_REVERSE_TABNABBING");
+  assert.ok(violation, "Expected SECURITY_REVERSE_TABNABBING violation in JSX");
+  assert.strictEqual(violation.severity, "MEDIUM");
+});
+
+test("Audit Security: passes external link with rel=noopener noreferrer in JSX", () => {
+  const code = `
+export const ExternalLink = () => (
+  <a href="https://example.com" target="_blank" rel="noopener noreferrer">External</a>
+);
+`;
+  const violations = auditCode(code, "src/Link.tsx", "src/Link.tsx");
+  const violation = violations.find((v) => v.rule === "SECURITY_REVERSE_TABNABBING");
+  assert.strictEqual(violation, undefined);
+});
+
+test("Audit Security: flags target=_blank missing rel in Vue template", () => {
+  const code = `
+<template>
+  <a href="https://example.com" target="_blank">External</a>
+</template>
+`;
+  const violations = auditCode(code, "src/Link.vue", "src/Link.vue");
+  const violation = violations.find((v) => v.rule === "SECURITY_REVERSE_TABNABBING");
+  assert.ok(violation, "Expected SECURITY_REVERSE_TABNABBING in Vue template");
+});
+
+test("Audit Security: flags javascript: pseudo-protocol in JSX href", () => {
+  const code = `
+export const BadLink = () => (
+  <a href="javascript:alert(1)">Click Me</a>
+);
+`;
+  const violations = auditCode(code, "src/BadLink.tsx", "src/BadLink.tsx");
+  const violation = violations.find((v) => v.rule === "SECURITY_JAVASCRIPT_URL");
+  assert.ok(violation, "Expected SECURITY_JAVASCRIPT_URL violation");
+  assert.strictEqual(violation.severity, "CRITICAL");
+});
+
+test("Audit Security: flags javascript: in template attributes", () => {
+  const code = `
+<template>
+  <form action="javascript:void(0)">
+    <button type="submit">Submit</button>
+  </form>
+</template>
+`;
+  const violations = auditCode(code, "src/Form.vue", "src/Form.vue");
+  const violation = violations.find((v) => v.rule === "SECURITY_JAVASCRIPT_URL");
+  assert.ok(violation, "Expected SECURITY_JAVASCRIPT_URL in template");
+});
+
+test("Audit Security: flags dynamic code execution via eval()", () => {
+  const code = `
+export const runDynamic = (str: string) => {
+  return eval(str);
+};
+`;
+  const violations = auditCode(code, "src/eval.ts", "src/eval.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.ok(violation, "Expected SECURITY_DYNAMIC_CODE_EXECUTION for eval()");
+  assert.strictEqual(violation.severity, "CRITICAL");
+});
+
+test("Audit Security: flags dynamic code execution via new Function()", () => {
+  const code = `
+export const buildFn = (code: string) => {
+  return new Function("return " + code);
+};
+`;
+  const violations = auditCode(code, "src/fn.ts", "src/fn.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.ok(violation, "Expected SECURITY_DYNAMIC_CODE_EXECUTION for new Function()");
+  assert.strictEqual(violation.severity, "CRITICAL");
+});
+
+test("Audit Security: flags string-based execution in setTimeout", () => {
+  const code = `
+export const scheduleCode = () => {
+  setTimeout("alert('hello')", 1000);
+};
+`;
+  const violations = auditCode(code, "src/timer.ts", "src/timer.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.ok(violation, "Expected SECURITY_DYNAMIC_CODE_EXECUTION for string setTimeout");
+});
+
+test("Audit Security: does NOT flag function callback setTimeout", () => {
+  const code = `
+export const scheduleCode = () => {
+  const timer = setTimeout(() => {
+    // legitimate callback
+  }, 1000);
+  return () => clearTimeout(timer);
+};
+`;
+  const violations = auditCode(code, "src/timer.ts", "src/timer.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_DYNAMIC_CODE_EXECUTION");
+  assert.strictEqual(violation, undefined);
+});
+
+test("Audit Security: flags sensitive variable logging in console", () => {
+  const code = `
+export const debugAuth = (authToken: string, user: any) => {
+  console.log("Authenticated with token:", authToken);
+  console.info("User details:", { password: user.password });
+};
+`;
+  const violations = auditCode(code, "src/auth.ts", "src/auth.ts");
+  const loggingViolations = violations.filter((v) => v.rule === "SECURITY_SENSITIVE_LOGGING");
+  assert.strictEqual(loggingViolations.length >= 1, true, "Expected SECURITY_SENSITIVE_LOGGING violation");
+  assert.strictEqual(loggingViolations[0].severity, "HIGH");
+});
+
+test("Audit Security: does NOT flag normal non-sensitive console logging", () => {
+  const code = `
+export const debugCount = (itemCount: number) => {
+  console.log("Items rendered:", itemCount);
+};
+`;
+  const violations = auditCode(code, "src/items.ts", "src/items.ts");
+  const violation = violations.find((v) => v.rule === "SECURITY_SENSITIVE_LOGGING");
+  assert.strictEqual(violation, undefined);
+});
+

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/build.d.ts

@@ -2,7 +2,8 @@ import type { BuildAuditReport, BuildOptions } from './build/types.js';
 
 export function runBuildAudit(
   rawArgs?: readonly string[],
-  isCli?: boolean
+  isCli?: boolean,
+  options?: { readonly print?: boolean; readonly silent?: boolean }
 ): Promise<BuildAuditReport>;
 
 export {

package/cli/build.js

@@ -20,16 +20,17 @@ const parseCommandFromArgs = (args) => {
   return candidate ? candidate.trim() : null;
 };
 
-export const runBuildAudit = async (rawArgs = [], isCli = false) => {
+export const runBuildAudit = async (rawArgs = [], isCli = false, options = {}) => {
   const isJson = rawArgs.includes('--json');
-  const isSilent = rawArgs.includes('--silent');
+  const isSilent = rawArgs.includes('--silent') || options.silent === true;
   const isRaw = rawArgs.includes('--raw');
   const isSummary = rawArgs.includes('--summary');
+  const shouldPrint = options.print !== false;
 
   const customCommand = parseCommandFromArgs(rawArgs);
   const command = detectProjectBuildCommand(customCommand, process.cwd());
 
-  const shouldPrintStart = !isJson && !isSilent && !isRaw;
+  const shouldPrintStart = shouldPrint && !isJson && !isSilent && !isRaw;
   if (shouldPrintStart) {
     process.stdout.write(`${ANSI.CYAN}Auditing build:${ANSI.RESET} ${ANSI.DIM}${command}${ANSI.RESET}\n`);
   }
@@ -39,13 +40,15 @@ export const runBuildAudit = async (rawArgs = [], isCli = false) => {
   const report = groupBuildDiagnostics(rawDiagnostics, executionResult);
 
   if (isJson) {
-    process.stdout.write(formatJsonBuildReport(report) + '\n');
+    if (shouldPrint) {
+      process.stdout.write(formatJsonBuildReport(report) + '\n');
+    }
     if (isCli) process.exit(report.exitCode);
     return report;
   }
 
   const terminalOutput = formatTerminalBuildReport(report, { silent: isSilent, summary: isSummary });
-  if (terminalOutput) {
+  if (terminalOutput && shouldPrint) {
     process.stdout.write(terminalOutput);
   }
 

package/cli/columnar.d.ts

@@ -0,0 +1,14 @@
+export interface ColumnarData<T = any> {
+  readonly cols: readonly string[];
+  readonly rows: readonly T[][];
+}
+
+export declare function toColumnar<T extends Record<string, any>>(
+  items?: readonly T[],
+  cols?: readonly string[],
+  accessors?: Record<string, (item: T) => any>
+): ColumnarData;
+
+export declare function fromColumnar<T extends Record<string, any>>(
+  columnar?: ColumnarData
+): readonly T[];

package/cli/columnar.js

@@ -0,0 +1,52 @@
+/**
+ * Chemical X Protocol: Columnar Serialization Utility
+ * Converts object collections into compact single-schema matrices
+ * to eliminate repeated dictionary keys and slash token consumption.
+ */
+
+/**
+ * Transforms an array of objects into a single-schema columnar structure.
+ *
+ * @param {readonly object[]} items Array of record objects.
+ * @param {readonly string[]} cols Column names to extract.
+ * @param {Record<string, (item: any) => any>} [accessors={}] Optional field transformers.
+ * @returns {{ cols: readonly string[], rows: readonly any[][] }}
+ */
+export const toColumnar = (items = [], cols = [], accessors = {}) => {
+  if (!items || items.length === 0) {
+    return { cols, rows: [] };
+  }
+
+  const rows = items.map((item) => {
+    return cols.map((col) => {
+      const accessor = accessors[col];
+      if (typeof accessor === 'function') {
+        return accessor(item);
+      }
+      return item[col];
+    });
+  });
+
+  return { cols, rows };
+};
+
+/**
+ * Reconstructs an array of objects from a columnar structure.
+ *
+ * @param {{ cols: readonly string[], rows: readonly any[][] }} columnar
+ * @returns {readonly Record<string, any>[]}
+ */
+export const fromColumnar = (columnar) => {
+  if (!columnar || !columnar.cols || !columnar.rows) {
+    return [];
+  }
+
+  const { cols, rows } = columnar;
+  return rows.map((row) => {
+    const obj = {};
+    cols.forEach((col, idx) => {
+      obj[col] = row[idx];
+    });
+    return obj;
+  });
+};

package/cli/columnar.spec.js

@@ -0,0 +1,49 @@
+import test from 'node:test';
+import assert from 'node:assert';
+import { toColumnar, fromColumnar } from './columnar.js';
+
+test('toColumnar: converts array of objects into cols and rows', () => {
+  const items = [
+    { file: 'src/a.ts', tier: 'atom', lines: 40 },
+    { file: 'src/b.ts', tier: 'molecule', lines: 75 }
+  ];
+
+  const result = toColumnar(items, ['file', 'tier', 'lines']);
+
+  assert.deepStrictEqual(result.cols, ['file', 'tier', 'lines']);
+  assert.strictEqual(result.rows.length, 2);
+  assert.deepStrictEqual(result.rows[0], ['src/a.ts', 'atom', 40]);
+  assert.deepStrictEqual(result.rows[1], ['src/b.ts', 'molecule', 75]);
+});
+
+test('toColumnar: handles empty or missing arrays cleanly', () => {
+  assert.deepStrictEqual(toColumnar([], ['file', 'tier']), { cols: ['file', 'tier'], rows: [] });
+  assert.deepStrictEqual(toColumnar(null, ['file']), { cols: ['file'], rows: [] });
+});
+
+test('toColumnar: supports custom accessor functions for nested fields', () => {
+  const items = [
+    { file: 'src/card.vue', symbols: [{ name: 'UserCard' }, { name: 'CardBadge' }] }
+  ];
+
+  const result = toColumnar(items, ['file', 'symbols'], {
+    symbols: (item) => item.symbols.map((s) => s.name)
+  });
+
+  assert.deepStrictEqual(result.rows[0], ['src/card.vue', ['UserCard', 'CardBadge']]);
+});
+
+test('fromColumnar: reconstructs array of objects from columnar data', () => {
+  const columnar = {
+    cols: ['file', 'tier', 'lines'],
+    rows: [
+      ['src/a.ts', 'atom', 40],
+      ['src/b.ts', 'molecule', 75]
+    ]
+  };
+
+  const items = fromColumnar(columnar);
+  assert.strictEqual(items.length, 2);
+  assert.deepStrictEqual(items[0], { file: 'src/a.ts', tier: 'atom', lines: 40 });
+  assert.deepStrictEqual(items[1], { file: 'src/b.ts', tier: 'molecule', lines: 75 });
+});