gitgreen 0.1.0

package/data/runtime-pue-mappings.json

@@ -0,0 +1,183 @@
+{
+  "metadata": {
+    "generatedAt": "2025-06-14T16:09:07.455Z",
+    "methodology": "Real-time Electricity Maps API with industry standard PUE",
+    "availableZones": [
+      "US-CENT-SWPP"
+    ]
+  },
+  "regions": {
+    "us-central1": {
+      "zone": "US-CENT-SWPP",
+      "industryStandardPUE": 1.1,
+      "realTimeCarbonIntensity": 492,
+      "googleOfficialIntensity": 430,
+      "cfe": 0.95
+    },
+    "us-east1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-east4": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-west1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-west2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-west3": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-west4": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "us-south1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west3": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west4": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west6": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west8": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west9": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west10": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-west12": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-north1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-central2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "europe-southwest1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-east1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-east2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-northeast1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-northeast2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-northeast3": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-south1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-south2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-southeast1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "asia-southeast2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "australia-southeast1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "australia-southeast2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "southamerica-east1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "northamerica-northeast1": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    },
+    "northamerica-northeast2": {
+      "zone": "FALLBACK",
+      "industryStandardPUE": 1.1,
+      "error": "No matching zone found in available zones"
+    }
+  }
+}

package/dist/cli.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = __importDefault(require("fs"));
+const commander_1 = require("commander");
+const kleur_1 = require("kleur");
+const asciichart_1 = __importDefault(require("asciichart"));
+const index_1 = require("./index");
+const init_1 = require("./init");
+const program = new commander_1.Command();
+function parseGcpTimeseries(filePath) {
+    const raw = JSON.parse(fs_1.default.readFileSync(filePath, 'utf8'));
+    const points = [];
+    for (const ts of raw.timeSeries || []) {
+        for (const p of ts.points || []) {
+            const timestamp = p.interval?.endTime || p.interval?.startTime;
+            let value;
+            if (p.value?.doubleValue !== undefined) {
+                value = p.value.doubleValue;
+            }
+            else if (p.value?.int64Value !== undefined) {
+                value = Number(p.value.int64Value);
+            }
+            else {
+                continue;
+            }
+            points.push({ timestamp, value });
+        }
+    }
+    return points;
+}
+const runCalculate = async (opts) => {
+    const gitlabDisabled = opts.gitlab === false;
+    if (!opts.cpuTimeseries || !opts.ramUsedTimeseries || !opts.ramSizeTimeseries) {
+        console.error((0, kleur_1.red)('Error: --cpu-timeseries, --ram-used-timeseries, and --ram-size-timeseries are required'));
+        process.exitCode = 1;
+        return;
+    }
+    const cpuTimeseries = parseGcpTimeseries(opts.cpuTimeseries);
+    const ramUsedTimeseries = parseGcpTimeseries(opts.ramUsedTimeseries);
+    const ramSizeTimeseries = parseGcpTimeseries(opts.ramSizeTimeseries);
+    console.log((0, kleur_1.gray)(`Loaded ${cpuTimeseries.length} CPU points, ${ramUsedTimeseries.length} RAM points`));
+    // Sort by timestamp for charts
+    const cpuSorted = [...cpuTimeseries].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    const ramSorted = [...ramUsedTimeseries].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    const ramSizeSorted = [...ramSizeTimeseries].sort((a, b) => new Date(a.timestamp).getTime() - new Date(b.timestamp).getTime());
+    // CPU chart (only if more than 1 point)
+    const cpuValues = cpuSorted.map(p => p.value * 100);
+    if (cpuValues.length > 1) {
+        console.log((0, kleur_1.bold)('\nCPU Utilization (%)'));
+        console.log(asciichart_1.default.plot(cpuValues, { height: 8, format: (x) => x.toFixed(1).padStart(6) }));
+    }
+    // RAM chart (only if more than 1 point)
+    if (ramSorted.length > 1 && ramSizeSorted.length > 0) {
+        const totalRamGb = ramSizeSorted[0].value / (1024 * 1024 * 1024);
+        const ramPercent = ramSorted.map(p => (p.value / (1024 * 1024 * 1024) / totalRamGb) * 100);
+        console.log((0, kleur_1.bold)('\nRAM Utilization (%)'));
+        console.log(asciichart_1.default.plot(ramPercent, { height: 8, format: (x) => x.toFixed(1).padStart(6) }));
+    }
+    try {
+        const { result, budget, markdown } = await (0, index_1.calculate)({
+            provider: opts.provider,
+            machineType: opts.machine,
+            region: opts.region,
+            cpuTimeseries,
+            ramUsedTimeseries,
+            ramSizeTimeseries,
+            carbonBudgetGrams: opts.budget,
+            failOnBreach: opts.failOnBudget,
+            runnerTags: opts.runnerTags ? String(opts.runnerTags).split(/[,\s]+/).filter(Boolean) : (0, index_1.readRunnerTagsFromEnv)(),
+            gitlab: gitlabDisabled ? false : { postMergeRequestNote: Boolean(opts.postNote) },
+            writeMarkdownPath: opts.outMd,
+            writeJsonPath: opts.outJson
+        });
+        const statusColor = budget.overBudget ? kleur_1.red : kleur_1.green;
+        const totalEnergyWh = (result.cpuEnergyKwh + result.ramEnergyKwh) * 1000;
+        console.log((0, kleur_1.bold)('\nCarbon Report'));
+        console.log((0, kleur_1.gray)('------------------------------'));
+        console.log(`Provider: ${result.provider.toUpperCase()}`);
+        console.log(`Region:   ${result.region}`);
+        console.log(`Machine:  ${result.machineType}`);
+        console.log(`Runtime:  ${(result.runtimeHours * 3600).toFixed(0)}s`);
+        console.log(`Energy:   ${totalEnergyWh.toFixed(3)} Wh`);
+        console.log(`Total:    ${statusColor(result.totalEmissions.toFixed(3) + ' gCO2e')}`);
+        if (budget.budgetConfigured && budget.limitGrams) {
+            console.log(`Budget:   ${budget.limitGrams} gCO2e (${budget.overBudget ? 'over' : 'within'})`);
+        }
+        if (opts.outMd || opts.outJson) {
+            console.log((0, kleur_1.gray)('Artifacts:'));
+            if (opts.outMd)
+                console.log(`- markdown: ${opts.outMd}`);
+            if (opts.outJson)
+                console.log(`- json:     ${opts.outJson}`);
+        }
+        if (!opts.outMd && !opts.outJson) {
+            console.log('\n' + markdown);
+        }
+        if (budget.overBudget && opts.failOnBudget) {
+            process.exitCode = 1;
+        }
+    }
+    catch (err) {
+        console.error((0, kleur_1.red)('Error:'), err?.message || err);
+        process.exitCode = 1;
+    }
+};
+program
+    .name('gitgreen')
+    .description('GitGreen carbon calculator using real timeseries metrics')
+    .option('-p, --provider <provider>', 'Cloud provider (gcp)')
+    .option('-m, --machine <type>', 'Machine type (e.g., e2-standard-4)')
+    .option('-r, --region <region>', 'Region/zone (e.g., us-central1-a)')
+    .option('--cpu-timeseries <path>', 'Path to CPU timeseries JSON (GCP Monitoring format)')
+    .option('--ram-used-timeseries <path>', 'Path to RAM used timeseries JSON')
+    .option('--ram-size-timeseries <path>', 'Path to RAM size timeseries JSON')
+    .option('--budget <grams>', 'Carbon budget in grams CO2e', v => Number(v))
+    .option('--fail-on-budget', 'Exit non-zero when budget exceeded')
+    .option('--out-md <path>', 'Write markdown report')
+    .option('--out-json <path>', 'Write JSON report')
+    .option('--runner-tags <tags>', 'Comma-separated runner tags')
+    .option('--no-gitlab', 'Disable GitLab context auto-detection')
+    .option('--post-note', 'Post MR note when GitLab context is present')
+    .showHelpAfterError()
+    .action(async (opts) => {
+    await runCalculate(opts);
+});
+program
+    .command('init')
+    .description('Interactive setup for GitLab CI integration')
+    .option('--yes', 'Accept defaults when possible')
+    .action(async (cmdOpts) => {
+    await (0, init_1.runInit)({ assumeYes: Boolean(cmdOpts.yes) });
+});
+program.parseAsync(process.argv);

package/dist/config.js

@@ -0,0 +1,43 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const dotenv_1 = __importDefault(require("dotenv"));
+dotenv_1.default.config();
+const numberFromEnv = (value, fallback) => {
+    if (!value)
+        return fallback;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+};
+const resolveDataDir = () => {
+    if (process.env.DATA_DIR) {
+        return path_1.default.resolve(process.env.DATA_DIR);
+    }
+    const bundled = path_1.default.join(__dirname, '..', 'data');
+    if (fs_1.default.existsSync(bundled)) {
+        return bundled;
+    }
+    const implData = path_1.default.join(__dirname, '..', '..', 'implementation', 'data');
+    if (fs_1.default.existsSync(implData)) {
+        return implData;
+    }
+    const cwdData = path_1.default.join(process.cwd(), 'data');
+    if (fs_1.default.existsSync(cwdData)) {
+        return cwdData;
+    }
+    return path_1.default.join(__dirname, '..', 'data');
+};
+exports.config = {
+    electricityMapsApiKey: process.env.ELECTRICITY_MAPS_API_KEY || '',
+    electricityMapsBaseUrl: process.env.ELECTRICITY_MAPS_BASE_URL || 'https://api.electricitymaps.com/v3',
+    gitlabBaseUrl: process.env.GITLAB_BASE_URL || 'https://gitlab.com',
+    defaultProvider: process.env.DEFAULT_PROVIDER || 'gcp',
+    fallbackPue: numberFromEnv(process.env.PUE_FALLBACK, 1.2),
+    gcpProjectId: process.env.GCP_PROJECT_ID || process.env.GOOGLE_CLOUD_PROJECT || '',
+    dataDir: resolveDataDir()
+};

package/dist/index.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readRunnerTagsFromEnv = exports.calculate = void 0;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+const config_1 = require("./config");
+const carbon_calculator_1 = require("./lib/carbon/carbon-calculator");
+const intensity_provider_1 = require("./lib/carbon/intensity-provider");
+const power_profile_repository_1 = require("./lib/carbon/power-profile-repository");
+const zone_mapper_1 = require("./lib/carbon/zone-mapper");
+const gitlab_client_1 = require("./lib/gitlab/gitlab-client");
+const report_formatter_1 = require("./lib/gitlab/report-formatter");
+const createDependencies = () => {
+    const powerProfileRepository = new power_profile_repository_1.PowerProfileRepository(config_1.config.dataDir);
+    const zoneMapper = new zone_mapper_1.ZoneMapper(config_1.config.dataDir, config_1.config.fallbackPue);
+    const intensityProvider = new intensity_provider_1.IntensityProvider(config_1.config.electricityMapsBaseUrl, config_1.config.electricityMapsApiKey);
+    const calculator = new carbon_calculator_1.CarbonCalculator(powerProfileRepository, zoneMapper, intensityProvider);
+    const gitlabClient = new gitlab_client_1.GitLabClient(config_1.config.gitlabBaseUrl);
+    return { calculator, gitlabClient };
+};
+const resolveGitLabContextFromEnv = (overrides) => {
+    const jobToken = overrides?.jobToken || process.env.CI_JOB_TOKEN;
+    const projectId = overrides?.projectId ?? (process.env.CI_PROJECT_ID ? Number(process.env.CI_PROJECT_ID) : undefined);
+    const jobId = overrides?.jobId ?? (process.env.CI_JOB_ID ? Number(process.env.CI_JOB_ID) : undefined);
+    const pipelineId = overrides?.pipelineId ?? (process.env.CI_PIPELINE_ID ? Number(process.env.CI_PIPELINE_ID) : undefined);
+    const mergeRequestIid = overrides?.mergeRequestIid ?? (process.env.CI_MERGE_REQUEST_IID ? Number(process.env.CI_MERGE_REQUEST_IID) : undefined);
+    const serverUrl = overrides?.serverUrl || process.env.CI_SERVER_URL || config_1.config.gitlabBaseUrl;
+    if (!jobToken || !projectId || !jobId)
+        return undefined;
+    return { projectId, jobId, pipelineId, mergeRequestIid, jobToken, serverUrl };
+};
+const toNumberIfSet = (value) => {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : undefined;
+};
+const calculate = async (options) => {
+    const deps = createDependencies();
+    if (!['gcp', 'aws'].includes(options.provider)) {
+        throw new Error('provider must be gcp or aws');
+    }
+    if (!options.cpuTimeseries.length) {
+        throw new Error('cpuTimeseries is required and must have at least one data point');
+    }
+    const jobInput = {
+        provider: options.provider,
+        machineType: options.machineType,
+        region: options.region,
+        cpuTimeseries: options.cpuTimeseries,
+        ramUsedTimeseries: options.ramUsedTimeseries,
+        ramSizeTimeseries: options.ramSizeTimeseries
+    };
+    const budgetValue = toNumberIfSet(options.carbonBudgetGrams);
+    const budget = budgetValue !== undefined ? {
+        carbonBudgetGrams: budgetValue,
+        failOnBreach: Boolean(options.failOnBreach)
+    } : undefined;
+    const result = await deps.calculator.calculate(jobInput);
+    const markdown = (0, report_formatter_1.buildMarkdownReport)(result, jobInput, budget);
+    const jsonReport = (0, report_formatter_1.buildJsonReport)(result, jobInput, budget);
+    const budgetResult = (0, report_formatter_1.evaluateBudget)(result, budget);
+    if (options.writeMarkdownPath) {
+        fs_1.default.writeFileSync(path_1.default.resolve(options.writeMarkdownPath), markdown, 'utf8');
+    }
+    if (options.writeJsonPath) {
+        fs_1.default.writeFileSync(path_1.default.resolve(options.writeJsonPath), JSON.stringify(jsonReport, null, 2), 'utf8');
+    }
+    const gitlabContext = options.gitlab === false ? undefined : resolveGitLabContextFromEnv(options.gitlab);
+    const gitlabOpts = options.gitlab !== false ? options.gitlab : undefined;
+    if (gitlabOpts?.postMergeRequestNote && gitlabContext?.jobToken) {
+        await deps.gitlabClient.postMergeRequestNote({
+            projectId: Number(gitlabContext.projectId),
+            jobId: Number(gitlabContext.jobId),
+            pipelineId: gitlabContext.pipelineId ? Number(gitlabContext.pipelineId) : undefined,
+            mergeRequestIid: gitlabContext.mergeRequestIid ? Number(gitlabContext.mergeRequestIid) : undefined,
+            jobToken: gitlabContext.jobToken,
+            serverUrl: gitlabContext.serverUrl || config_1.config.gitlabBaseUrl
+        }, markdown);
+    }
+    if (budgetResult.overBudget && budget?.failOnBreach) {
+        throw new Error(`Carbon budget exceeded (${budgetResult.limitGrams} gCO2e)`);
+    }
+    return { result, budget: budgetResult, markdown, jsonReport };
+};
+exports.calculate = calculate;
+const readRunnerTagsFromEnv = () => {
+    const tagsEnv = process.env.CI_RUNNER_TAGS || process.env.RUNNER_TAGS || '';
+    return tagsEnv.split(/[,\s]+/).filter(Boolean);
+};
+exports.readRunnerTagsFromEnv = readRunnerTagsFromEnv;