@stratixlabs/core 1.7.1

package/scripts/generate-dts-from-tokens.js

@@ -0,0 +1,77 @@
+const fs = require('fs');
+const path = require('path');
+
+function isLeaf(node) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) return false;
+  const keys = Object.keys(node);
+  return keys.includes('value') && keys.includes('type') && keys.includes('originalVariable');
+}
+
+function buildType(node, indentLevel) {
+  if (isLeaf(node)) {
+    return 'TokenLeaf';
+  }
+  if (!node || typeof node !== 'object') {
+    return 'TokenLeaf';
+  }
+  const keys = Object.keys(node);
+  const indent = '  '.repeat(indentLevel);
+  const innerIndent = '  '.repeat(indentLevel + 1);
+  const lines = ['{'];
+  for (const key of keys) {
+    const childType = buildType(node[key], indentLevel + 1);
+    lines.push(`${innerIndent}"${key}": ${childType};`);
+  }
+  lines.push(`${indent}}`);
+  return lines.join('\n');
+}
+
+function main() {
+  const cwd = process.cwd();
+  const tokensPath = path.join(cwd, 'tokens.json');
+
+  if (!fs.existsSync(tokensPath)) {
+    console.error('❌ tokens.json not found. Run "npm run build:tokens" first.');
+    process.exit(1);
+  }
+
+  const raw = fs.readFileSync(tokensPath, 'utf8');
+  const json = JSON.parse(raw);
+
+  const graphType = buildType(json, 0);
+
+  const lines = [];
+  lines.push("export type TokenType =");
+  lines.push("  | 'color'");
+  lines.push("  | 'spacing'");
+  lines.push("  | 'typography'");
+  lines.push("  | 'radius'");
+  lines.push("  | 'border'");
+  lines.push("  | 'elevation'");
+  lines.push("  | 'motion'");
+  lines.push("  | 'opacity'");
+  lines.push("  | 'breakpoint'");
+  lines.push("  | 'semantic'");
+  lines.push("  | 'unknown';");
+  lines.push('');
+  lines.push('export interface TokenLeaf {');
+  lines.push('  value: string;');
+  lines.push('  type: TokenType;');
+  lines.push('  originalVariable: string;');
+  lines.push('}');
+  lines.push('');
+  lines.push('export type Tokens = ' + graphType + ';');
+  lines.push('');
+  lines.push('declare const tokens: Tokens;');
+  lines.push('');
+  lines.push('export default tokens;');
+  lines.push('');
+
+  const outputPath = path.join(cwd, 'substrata.d.ts');
+  fs.writeFileSync(outputPath, lines.join('\n'));
+
+  console.log(`✅ Generated ${outputPath} from ${tokensPath}`);
+}
+
+main();
+

package/scripts/generate-tokens.js

@@ -0,0 +1,138 @@
+const fs = require('fs');
+const path = require('path');
+
+function ensurePathWithinRoot(resolvedPath, rootDir) {
+    const resolved = path.resolve(resolvedPath);
+    const root = path.resolve(rootDir);
+    const normalize = s => s.replace(/\\/g, '/').toLowerCase();
+    const resolvedNorm = normalize(resolved);
+    const rootNorm = normalize(root);
+    if (resolvedNorm !== rootNorm && !resolvedNorm.startsWith(rootNorm + '/')) {
+        throw new Error(`Configured path ${resolved} is outside of project root ${root}`);
+    }
+}
+
+function setDeep(obj, pathParts, value) {
+    let current = obj;
+    for (let i = 0; i < pathParts.length; i++) {
+        const part = pathParts[i];
+        if (i === pathParts.length - 1) {
+            current[part] = value;
+        } else {
+            current[part] = current[part] || {};
+            current = current[part];
+        }
+    }
+}
+
+function inferTypeFromFilename(filename) {
+    const name = filename.toLowerCase();
+    if (name.includes('color')) return 'color';
+    if (name.includes('spacing')) return 'spacing';
+    if (name.includes('typography')) return 'typography';
+    if (name.includes('radius')) return 'radius';
+    if (name.includes('border')) return 'border';
+    if (name.includes('elevation') || name.includes('shadow')) return 'elevation';
+    if (name.includes('motion')) return 'motion';
+    if (name.includes('opacity')) return 'opacity';
+    if (name.includes('breakpoint')) return 'breakpoint';
+    if (name.includes('semantic')) return 'semantic';
+    return 'unknown';
+}
+
+function parseCssVariables(cssContent, fileType) {
+    const tokens = {};
+    const lines = cssContent.split('\n');
+
+    for (const line of lines) {
+        const match = line.match(/--([\w-]+):\s*([^;]+);/);
+        if (match) {
+            const variableName = match[1]; // e.g. "color-neutral-100"
+            const value = match[2].trim(); // e.g. "#ffffff"
+
+            const parts = variableName.split('-');
+            setDeep(tokens, parts, {
+                value: value,
+                type: fileType,
+                originalVariable: `--${variableName}`
+            });
+        }
+    }
+    return tokens;
+}
+
+function deepMerge(target, source) {
+    for (const key of Object.keys(source)) {
+        const srcVal = source[key];
+        const tgtVal = target[key];
+        if (srcVal && typeof srcVal === 'object' && !Array.isArray(srcVal)) {
+            if (!tgtVal || typeof tgtVal !== 'object' || Array.isArray(tgtVal)) {
+                target[key] = {};
+            }
+            deepMerge(target[key], srcVal);
+        } else {
+            target[key] = srcVal;
+        }
+    }
+    return target;
+}
+
+async function generateTokens() {
+    try {
+        let tokensDir = path.join(__dirname, '../src/tokens');
+        let outputFile = path.join(__dirname, '../tokens.json');
+
+        const rootDir = process.cwd();
+        const configPath = path.join(rootDir, 'substrata.config.js');
+        if (fs.existsSync(configPath)) {
+            console.log('Found substrata.config.js');
+            const config = require(configPath);
+            if (config.tokens) {
+                const resolvedTokensDir = path.resolve(rootDir, config.tokens);
+                ensurePathWithinRoot(resolvedTokensDir, rootDir);
+                tokensDir = resolvedTokensDir;
+            }
+            if (config.output) {
+                const resolvedOutputFile = path.resolve(rootDir, config.output);
+                ensurePathWithinRoot(resolvedOutputFile, rootDir);
+                outputFile = resolvedOutputFile;
+            }
+        }
+
+        if (!fs.existsSync(tokensDir)) {
+            console.error(`❌ Tokens directory not found: ${tokensDir}`);
+            process.exit(1);
+        }
+
+        const files = fs.readdirSync(tokensDir);
+        const allTokens = {};
+
+        console.log(`Scanning ${tokensDir}...`);
+
+        for (const file of files) {
+            if (file.endsWith('.css')) {
+                const content = fs.readFileSync(path.join(tokensDir, file), 'utf8');
+                const fileType = inferTypeFromFilename(file);
+                const fileTokens = parseCssVariables(content, fileType);
+
+                deepMerge(allTokens, fileTokens);
+            }
+        }
+
+        const outputContent = JSON.stringify(allTokens, null, 2);
+        // Ensure output directory exists
+        const outputDir = path.dirname(outputFile);
+        if (!fs.existsSync(outputDir)) {
+            fs.mkdirSync(outputDir, { recursive: true });
+        }
+
+        fs.writeFileSync(outputFile, outputContent);
+
+        console.log(`✅ Generated tokens.json at ${outputFile}`);
+    } catch (error) {
+        console.error('❌ Error generating tokens:', error);
+        process.exit(1);
+    }
+}
+
+generateTokens();

package/scripts/lint-code.js

@@ -0,0 +1,186 @@
+const fs = require('fs');
+const path = require('path');
+
+const TARGET_DIRS = [
+  path.join(__dirname, '../src/components'),
+  path.join(__dirname, '../src/consumption'),
+];
+
+const DECL_REGEX = /^\s*([a-zA-Z-]+)\s*:\s*([^;{]+);/;
+const VAR_REGEX = /var\(\s*(--[\w-]+)/g;
+
+const COLOR_PROPS = new Set([
+  'color',
+  'background',
+  'background-color',
+  'border-color',
+  'border-top-color',
+  'border-right-color',
+  'border-bottom-color',
+  'border-left-color',
+  'outline-color',
+  'fill',
+  'stroke',
+]);
+
+const SPACING_PROPS = new Set([
+  'margin',
+  'margin-top',
+  'margin-right',
+  'margin-bottom',
+  'margin-left',
+  'padding',
+  'padding-top',
+  'padding-right',
+  'padding-bottom',
+  'padding-left',
+  'gap',
+  'row-gap',
+  'column-gap',
+  'top',
+  'right',
+  'bottom',
+  'left',
+  'inset',
+]);
+
+const TYPOGRAPHY_PROPS = new Set([
+  'font-size',
+  'line-height',
+  'font-weight',
+  'letter-spacing',
+  'font-family',
+]);
+
+const RADIUS_PROPS = new Set([
+  'border-radius',
+  'border-top-left-radius',
+  'border-top-right-radius',
+  'border-bottom-right-radius',
+  'border-bottom-left-radius',
+]);
+
+const ELEVATION_PROPS = new Set(['box-shadow']);
+const OPACITY_PROPS = new Set(['opacity']);
+const MOTION_PROPS = new Set(['transition-duration', 'animation-duration']);
+
+const CODE_FILE_REGEX = /\.(css|scss|js|jsx|ts|tsx)$/;
+
+function isLeaf(node) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) return false;
+  const keys = Object.keys(node);
+  return keys.includes('value') && keys.includes('type') && keys.includes('originalVariable');
+}
+
+function collectTokenTypes(obj, map) {
+  if (isLeaf(obj)) {
+    map[obj.originalVariable] = obj.type;
+    return;
+  }
+  if (!obj || typeof obj !== 'object') return;
+  for (const key of Object.keys(obj)) {
+    collectTokenTypes(obj[key], map);
+  }
+}
+
+function loadTokenTypeMap() {
+  const tokensPath = path.join(process.cwd(), 'tokens.json');
+  if (!fs.existsSync(tokensPath)) {
+    console.error('❌ tokens.json not found. Run "npm run build:tokens" first.');
+    process.exit(1);
+  }
+  const raw = fs.readFileSync(tokensPath, 'utf8');
+  const json = JSON.parse(raw);
+  const map = {};
+  collectTokenTypes(json, map);
+  return map;
+}
+
+function getPropertyCategory(prop) {
+  if (COLOR_PROPS.has(prop)) return 'color';
+  if (SPACING_PROPS.has(prop)) return 'spacing';
+  if (TYPOGRAPHY_PROPS.has(prop)) return 'typography';
+  if (RADIUS_PROPS.has(prop)) return 'radius';
+  if (ELEVATION_PROPS.has(prop)) return 'elevation';
+  if (OPACITY_PROPS.has(prop)) return 'opacity';
+  if (MOTION_PROPS.has(prop)) return 'motion';
+  return null;
+}
+
+function isTypeAllowedForCategory(type, category) {
+  if (type === 'unknown') return true;
+  if (category === 'color') {
+    return type === 'color' || type === 'semantic';
+  }
+  if (category === 'spacing') {
+    return type === 'spacing';
+  }
+  if (category === 'typography') {
+    return type === 'typography';
+  }
+  if (category === 'radius') {
+    return type === 'radius';
+  }
+  if (category === 'elevation') {
+    return type === 'elevation';
+  }
+  if (category === 'opacity') {
+    return type === 'opacity';
+  }
+  if (category === 'motion') {
+    return type === 'motion';
+  }
+  return true;
+}
+
+function scanFile(filePath, tokenTypes, errors) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+  lines.forEach((line, idx) => {
+    const match = DECL_REGEX.exec(line);
+    if (!match) return;
+    const prop = match[1].toLowerCase();
+    const category = getPropertyCategory(prop);
+    if (!category) return;
+    let m;
+    VAR_REGEX.lastIndex = 0;
+    while ((m = VAR_REGEX.exec(line)) !== null) {
+      const variable = m[1];
+      const type = tokenTypes[variable];
+      const location = `${filePath}:${idx + 1}`;
+      if (!type) continue;
+      if (!isTypeAllowedForCategory(type, category)) {
+        errors.push(
+          `${location} uses token ${variable} of type ${type} in property ${prop} (category ${category})`
+        );
+      }
+    }
+  });
+}
+
+function main() {
+  const tokenTypes = loadTokenTypeMap();
+  const errors = [];
+
+  for (const dir of TARGET_DIRS) {
+    if (!fs.existsSync(dir)) continue;
+    const entries = fs.readdirSync(dir);
+    for (const entry of entries) {
+      const full = path.join(dir, entry);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) continue;
+      if (!CODE_FILE_REGEX.test(entry)) continue;
+      scanFile(full, tokenTypes, errors);
+    }
+  }
+
+  if (errors.length) {
+    console.error('❌ Token-aware code lint failed:');
+    for (const e of errors) console.error(' -', e);
+    process.exit(1);
+  } else {
+    console.log('✅ Token-aware code lint passed');
+  }
+}
+
+main();

package/scripts/lint-hardcoded.js

@@ -0,0 +1,49 @@
+const fs = require('fs');
+const path = require('path');
+
+const TARGET_DIRS = [
+  path.join(__dirname, '../src/components'),
+  path.join(__dirname, '../src/consumption'),
+];
+
+const HEX_REGEX = /#[0-9a-fA-F]{3,6}/;
+
+function scanFile(filePath, errors) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const contentWithoutBlockComments = content.replace(/\/\*[\s\S]*?\*\//g, match =>
+    match.replace(/[^\n]/g, ' ')
+  );
+  const lines = contentWithoutBlockComments.split('\n');
+  lines.forEach((line, idx) => {
+    const codePart = line.split('//')[0];
+    if (HEX_REGEX.test(codePart) && !codePart.includes('var(')) {
+      errors.push(`${filePath}:${idx + 1} contains hardcoded hex color`);
+    }
+  });
+}
+
+function main() {
+  const errors = [];
+  for (const dir of TARGET_DIRS) {
+    if (!fs.existsSync(dir)) continue;
+    const entries = fs.readdirSync(dir);
+    for (const entry of entries) {
+      const full = path.join(dir, entry);
+      const stat = fs.statSync(full);
+      if (stat.isDirectory()) continue;
+      if (/\.(css|scss)$/.test(entry)) {
+        scanFile(full, errors);
+      }
+    }
+  }
+
+  if (errors.length) {
+    console.error('❌ Hardcoded color values detected:');
+    for (const e of errors) console.error(' -', e);
+    process.exit(1);
+  } else {
+    console.log('✅ No hardcoded hex color values found in target directories');
+  }
+}
+
+main();

package/scripts/tokens-to-css.js

@@ -0,0 +1,145 @@
+const fs = require('fs');
+const path = require('path');
+
+function ensurePathWithinRoot(resolvedPath, rootDir) {
+    const resolved = path.resolve(resolvedPath);
+    const root = path.resolve(rootDir);
+    const normalize = s => s.replace(/\\/g, '/').toLowerCase();
+    const resolvedNorm = normalize(resolved);
+    const rootNorm = normalize(root);
+    if (resolvedNorm !== rootNorm && !resolvedNorm.startsWith(rootNorm + '/')) {
+        throw new Error(`Configured path ${resolved} is outside of project root ${root}`);
+    }
+}
+
+function resolvePaths() {
+    let tokensDir = path.join(__dirname, '../src/tokens');
+    let tokensJsonPath = path.join(__dirname, '../tokens.json');
+
+    const rootDir = process.cwd();
+    const configPath = path.join(rootDir, 'substrata.config.js');
+    if (fs.existsSync(configPath)) {
+        const config = require(configPath);
+        if (config.tokens) {
+            const resolvedTokensDir = path.resolve(rootDir, config.tokens);
+            ensurePathWithinRoot(resolvedTokensDir, rootDir);
+            tokensDir = resolvedTokensDir;
+        }
+        if (config.output) {
+            const resolvedTokensJsonPath = path.resolve(rootDir, config.output);
+            ensurePathWithinRoot(resolvedTokensJsonPath, rootDir);
+            tokensJsonPath = resolvedTokensJsonPath;
+        }
+    }
+
+    return { tokensDir, tokensJsonPath };
+}
+
+function flattenTokens(obj, prefix, result) {
+    if (!obj || typeof obj !== 'object') {
+        return result;
+    }
+
+    const keys = Object.keys(obj);
+    for (const key of keys) {
+        const value = obj[key];
+        const nextPath = prefix ? `${prefix}.${key}` : key;
+
+        if (value && typeof value === 'object' && !Array.isArray(value)) {
+            if (
+                Object.prototype.hasOwnProperty.call(value, 'value') &&
+                Object.prototype.hasOwnProperty.call(value, 'type') &&
+                Object.prototype.hasOwnProperty.call(value, 'originalVariable')
+            ) {
+                result.push({
+                    path: nextPath,
+                    type: value.type,
+                    name: value.originalVariable,
+                    value: value.value
+                });
+            } else {
+                flattenTokens(value, nextPath, result);
+            }
+        }
+    }
+
+    return result;
+}
+
+const FILE_BY_TYPE = {
+    breakpoint: 'breakpoints.css',
+    color: 'colors.css',
+    semantic: 'semantic-aliases.css',
+    spacing: 'spacing.css',
+    elevation: 'elevation.css',
+    motion: 'motion.css',
+    opacity: 'opacity.css',
+    radius: 'radius-and-borders.css',
+    typography: 'typography.css'
+};
+
+function buildCssFiles(tokens, tokensDir) {
+    const byFile = new Map();
+
+    for (const entry of tokens) {
+        const fileName = FILE_BY_TYPE[entry.type];
+        if (!fileName) continue;
+        if (!byFile.has(fileName)) {
+            byFile.set(fileName, []);
+        }
+        byFile.get(fileName).push({
+            name: entry.name,
+            value: entry.value
+        });
+    }
+
+    if (!fs.existsSync(tokensDir)) {
+        fs.mkdirSync(tokensDir, { recursive: true });
+    }
+
+    for (const [fileName, vars] of byFile) {
+        vars.sort((a, b) => a.name.localeCompare(b.name));
+
+        const lines = [];
+        lines.push(':root {');
+        lines.push('');
+        for (const v of vars) {
+            lines.push(`  ${v.name}: ${v.value};`);
+        }
+        lines.push('');
+        lines.push('}');
+
+        const content = lines.join('\n');
+        const filePath = path.join(tokensDir, fileName);
+        fs.writeFileSync(filePath, content);
+        console.log(`✅ Wrote ${filePath} with ${vars.length} variables.`);
+    }
+}
+
+function main() {
+    const { tokensDir, tokensJsonPath } = resolvePaths();
+
+    if (!fs.existsSync(tokensJsonPath)) {
+        console.error(`❌ tokens.json not found at: ${tokensJsonPath}`);
+        process.exit(1);
+    }
+
+    let tokens;
+    try {
+        tokens = JSON.parse(fs.readFileSync(tokensJsonPath, 'utf8'));
+    } catch (error) {
+        console.error('❌ Could not parse tokens.json');
+        console.error(error);
+        process.exit(1);
+    }
+
+    const flat = flattenTokens(tokens, '', []);
+    if (flat.length === 0) {
+        console.log('ℹ️ No tokens with originalVariable found in tokens.json.');
+        return;
+    }
+
+    buildCssFiles(flat, tokensDir);
+}
+
+main();

package/scripts/validate-tokens.js

@@ -0,0 +1,113 @@
+const fs = require('fs');
+const path = require('path');
+
+const AJV_AVAILABLE = (() => {
+  try {
+    require.resolve('ajv');
+    return true;
+  } catch (e) {
+    return false;
+  }
+})();
+
+const ORIGINAL_VARIABLE_REGEX = /^--[\w-]+$/;
+
+function isLeaf(node) {
+  if (!node || typeof node !== 'object' || Array.isArray(node)) return false;
+  const keys = Object.keys(node);
+  return keys.includes('value') && keys.includes('type') && keys.includes('originalVariable');
+}
+
+function validateLeaf(node, pathStr, errors) {
+  if (typeof node.value !== 'string' || node.value.length === 0) {
+    errors.push(`Invalid value at ${pathStr}`);
+  }
+  if (typeof node.type !== 'string' || node.type.length === 0) {
+    errors.push(`Invalid or missing type at ${pathStr}`);
+  }
+  if (typeof node.originalVariable !== 'string' || !ORIGINAL_VARIABLE_REGEX.test(node.originalVariable)) {
+    errors.push(
+      `Invalid originalVariable "${node.originalVariable}" at ${pathStr}. Expected format: --kebab-case`
+    );
+  }
+}
+
+function traverse(obj, pathParts, errors, stats) {
+  if (isLeaf(obj)) {
+    const pathStr = pathParts.join('.');
+    stats.leaves += 1;
+    validateLeaf(obj, pathStr, errors);
+    return;
+  }
+  if (!obj || typeof obj !== 'object') return;
+  for (const key of Object.keys(obj)) {
+    traverse(obj[key], [...pathParts, key], errors, stats);
+  }
+}
+
+function runSchemaValidation(tokens, cwd, errors) {
+  if (!AJV_AVAILABLE) {
+    console.warn('⚠️  AJV not installed — skipping JSON Schema validation.');
+    return;
+  }
+
+  try {
+    const Ajv = require('ajv');
+    const schemaPath = path.join(cwd, 'tokens.schema.json');
+    if (!fs.existsSync(schemaPath)) {
+      console.warn('⚠️  tokens.schema.json not found — skipping JSON Schema validation.');
+      return;
+    }
+    const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+    const ajv = new Ajv({ allErrors: true });
+    const validate = ajv.compile(schema);
+    const valid = validate(tokens);
+    if (!valid) {
+      errors.push('Schema validation failed:');
+      for (const e of validate.errors || []) {
+        errors.push(`  ${e.instancePath || '/'} ${e.message}`);
+      }
+    }
+  } catch (e) {
+    errors.push(`Error running schema validation: ${e.message}`);
+  }
+}
+
+function main() {
+  try {
+    const cwd = process.cwd();
+    const tokensPath = path.join(cwd, 'tokens.json');
+    if (!fs.existsSync(tokensPath)) {
+      console.error('❌ tokens.json not found. Run "npm run build:tokens" first.');
+      process.exit(1);
+    }
+    const content = fs.readFileSync(tokensPath, 'utf8');
+    const tokens = JSON.parse(content);
+
+    const errors = [];
+    // 1) Schema validation (AJV) if available
+    runSchemaValidation(tokens, cwd, errors);
+
+    // 2) Traditional traversal to ensure leaf count and give friendly messages
+    const stats = { leaves: 0 };
+    traverse(tokens, [], errors, stats);
+
+    if (stats.leaves === 0) {
+      console.error('❌ No token leaves found in tokens.json');
+      process.exit(1);
+    }
+
+    if (errors.length) {
+      console.error(`❌ Validation failed with ${errors.length} error(s):`);
+      for (const e of errors) console.error(' -', e);
+      process.exit(1);
+    }
+
+    console.log(`✅ tokens.json validated successfully (${stats.leaves} tokens)`);
+  } catch (error) {
+    console.error('❌ Error validating tokens:', error);
+    process.exit(1);
+  }
+}
+
+main();