carbonlint-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nishal K
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# carbonlint-cli
+
+> Measure and track the carbon footprint of your software projects from the command line.
+
+[![npm](https://img.shields.io/npm/v/carbonlint-cli)](https://www.npmjs.com/package/carbonlint-cli)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+**CarbonLint CLI** estimates the CO₂ emissions of your codebase by analyzing file types, sizes, and regional carbon intensity data. Use it locally or in CI/CD pipelines to set carbon budgets and catch regressions.
+
+## Install
+
+```bash
+npm install -g carbonlint-cli
+```
+
+## Quick Start
+
+```bash
+# Initialize config in your project
+carbonlint init
+
+# Scan your project
+carbonlint .
+
+# Override region for a specific scan
+carbonlint . --region EU-NORTH
+
+# JSON output for CI pipelines
+carbonlint . --json
+
+# Fail the build if over budget (CI gate)
+carbonlint . --ci --budget 50
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `carbonlint init` | Create `.carbonlintrc.json` with default settings |
+| `carbonlint [path]` | Scan project and generate carbon report |
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-r, --region <region>` | Carbon intensity region | `GLOBAL-AVG` |
+| `-b, --budget <grams>` | Carbon budget threshold in grams | `100` |
+| `--profile <profile>` | Hardware profile (`laptop`/`desktop`/`server`) | `laptop` |
+| `--json` | Output structured JSON | — |
+| `--ci` | Exit code 1 if over budget | — |
+
+## Regions
+
+| Key | Location | gCO₂/kWh |
+|-----|----------|-----------|
+| `EU-NORTH` | Sweden | 25 |
+| `US-WEST` | California | 210 |
+| `EU-WEST` | Ireland | 300 |
+| `US-EAST` | Virginia | 380 |
+| `ASIA-EAST` | Japan | 470 |
+| `GLOBAL-AVG` | Global Average | 475 |
+| `ASIA-SOUTH` | India | 700 |
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Carbon Check
+  run: |
+    npm install -g carbonlint-cli
+    carbonlint . --ci --budget 50 --region US-WEST
+```
+
+### GitLab CI
+
+```yaml
+carbon-check:
+  script:
+    - npm install -g carbonlint-cli
+    - carbonlint . --ci --budget 50
+```
+
+## Configuration
+
+Create `.carbonlintrc.json` with `carbonlint init`:
+
+```json
+{
+  "region": "GLOBAL-AVG",
+  "hardwareProfile": "laptop",
+  "pue": 1.0,
+  "maxCarbon": 100,
+  "failOnThreshold": false
+}
+```
+
+## Programmatic API
+
+```js
+import { scanProject, loadConfig } from 'carbonlint-cli';
+
+const config = loadConfig('.');
+const result = scanProject('.', config);
+console.log(result.greenScore);  // 0-100
+console.log(result.carbon_grams);
+```
+
+## License
+
+MIT © [Nishal K](https://github.com/nishal21)

package/bin/carbonlint.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+run();

package/package.json

@@ -0,0 +1,49 @@
+{
+    "name": "carbonlint-cli",
+    "version": "1.0.0",
+    "description": "CLI tool for measuring and tracking the carbon footprint of your software projects. Supports CI/CD integration with carbon budgets.",
+    "main": "src/index.js",
+    "bin": {
+        "carbonlint": "./bin/carbonlint.js"
+    },
+    "type": "module",
+    "scripts": {
+        "test": "node bin/carbonlint.js --help"
+    },
+    "keywords": [
+        "carbon",
+        "sustainability",
+        "green-coding",
+        "carbon-footprint",
+        "energy",
+        "co2",
+        "climate",
+        "linter",
+        "ci-cd",
+        "devtools"
+    ],
+    "author": "Nishal K <nishalamv@gmail.com>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/nishal21/carbonlint"
+    },
+    "homepage": "https://nishal21.github.io/carbonlint/",
+    "bugs": {
+        "url": "https://github.com/nishal21/carbonlint/issues"
+    },
+    "engines": {
+        "node": ">=16.0.0"
+    },
+    "dependencies": {
+        "chalk": "^5.3.0",
+        "commander": "^12.1.0",
+        "ora": "^8.1.0"
+    },
+    "files": [
+        "bin/",
+        "src/",
+        "README.md",
+        "LICENSE"
+    ]
+}

package/src/cli.js

@@ -0,0 +1,84 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import { createConfig, loadConfig } from './config.js';
+import { scanProject } from './scanner.js';
+import { printReport, printJson } from './reporter.js';
+import { REGIONS } from './data.js';
+
+export function run() {
+    const program = new Command();
+
+    program
+        .name('carbonlint')
+        .description('Measure and track the carbon footprint of your software projects')
+        .version('1.0.0');
+
+    // ── Init command ──
+    program
+        .command('init')
+        .description('Create a .carbonlintrc.json config file in the current directory')
+        .action(() => {
+            const result = createConfig('.');
+            if (result.created) {
+                console.log(chalk.green('✓') + ` Created ${chalk.bold('.carbonlintrc.json')} in project root`);
+                console.log(chalk.dim('  Edit it to set region, budget, and hardware profile.'));
+            } else {
+                console.log(chalk.yellow('!') + ' .carbonlintrc.json already exists at ' + chalk.dim(result.path));
+            }
+        });
+
+    // ── Scan (default) command ──
+    program
+        .argument('[path]', 'Path to project directory to scan', '.')
+        .option('-r, --region <region>', 'Carbon intensity region', '')
+        .option('-b, --budget <grams>', 'Carbon budget in grams', '')
+        .option('--json', 'Output results as JSON')
+        .option('--ci', 'CI mode: exit with code 1 if over budget')
+        .option('--profile <profile>', 'Hardware profile (laptop/desktop/server)', '')
+        .action(async (targetPath, options) => {
+            // Load config, apply CLI overrides
+            const config = loadConfig(targetPath);
+            if (options.region) config.region = options.region;
+            if (options.budget) config.maxCarbon = Number(options.budget);
+            if (options.profile) config.hardwareProfile = options.profile;
+            if (options.ci) config.failOnThreshold = true;
+
+            // Validate region
+            const regionKey = config.region.toUpperCase();
+            if (!REGIONS[regionKey]) {
+                console.error(chalk.red('✗') + ` Unknown region: ${config.region}`);
+                console.error(chalk.dim('  Available: ' + Object.keys(REGIONS).join(', ')));
+                process.exit(1);
+            }
+
+            const spinner = options.json ? null : ora('Scanning project...').start();
+
+            try {
+                const result = scanProject(targetPath, config);
+
+                if (spinner) spinner.succeed(`Scanned ${result.totalFiles} files`);
+
+                if (options.json) {
+                    printJson(result);
+                } else {
+                    printReport(result);
+                }
+
+                // CI gate
+                if (config.failOnThreshold && result.overBudget) {
+                    if (!options.json) {
+                        console.log(chalk.red.bold('  ✗ CI CHECK FAILED') + chalk.dim(` — carbon ${result.carbon_grams.toFixed(4)}g exceeds budget ${result.budget}g`));
+                        console.log();
+                    }
+                    process.exit(1);
+                }
+            } catch (err) {
+                if (spinner) spinner.fail('Scan failed');
+                console.error(chalk.red(err.message));
+                process.exit(1);
+            }
+        });
+
+    program.parse();
+}

package/src/config.js

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { DEFAULTS } from './data.js';
+
+const CONFIG_FILE = '.carbonlintrc.json';
+
+export function findConfig(dir) {
+    let current = path.resolve(dir);
+    while (true) {
+        const candidate = path.join(current, CONFIG_FILE);
+        if (fs.existsSync(candidate)) return candidate;
+        const parent = path.dirname(current);
+        if (parent === current) break;
+        current = parent;
+    }
+    return null;
+}
+
+export function loadConfig(dir) {
+    const configPath = findConfig(dir);
+    if (!configPath) return { ...DEFAULTS };
+    try {
+        const raw = fs.readFileSync(configPath, 'utf-8');
+        return { ...DEFAULTS, ...JSON.parse(raw) };
+    } catch {
+        return { ...DEFAULTS };
+    }
+}
+
+export function createConfig(dir) {
+    const configPath = path.join(path.resolve(dir), CONFIG_FILE);
+    if (fs.existsSync(configPath)) return { created: false, path: configPath };
+    const config = {
+        region: DEFAULTS.region,
+        hardwareProfile: DEFAULTS.hardwareProfile,
+        pue: DEFAULTS.pue,
+        maxCarbon: DEFAULTS.maxCarbon,
+        failOnThreshold: DEFAULTS.failOnThreshold,
+    };
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+    return { created: true, path: configPath };
+}

package/src/data.js

@@ -0,0 +1,52 @@
+// CarbonLint CLI — Carbon intensity data per region (gCO₂/kWh)
+// Source: matches the Tauri desktop app's get_carbon_intensity_map()
+
+export const REGIONS = {
+    'US-WEST': { name: 'California, US', gco2_kwh: 210 },
+    'US-EAST': { name: 'Virginia, US', gco2_kwh: 380 },
+    'EU-WEST': { name: 'Ireland, EU', gco2_kwh: 300 },
+    'EU-NORTH': { name: 'Sweden, EU', gco2_kwh: 25 },
+    'ASIA-EAST': { name: 'Japan', gco2_kwh: 470 },
+    'ASIA-SOUTH': { name: 'India', gco2_kwh: 700 },
+    'GLOBAL-AVG': { name: 'Global Average', gco2_kwh: 475 },
+};
+
+// Hardware power profiles (watts)
+export const HARDWARE = {
+    laptop: { cpu_tdp: 15, mem_per_gb: 0.3 },
+    desktop: { cpu_tdp: 65, mem_per_gb: 0.4 },
+    server: { cpu_tdp: 150, mem_per_gb: 0.5 },
+};
+
+// File type weights — how much relative energy different files consume during build
+export const FILE_WEIGHTS = {
+    // Heavy compile / transpile
+    '.ts': 1.0, '.tsx': 1.0, '.jsx': 1.0,
+    '.rs': 1.2, '.cpp': 1.2, '.c': 1.0,
+    '.java': 1.1, '.go': 0.9, '.cs': 1.1,
+    // Normal
+    '.js': 0.6, '.mjs': 0.6, '.cjs': 0.6,
+    '.py': 0.5, '.rb': 0.5, '.php': 0.5,
+    // Styles / markup
+    '.css': 0.3, '.scss': 0.4, '.less': 0.4,
+    '.html': 0.2, '.vue': 0.8, '.svelte': 0.8,
+    // Config / docs (minimal)
+    '.json': 0.1, '.yaml': 0.1, '.yml': 0.1,
+    '.toml': 0.1, '.xml': 0.1, '.md': 0.05,
+    '.txt': 0.02, '.env': 0.01,
+    // Assets (energy comes from bundling/optimizing)
+    '.png': 0.15, '.jpg': 0.15, '.jpeg': 0.15,
+    '.gif': 0.15, '.svg': 0.1, '.webp': 0.1,
+    '.ico': 0.05, '.mp4': 0.2, '.webm': 0.2,
+    '.woff': 0.05, '.woff2': 0.05, '.ttf': 0.05,
+};
+
+// Default config values — matches Tauri's AppSettings defaults
+export const DEFAULTS = {
+    region: 'GLOBAL-AVG',
+    hardwareProfile: 'laptop',
+    pue: 1.0,
+    maxCarbon: 100,     // grams
+    maxEnergy: 0.5,     // kWh
+    failOnThreshold: false,
+};

package/src/index.js

@@ -0,0 +1,4 @@
+// CarbonLint CLI — Programmatic API
+export { scanProject } from './scanner.js';
+export { loadConfig, createConfig } from './config.js';
+export { REGIONS, HARDWARE, FILE_WEIGHTS, DEFAULTS } from './data.js';

package/src/reporter.js

@@ -0,0 +1,110 @@
+import chalk from 'chalk';
+
+const g = chalk.green;
+const y = chalk.yellow;
+const r = chalk.red;
+const d = chalk.dim;
+const b = chalk.bold;
+
+export function printReport(result) {
+    const hr = d('─'.repeat(56));
+
+    console.log();
+    console.log(b(g('  🌿 CarbonLint')) + d(' — Carbon Footprint Report'));
+    console.log(hr);
+    console.log();
+
+    // Green Score
+    const scoreColor = result.greenScore >= 80 ? g : result.greenScore >= 50 ? y : r;
+    const scoreBar = buildBar(result.greenScore);
+    console.log(`  ${b('Green Score')}  ${scoreColor(b(result.greenScore + '/100'))} ${scoreLabel(result.greenScore)}`);
+    console.log(`  ${scoreBar}`);
+    console.log();
+
+    // Stats
+    console.log(`  ${d('Files scanned')}     ${b(result.totalFiles.toLocaleString())}`);
+    console.log(`  ${d('Total size')}        ${b(formatBytes(result.totalSize))}`);
+    console.log(`  ${d('Region')}            ${b(result.region.key)} ${d('(' + result.region.name + ', ' + result.region.gco2_kwh + ' gCO₂/kWh)')}`);
+    console.log(`  ${d('Est. energy')}       ${b(result.energy_kWh.toFixed(6))} ${d('kWh')}`);
+    console.log(`  ${d('Est. CO₂')}          ${carbonColor(result.carbon_grams, result.budget)(b(result.carbon_grams.toFixed(4) + 'g'))}`);
+    console.log(`  ${d('Budget')}            ${b(result.budget + 'g')} ${result.overBudget ? r('⚠ OVER BUDGET') : g('✓ within budget')}`);
+    console.log();
+
+    // Breakdown table
+    if (result.breakdown.length > 0) {
+        console.log(`  ${b('File Breakdown')} ${d('(top 10 by weight)')}`);
+        console.log(`  ${d('Ext'.padEnd(10))} ${'Count'.padStart(7)}  ${'Size'.padStart(10)}  ${'Weight'.padStart(10)}`);
+        console.log(`  ${d('─'.repeat(42))}`);
+        for (const row of result.breakdown.slice(0, 10)) {
+            console.log(
+                `  ${(row.ext || '(none)').padEnd(10)} ${String(row.count).padStart(7)}  ${formatBytes(row.size).padStart(10)}  ${row.weight.toFixed(1).padStart(10)}`
+            );
+        }
+        console.log();
+    }
+
+    // Warnings
+    if (result.warnings.length > 0) {
+        console.log(`  ${y(b('⚠ Warnings'))} ${d('(' + result.warnings.length + ')')}`);
+        for (const w of result.warnings.slice(0, 5)) {
+            console.log(`  ${y('›')} ${w.message}`);
+        }
+        if (result.warnings.length > 5) {
+            console.log(`  ${d('  ... and ' + (result.warnings.length - 5) + ' more')}`);
+        }
+        console.log();
+    }
+
+    console.log(hr);
+    console.log(d('  Powered by CarbonLint — https://nishal21.github.io/carbonlint/'));
+    console.log();
+}
+
+export function printJson(result) {
+    const output = {
+        version: '1.0.0',
+        greenScore: result.greenScore,
+        files: result.totalFiles,
+        totalSizeBytes: result.totalSize,
+        region: result.region.key,
+        regionName: result.region.name,
+        carbonIntensity_gCO2_kWh: result.region.gco2_kwh,
+        estimatedEnergy_kWh: Number(result.energy_kWh.toFixed(6)),
+        estimatedCarbon_grams: Number(result.carbon_grams.toFixed(4)),
+        budget_grams: result.budget,
+        overBudget: result.overBudget,
+        breakdown: result.breakdown,
+        warnings: result.warnings.map(w => w.message),
+    };
+    console.log(JSON.stringify(output, null, 2));
+}
+
+// ── Helpers ──
+
+function buildBar(score) {
+    const width = 30;
+    const filled = Math.round((score / 100) * width);
+    const empty = width - filled;
+    const color = score >= 80 ? g : score >= 50 ? y : r;
+    return d('[') + color('█'.repeat(filled)) + d('░'.repeat(empty)) + d(']');
+}
+
+function scoreLabel(score) {
+    if (score >= 90) return g('(Excellent)');
+    if (score >= 75) return g('(Good)');
+    if (score >= 50) return y('(Fair)');
+    if (score >= 25) return y('(Needs Work)');
+    return r('(Poor)');
+}
+
+function carbonColor(grams, budget) {
+    if (grams > budget) return r;
+    if (grams > budget * 0.8) return y;
+    return g;
+}
+
+function formatBytes(bytes) {
+    if (bytes < 1024) return bytes + ' B';
+    if (bytes < 1024 * 1024) return (bytes / 1024).toFixed(1) + ' KB';
+    return (bytes / (1024 * 1024)).toFixed(1) + ' MB';
+}

package/src/scanner.js

@@ -0,0 +1,105 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { FILE_WEIGHTS, REGIONS, HARDWARE } from './data.js';
+
+// Directories to always skip
+const SKIP_DIRS = new Set([
+    'node_modules', '.git', '.svn', '.hg', 'dist', 'build', 'out',
+    '.next', '.nuxt', '.output', '__pycache__', '.venv', 'venv',
+    'target', 'vendor', '.cache', '.parcel-cache', 'coverage',
+    '.turbo', '.vercel', '.netlify',
+]);
+
+export function scanProject(targetPath, config = {}) {
+    const root = path.resolve(targetPath);
+    const files = [];
+    const warnings = [];
+
+    walk(root, files, warnings);
+
+    // Compute totals
+    const totalFiles = files.length;
+    const totalSize = files.reduce((s, f) => s + f.size, 0);
+    const totalWeight = files.reduce((s, f) => s + f.weight, 0);
+
+    // Estimate energy: weighted file score → simulated kWh
+    // Baseline: 1000 weight-units ≈ 0.01 kWh (a reasonable dev-build estimate)
+    const baseEnergy_kWh = (totalWeight / 1000) * 0.01;
+
+    // PUE factor (Power Usage Effectiveness — data centre overhead)
+    const pue = config.pue || 1.0;
+    const energy_kWh = baseEnergy_kWh * pue;
+
+    // Carbon
+    const regionKey = (config.region || 'GLOBAL-AVG').toUpperCase();
+    const region = REGIONS[regionKey] || REGIONS['GLOBAL-AVG'];
+    const carbon_grams = energy_kWh * region.gco2_kwh;
+
+    // Green Score (0-100) — lower carbon = higher score
+    const budget = config.maxCarbon || 100;
+    const ratio = carbon_grams / budget;
+    const greenScore = Math.max(0, Math.min(100, Math.round(100 - ratio * 50)));
+
+    // Breakdown by extension
+    const byExt = {};
+    for (const f of files) {
+        if (!byExt[f.ext]) byExt[f.ext] = { count: 0, size: 0, weight: 0 };
+        byExt[f.ext].count++;
+        byExt[f.ext].size += f.size;
+        byExt[f.ext].weight += f.weight;
+    }
+
+    // Sort by weight desc
+    const breakdown = Object.entries(byExt)
+        .sort((a, b) => b[1].weight - a[1].weight)
+        .map(([ext, data]) => ({ ext, ...data }));
+
+    // Heavy asset warnings
+    for (const f of files) {
+        if (f.size > 512 * 1024 && /\.(png|jpg|jpeg|gif|mp4|webm|bmp|tiff)$/i.test(f.ext)) {
+            warnings.push({
+                type: 'heavy-asset',
+                file: path.relative(root, f.path),
+                size: f.size,
+                message: `Heavy asset: ${path.relative(root, f.path)} (${(f.size / 1024).toFixed(0)} KB)`,
+            });
+        }
+    }
+
+    return {
+        root,
+        totalFiles,
+        totalSize,
+        totalWeight,
+        energy_kWh,
+        carbon_grams,
+        greenScore,
+        region: { key: regionKey, ...region },
+        budget,
+        overBudget: carbon_grams > budget,
+        breakdown,
+        warnings,
+    };
+}
+
+function walk(dir, files, warnings) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { return; }
+
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') && entry.name !== '.env') continue;
+        const full = path.join(dir, entry.name);
+
+        if (entry.isDirectory()) {
+            if (SKIP_DIRS.has(entry.name)) continue;
+            walk(full, files, warnings);
+        } else if (entry.isFile()) {
+            const ext = path.extname(entry.name).toLowerCase();
+            let size;
+            try { size = fs.statSync(full).size; } catch { continue; }
+            const weight = (FILE_WEIGHTS[ext] || 0.05) * (size / 1024); // weight per KB
+            files.push({ path: full, ext, size, weight });
+        }
+    }
+}