@finggujadhav/compiler 0.9.0

package/cli.js

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+/**
+ * FingguFlux CLI
+ * Phase 6A: Compiler CLI Foundation
+ */
+import fs from 'fs';
+import path from 'path';
+import { scanFiles, getProjectFiles } from './scanner.js';
+import { CompilerEngine } from './engine.js';
+
+// Basic named argument parser
+const args = process.argv.slice(2);
+const getArg = (flag) => {
+    const idx = args.indexOf(flag);
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : null;
+};
+
+const mode = getArg('--mode') || 'dev';
+const inputDir = getArg('--input') || './';
+const outputDir = getArg('--output') || './dist';
+
+async function runBuild() {
+    console.log(`\n🚀 FingguFlux Compiler [Mode: ${mode.toUpperCase()}]`);
+
+    // 1. Scan for used classes
+    console.log(`🔍 Scanning files in ${inputDir}...`);
+    const files = getProjectFiles(path.resolve(inputDir));
+    const usedClasses = scanFiles(files);
+    console.log(`✅ Found ${usedClasses.length} used FingguFlux classes.`);
+
+    // 2. Initialize Engine
+    const engine = new CompilerEngine({ mode });
+    engine.setUsedClasses(usedClasses);
+
+    // 3. Collect CSS source files
+    let combinedCSS = '';
+    const possiblePaths = [
+        path.resolve('./node_modules/@finggujadhav/core'),
+        path.resolve('./packages/core'),
+        path.resolve('../../packages/core')
+    ];
+
+    let corePath = possiblePaths.find(p => fs.existsSync(p));
+    if (!corePath) throw new Error('Could not find @finggujadhav/core CSS sources.');
+
+    const collectCSS = (dir) => {
+        if (!fs.existsSync(dir)) return;
+        const list = fs.readdirSync(dir);
+        list.forEach(file => {
+            const fullPath = path.join(dir, file);
+            if (fs.statSync(fullPath).isDirectory()) {
+                if (file === 'components') collectCSS(fullPath);
+            } else if (path.extname(file) === '.css' && file !== 'index.css') {
+                combinedCSS += fs.readFileSync(fullPath, 'utf8') + '\n';
+            }
+        });
+    };
+
+    collectCSS(corePath);
+
+    // 4. Process CSS
+    console.log(`🛠️ Processing CSS and applying tree-shaking...`);
+    const finalCSS = engine.processCSS(combinedCSS);
+    const mapping = engine.getMapping();
+
+    // 5. Output
+    if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    const cssPath = path.join(outputDir, 'finggu.css');
+    const mappingPath = path.join(outputDir, 'mapping.json');
+
+    fs.writeFileSync(cssPath, finalCSS);
+    fs.writeFileSync(mappingPath, JSON.stringify(mapping, null, 2));
+
+    console.log(`\n📦 Build Complete!`);
+    console.log(`- CSS: ${cssPath} (${Buffer.byteLength(finalCSS)} bytes)`);
+    console.log(`- Mapping: ${mappingPath}`);
+    console.log(`- Mode: ${mode}`);
+}
+
+runBuild().catch(err => {
+    console.error('Build failed:', err);
+    process.exit(1);
+});

package/docs/policy.md

@@ -0,0 +1,40 @@
+# FingguFlux Compiler: Explicit Class Policy
+
+To ensure 100% reliable tree-shaking and deterministic hashing, developers must adhere to the following class usage policy.
+
+## 1. Explicit Class Strings
+The compiler uses static analysis (regex) to identify used classes. It does **not** execute JavaScript. Therefore, class names must appear as full literal strings in your code.
+
+### ❌ Prohibited: Concatenation
+```javascript
+// This will NOT be detected
+const type = 'primary';
+const className = 'ff-btn-' + type; 
+```
+
+### ✅ Recommended: Explicit Literals
+```javascript
+// This will be detected correctly
+const className = isPrimary ? 'ff-btn-primary' : 'ff-btn-secondary';
+```
+
+## 2. Template Literals
+Standard template literals are supported as long as the FingguFlux class is a discrete word.
+
+### ✅ Supported
+```html
+<div class="ff-card ${isActive ? 'ff-shadow-lg' : ''}">
+```
+
+## 3. Escape Hatch: Safelist
+If you must use dynamic classes (e.g., from a CMS or database), add them to the `safelist` in your build configuration (to be implemented in Phase 7).
+
+Currently, you can force inclusion by adding invisible comments in your template:
+```html
+<!-- ff-safelist: ff-btn ff-shadow-xl -->
+```
+
+## 4. Determinism
+Hashes are derived from class names. 
+- `ff-btn` will **always** hash to the same value across any project or build.
+- Adding new classes does **not** affect existing hashes.

package/engine.js

@@ -0,0 +1,189 @@
+/**
+ * FingguFlux Compiler Engine
+ * Handles dependency resolution, tree-shaking, and selector mapping.
+ */
+import fs from 'fs';
+import path from 'path';
+
+export class CompilerEngine {
+    constructor(options = {}) {
+        this.mode = options.mode || 'dev'; // dev, opt, ext
+        this.mapping = {};
+        this.usedClasses = new Set();
+
+        // Dependency Manifest
+        this.dependencies = {
+            'ff-btn-': 'ff-btn',
+            'ff-tab-': 'ff-tab',
+            'ff-dropdown-': 'ff-dropdown',
+            'ff-modal-': 'ff-modal',
+            'ff-card-': 'ff-card',
+            'ff-input-': 'ff-input'
+        };
+    }
+
+    setUsedClasses(classes) {
+        this.usedClasses = new Set(classes);
+        this.resolveDependencies();
+    }
+
+    /**
+     * Resolves base class dependencies for variants
+     */
+    resolveDependencies() {
+        const expanded = new Set(this.usedClasses);
+        this.usedClasses.forEach(cls => {
+            for (const [prefix, base] of Object.entries(this.dependencies)) {
+                if (cls.startsWith(prefix)) {
+                    expanded.add(base);
+                }
+            }
+        });
+        this.usedClasses = expanded;
+    }
+
+    /**
+     * Generates a deterministic short hash for a class name
+     * Uses a simple FNV-1a inspired hash for speed and determinism
+     */
+    getHash(str) {
+        let hash = 0x811c9dc5;
+        for (let i = 0; i < str.length; i++) {
+            hash ^= str.charCodeAt(i);
+            hash += (hash << 1) + (hash << 4) + (hash << 7) + (hash << 8) + (hash << 24);
+        }
+        return (hash >>> 0).toString(36);
+    }
+
+    generateMapping(cls) {
+        if (this.mapping[cls]) return this.mapping[cls];
+
+        if (this.mode === 'dev') {
+            this.mapping[cls] = cls;
+        } else if (this.mode === 'opt') {
+            this.mapping[cls] = cls.replace('ff-', '');
+        } else if (this.mode === 'ext') {
+            const hash = this.getHash(cls);
+            this.mapping[cls] = `ff-${hash}`;
+        }
+
+        return this.mapping[cls];
+    }
+
+    processCSS(cssContent) {
+        let processed = cssContent;
+
+        // 1. Identify all .ff- selectors in the source
+        const classRegex = /\.ff-([\w-]+)/g;
+        const foundInCSS = new Set();
+        let match;
+        while ((match = classRegex.exec(cssContent)) !== null) {
+            foundInCSS.add(`ff-${match[1]}`);
+        }
+
+        // 2. Generate mappings only for USED classes
+        foundInCSS.forEach(cls => {
+            if (this.usedClasses.has(cls)) {
+                this.generateMapping(cls);
+            }
+        });
+
+        // 3. Tree-shaking (Block-level pruning) - DO THIS FIRST while names are original
+        const blocks = processed.split('}');
+        const filteredBlocks = blocks.filter(block => {
+            const selectorIndex = block.indexOf('{');
+            if (selectorIndex === -1) return block.trim().length > 0;
+
+            const selector = block.substring(0, selectorIndex).trim();
+
+            if (selector.includes('.ff-')) {
+                const ffClassesInSelector = selector.match(/\.ff-[\w-]+/g);
+                if (ffClassesInSelector) {
+                    // Prune block if ANY ff- class in the selector is unused
+                    // (Matches our strict tree-shaking policy for components/utilities)
+                    const hasUnused = ffClassesInSelector.some(cls => {
+                        const baseCls = cls.substring(1);
+                        return !this.usedClasses.has(baseCls);
+                    });
+                    if (hasUnused) return false;
+                }
+            }
+            return true;
+        });
+
+        processed = filteredBlocks.join('}') + (filteredBlocks.length > 0 ? '}' : '');
+
+        // 4. Replace selectors with mapped hashes
+        // NOTE: We explicitly DO NOT hash CSS variables starting with --ff-
+        // This ensures runtime theme switching remains operational.
+        const sortedClasses = Object.keys(this.mapping).sort((a, b) => b.length - a.length);
+        sortedClasses.forEach(cls => {
+            const mapped = this.mapping[cls];
+            if (cls !== mapped) {
+                const escapedCls = cls.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                const regex = new RegExp(`\\.${escapedCls}(?![\\w-])`, 'g');
+                processed = processed.replace(regex, `.${mapped}`);
+            }
+        });
+
+        // 5. Keyframe Pruning (Post-pruning)
+        return this.pruneKeyframes(processed);
+    }
+
+    pruneKeyframes(css) {
+        // Find all referenced animation names
+        const animationRegex = /animation(?:\-name)?\s*:\s*([^;!}]+)/g;
+        const usedAnimations = new Set();
+        let match;
+        while ((match = animationRegex.exec(css)) !== null) {
+            // Split by space/comma and filter out durations/easings/etc
+            const parts = match[1].split(/[,\s]+/).map(p => p.trim());
+            parts.forEach(p => {
+                if (p && !/^\d|ms|s|infinite|linear|ease|both|forwards|backwards/.test(p)) {
+                    usedAnimations.add(p);
+                }
+            });
+        }
+
+        // Prune unused @keyframes blocks
+        const keyframeBlocks = css.split(/@keyframes\s+([\w-]+)\s*\{/);
+        if (keyframeBlocks.length <= 1) return css;
+
+        let finalCSS = keyframeBlocks[0];
+        for (let i = 1; i < keyframeBlocks.length; i += 2) {
+            const name = keyframeBlocks[i];
+            const contentAndRest = keyframeBlocks[i + 1];
+
+            // Find the end of this @keyframes block (handling nested braces if any)
+            let braceCount = 1;
+            let endOfBlock = -1;
+            for (let j = 0; j < contentAndRest.length; j++) {
+                if (contentAndRest[j] === '{') braceCount++;
+                if (contentAndRest[j] === '}') braceCount--;
+                if (braceCount === 0) {
+                    endOfBlock = j;
+                    break;
+                }
+            }
+
+            const keyframeContent = contentAndRest.substring(0, endOfBlock + 1);
+            const rest = contentAndRest.substring(endOfBlock + 1);
+
+            if (usedAnimations.has(name)) {
+                finalCSS += `@keyframes ${name} {${keyframeContent}`;
+            }
+            finalCSS += rest;
+        }
+
+        return finalCSS;
+    }
+
+    getMapping() {
+        // Return sorted mapping for stability
+        const sortedMapping = {};
+        Object.keys(this.mapping).sort().forEach(key => {
+            sortedMapping[key] = this.mapping[key];
+        });
+        return sortedMapping;
+    }
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+    "name": "@finggujadhav/compiler",
+    "version": "0.9.0",
+    "description": "The FingguFlux static analysis and selector hardening engine.",
+    "main": "engine.js",
+    "bin": {
+        "finggu": "cli.js"
+    },
+    "files": [
+        "engine.js",
+        "scanner.js",
+        "cli.js",
+        "docs/policy.md"
+    ],
+    "type": "module",
+    "engines": {
+        "node": ">=16.0.0"
+    },
+    "keywords": [
+        "compiler",
+        "css-minification",
+        "hardening",
+        "obfuscation"
+    ],
+    "author": "Finggu Architecture Team",
+    "license": "MIT"
+}

package/scanner.js

@@ -0,0 +1,49 @@
+/**
+ * FingguFlux Scanner
+ * Scans HTML/Template files to extract used ff-* classes.
+ */
+import fs from 'fs';
+import path from 'path';
+
+export const scanFiles = (filePaths) => {
+    const usedClasses = new Set();
+    const ffClassRegex = /\bff-[\w-]+\b/g;
+
+    filePaths.forEach((filePath) => {
+        try {
+            const content = fs.readFileSync(filePath, 'utf8');
+            const matches = content.match(ffClassRegex);
+            if (matches) {
+                matches.forEach((cls) => usedClasses.add(cls));
+            }
+        } catch (err) {
+            console.error(`Error scanning file ${filePath}:`, err.message);
+        }
+    });
+
+    return Array.from(usedClasses);
+};
+
+export const getProjectFiles = (dir, extensions = ['.html', '.js', '.jsx', '.ts', '.tsx', '.vue', '.svelte']) => {
+    let results = [];
+    const list = fs.readdirSync(dir);
+
+    list.forEach((file) => {
+        file = path.join(dir, file);
+        const stat = fs.statSync(file);
+
+        if (stat && stat.isDirectory()) {
+            const base = path.basename(file);
+            if (base === 'node_modules' || base.startsWith('.')) return;
+            // Recurse into subdirectory
+            results = results.concat(getProjectFiles(file, extensions));
+        } else {
+            // Check extension
+            if (extensions.includes(path.extname(file))) {
+                results.push(file);
+            }
+        }
+    });
+
+    return results;
+};