@foxlight/ci 0.1.0

package/README.md

@@ -0,0 +1,81 @@
+# @foxlight/ci
+
+CI/CD integration for [Foxlight](https://github.com/josegabrielcruz/foxlight) — the open-source front-end intelligence platform.
+
+## What's Inside
+
+- **GitHub Integration** — PR comments with component/bundle/health diffs, Check Runs API with pass/fail annotations
+- **GitLab Integration** — merge request notes with the same diff tables
+- **Snapshot Comparator** — captures project state and detects significant changes between snapshots
+
+## Installation
+
+```bash
+npm install @foxlight/ci
+```
+
+## GitHub Actions
+
+```yaml
+# .github/workflows/foxlight.yml
+name: Foxlight
+on: [pull_request]
+
+jobs:
+  analyze:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npx foxlight ci
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## GitLab CI
+
+```yaml
+# .gitlab-ci.yml
+foxlight:
+  script:
+    - npm ci
+    - npx foxlight ci
+  rules:
+    - if: $CI_MERGE_REQUEST_IID
+```
+
+## Programmatic API
+
+```typescript
+import {
+  postPRComment,
+  createCheckRun,
+  detectGitHubEnv,
+  postMRComment,
+  detectGitLabEnv,
+} from '@foxlight/ci';
+
+// GitHub — post a PR comment
+const env = detectGitHubEnv();
+if (env) {
+  await postPRComment(env, snapshotDiff);
+  await createCheckRun({
+    ...env,
+    name: 'Foxlight Analysis',
+    diff: snapshotDiff,
+  });
+}
+
+// GitLab — post an MR note
+const gitlabEnv = detectGitLabEnv();
+if (gitlabEnv) {
+  await postMRComment(gitlabEnv, snapshotDiff);
+}
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,90 @@
+import { SnapshotDiff, ProjectSnapshot } from '@foxlight/core';
+
+/** GitHub API configuration. */
+interface GitHubConfig {
+    /** GitHub API token */
+    token: string;
+    /** Repository owner */
+    owner: string;
+    /** Repository name */
+    repo: string;
+    /** PR number */
+    prNumber: number;
+    /** Optional: GitHub API base URL (for GitHub Enterprise) */
+    apiUrl?: string;
+}
+/**
+ * Detect GitHub environment from CI environment variables.
+ * Works in GitHub Actions automatically.
+ */
+declare function detectGitHubEnv(): Partial<GitHubConfig>;
+/**
+ * Post a Foxlight analysis comment on a GitHub PR.
+ */
+declare function postPRComment(config: GitHubConfig, diff: SnapshotDiff): Promise<void>;
+/**
+ * Generate the Markdown body for a PR comment.
+ */
+declare function generateCommentBody(diff: SnapshotDiff): string;
+/** Options for creating a GitHub check run. */
+interface CheckRunOptions {
+    /** Name of the check (e.g., "Foxlight Analysis") */
+    name: string;
+    /** The head SHA to attach the check to */
+    headSha: string;
+}
+/**
+ * Create a GitHub Check Run with Foxlight analysis results.
+ * Check Runs appear in the PR's "Checks" tab and can report
+ * success/failure based on configurable thresholds.
+ */
+declare function createCheckRun(config: GitHubConfig, diff: SnapshotDiff, options: CheckRunOptions): Promise<void>;
+
+/** GitLab API configuration. */
+interface GitLabConfig {
+    /** GitLab private token or CI job token */
+    token: string;
+    /** Project ID (numeric) or URL-encoded path (e.g. "group%2Fproject") */
+    projectId: string;
+    /** Merge request IID */
+    mergeRequestIid: number;
+    /** Optional: GitLab API base URL (for self-hosted instances) */
+    apiUrl?: string;
+}
+/**
+ * Detect GitLab environment from CI environment variables.
+ * Works in GitLab CI/CD pipelines automatically.
+ */
+declare function detectGitLabEnv(): Partial<GitLabConfig>;
+/**
+ * Post a Foxlight analysis comment on a GitLab merge request.
+ */
+declare function postMRComment(config: GitLabConfig, diff: SnapshotDiff): Promise<void>;
+
+interface CompareOptions {
+    /** Path to the base snapshot JSON file */
+    basePath?: string;
+    /** Path to save the head snapshot */
+    outputPath?: string;
+    /** Project root directory */
+    rootDir: string;
+    /** Git commit SHA for the head snapshot */
+    commitSha?: string;
+    /** Git branch name */
+    branch?: string;
+}
+interface CompareResult {
+    diff: SnapshotDiff;
+    base: ProjectSnapshot;
+    head: ProjectSnapshot;
+}
+/**
+ * Analyze the current state, compare against a baseline, and produce a diff.
+ */
+declare function compareSnapshots(options: CompareOptions): Promise<CompareResult>;
+/**
+ * Determine if a diff has significant changes that warrant reporting.
+ */
+declare function hasSignificantChanges(diff: SnapshotDiff): boolean;
+
+export { type CheckRunOptions, type CompareOptions, type CompareResult, type GitHubConfig, type GitLabConfig, compareSnapshots, createCheckRun, detectGitHubEnv, detectGitLabEnv, generateCommentBody, hasSignificantChanges, postMRComment, postPRComment };

package/dist/index.js

@@ -0,0 +1,325 @@
+// src/github.ts
+function formatBytes(bytes) {
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  const i = Math.floor(Math.log(Math.abs(bytes)) / Math.log(1024));
+  const value = bytes / Math.pow(1024, i);
+  const sign = bytes < 0 ? "-" : "";
+  return `${sign}${Math.abs(value).toFixed(value >= 100 ? 0 : value >= 10 ? 1 : 2)} ${units[i]}`;
+}
+function detectGitHubEnv() {
+  const token = process.env["GITHUB_TOKEN"];
+  const repository = process.env["GITHUB_REPOSITORY"] ?? "";
+  const [owner, repo] = repository.split("/");
+  const eventPath = process.env["GITHUB_EVENT_PATH"];
+  let prNumber;
+  if (eventPath) {
+    try {
+      const ref = process.env["GITHUB_REF"] ?? "";
+      const match = ref.match(/refs\/pull\/(\d+)/);
+      if (match?.[1]) {
+        prNumber = parseInt(match[1], 10);
+      }
+    } catch {
+    }
+  }
+  return {
+    token,
+    owner,
+    repo,
+    prNumber,
+    apiUrl: process.env["GITHUB_API_URL"] ?? "https://api.github.com"
+  };
+}
+async function postPRComment(config, diff) {
+  const body = generateCommentBody(diff);
+  const { apiUrl = "https://api.github.com" } = config;
+  const url = `${apiUrl}/repos/${config.owner}/${config.repo}/issues/${config.prNumber}/comments`;
+  const existingCommentId = await findExistingComment(config);
+  if (existingCommentId) {
+    const updateUrl = `${apiUrl}/repos/${config.owner}/${config.repo}/issues/comments/${existingCommentId}`;
+    await fetch(updateUrl, {
+      method: "PATCH",
+      headers: {
+        Authorization: `token ${config.token}`,
+        "Content-Type": "application/json",
+        Accept: "application/vnd.github.v3+json"
+      },
+      body: JSON.stringify({ body })
+    });
+  } else {
+    await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `token ${config.token}`,
+        "Content-Type": "application/json",
+        Accept: "application/vnd.github.v3+json"
+      },
+      body: JSON.stringify({ body })
+    });
+  }
+}
+async function findExistingComment(config) {
+  const { apiUrl = "https://api.github.com" } = config;
+  const url = `${apiUrl}/repos/${config.owner}/${config.repo}/issues/${config.prNumber}/comments`;
+  const response = await fetch(url, {
+    headers: {
+      Authorization: `token ${config.token}`,
+      Accept: "application/vnd.github.v3+json"
+    }
+  });
+  if (!response.ok) return null;
+  const comments = await response.json();
+  const foxlightComment = comments.find((c) => c.body.includes("<!-- foxlight-report -->"));
+  return foxlightComment?.id ?? null;
+}
+var COMMENT_MARKER = "<!-- foxlight-report -->";
+function generateCommentBody(diff) {
+  const lines = [COMMENT_MARKER, "## \u{1F98A} Foxlight Report", ""];
+  const { added, removed, modified } = diff.components;
+  if (added.length > 0 || removed.length > 0 || modified.length > 0) {
+    lines.push("### Components", "");
+    if (added.length > 0) {
+      lines.push(
+        `\u{1F7E2} **${added.length} added:** ${added.map((c) => `\`${c.name}\``).join(", ")}`,
+        ""
+      );
+    }
+    if (removed.length > 0) {
+      lines.push(
+        `\u{1F534} **${removed.length} removed:** ${removed.map((c) => `\`${c.name}\``).join(", ")}`,
+        ""
+      );
+    }
+    if (modified.length > 0) {
+      lines.push(`\u{1F7E1} **${modified.length} modified:**`, "");
+      lines.push(...formatModifications(modified), "");
+    }
+  } else {
+    lines.push("\u2705 No component changes detected.", "");
+  }
+  if (diff.bundleDiff.length > 0) {
+    const significant = diff.bundleDiff.filter((b) => Math.abs(b.delta.gzip) > 100);
+    if (significant.length > 0) {
+      lines.push("### Bundle Size Changes", "");
+      lines.push(
+        "| Component | Before | After | Delta |",
+        "|-----------|--------|-------|-------|"
+      );
+      for (const entry of significant) {
+        lines.push(formatBundleRow(entry));
+      }
+      lines.push("");
+    }
+  }
+  if (diff.healthDiff.length > 0) {
+    const significant = diff.healthDiff.filter((h) => Math.abs(h.delta) >= 5);
+    if (significant.length > 0) {
+      lines.push("### Health Score Changes", "");
+      lines.push(
+        "| Component | Before | After | Delta |",
+        "|-----------|--------|-------|-------|"
+      );
+      for (const entry of significant) {
+        lines.push(formatHealthRow(entry));
+      }
+      lines.push("");
+    }
+  }
+  lines.push(
+    "---",
+    `*Generated by [Foxlight](https://github.com/foxlight) at ${(/* @__PURE__ */ new Date()).toISOString()}*`
+  );
+  return lines.join("\n");
+}
+function formatModifications(mods) {
+  const lines = [];
+  for (const mod of mods) {
+    const changes = [];
+    if (mod.propsAdded.length > 0) changes.push(`+${mod.propsAdded.length} props`);
+    if (mod.propsRemoved.length > 0) changes.push(`-${mod.propsRemoved.length} props`);
+    if (mod.propsModified.length > 0) changes.push(`~${mod.propsModified.length} props changed`);
+    if (mod.changes.length > 0) changes.push(...mod.changes);
+    lines.push(`  - \`${mod.componentId}\`: ${changes.join(", ")}`);
+  }
+  return lines;
+}
+function formatBundleRow(entry) {
+  const delta = entry.delta.gzip;
+  const emoji = delta > 0 ? "\u{1F53A}" : "\u{1F53D}";
+  return `| \`${entry.componentId}\` | ${formatBytes(entry.before.gzip)} | ${formatBytes(entry.after.gzip)} | ${emoji} ${formatBytes(delta)} |`;
+}
+function formatHealthRow(entry) {
+  const emoji = entry.delta > 0 ? "\u{1F4C8}" : "\u{1F4C9}";
+  return `| \`${entry.componentId}\` | ${entry.beforeScore} | ${entry.afterScore} | ${emoji} ${entry.delta > 0 ? "+" : ""}${entry.delta} |`;
+}
+async function createCheckRun(config, diff, options) {
+  const { apiUrl = "https://api.github.com" } = config;
+  const url = `${apiUrl}/repos/${config.owner}/${config.repo}/check-runs`;
+  const { conclusion, summary, annotations } = evaluateCheckResult(diff);
+  const body = {
+    name: options.name,
+    head_sha: options.headSha,
+    status: "completed",
+    conclusion,
+    output: {
+      title: "Foxlight Analysis",
+      summary,
+      text: generateCommentBody(diff),
+      annotations
+    }
+  };
+  await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `token ${config.token}`,
+      "Content-Type": "application/json",
+      Accept: "application/vnd.github.v3+json"
+    },
+    body: JSON.stringify(body)
+  });
+}
+function evaluateCheckResult(diff) {
+  const annotations = [];
+  const issues = [];
+  const { added, removed, modified } = diff.components;
+  for (const entry of diff.bundleDiff) {
+    if (entry.delta.gzip > 10240) {
+      issues.push(
+        `Bundle size regression: ${entry.componentId} grew by ${formatBytes(entry.delta.gzip)} (gzip)`
+      );
+    }
+  }
+  for (const entry of diff.healthDiff) {
+    if (entry.delta < -15) {
+      issues.push(
+        `Health regression: ${entry.componentId} dropped from ${entry.beforeScore} to ${entry.afterScore}`
+      );
+    }
+  }
+  const summaryParts = [];
+  if (added.length > 0) summaryParts.push(`${added.length} component(s) added`);
+  if (removed.length > 0) summaryParts.push(`${removed.length} component(s) removed`);
+  if (modified.length > 0) summaryParts.push(`${modified.length} component(s) modified`);
+  if (issues.length > 0) summaryParts.push(`${issues.length} issue(s) detected`);
+  const summary = summaryParts.length > 0 ? summaryParts.join(", ") : "No significant changes detected.";
+  const conclusion = issues.length > 0 ? "failure" : added.length + removed.length + modified.length > 0 ? "success" : "neutral";
+  return { conclusion, summary, annotations };
+}
+
+// src/gitlab.ts
+function detectGitLabEnv() {
+  const token = process.env["GITLAB_TOKEN"] ?? process.env["CI_JOB_TOKEN"];
+  const projectId = process.env["CI_PROJECT_ID"];
+  const apiUrl = process.env["CI_API_V4_URL"] ?? "https://gitlab.com/api/v4";
+  let mergeRequestIid;
+  const mrIid = process.env["CI_MERGE_REQUEST_IID"];
+  if (mrIid) {
+    mergeRequestIid = parseInt(mrIid, 10);
+  }
+  return {
+    token,
+    projectId,
+    mergeRequestIid,
+    apiUrl
+  };
+}
+async function postMRComment(config, diff) {
+  const body = generateCommentBody(diff);
+  const { apiUrl = "https://gitlab.com/api/v4" } = config;
+  const existingNoteId = await findExistingNote(config);
+  if (existingNoteId) {
+    const updateUrl = `${apiUrl}/projects/${encodeURIComponent(config.projectId)}/merge_requests/${config.mergeRequestIid}/notes/${existingNoteId}`;
+    await fetch(updateUrl, {
+      method: "PUT",
+      headers: {
+        "PRIVATE-TOKEN": config.token,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ body })
+    });
+  } else {
+    const url = `${apiUrl}/projects/${encodeURIComponent(config.projectId)}/merge_requests/${config.mergeRequestIid}/notes`;
+    await fetch(url, {
+      method: "POST",
+      headers: {
+        "PRIVATE-TOKEN": config.token,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ body })
+    });
+  }
+}
+async function findExistingNote(config) {
+  const { apiUrl = "https://gitlab.com/api/v4" } = config;
+  const url = `${apiUrl}/projects/${encodeURIComponent(config.projectId)}/merge_requests/${config.mergeRequestIid}/notes?sort=desc&order_by=created_at`;
+  const response = await fetch(url, {
+    headers: {
+      "PRIVATE-TOKEN": config.token
+    }
+  });
+  if (!response.ok) return null;
+  const notes = await response.json();
+  const foxlightNote = notes.find((n) => n.body.includes("<!-- foxlight-report -->"));
+  return foxlightNote?.id ?? null;
+}
+
+// src/snapshot-comparator.ts
+import { readFile, writeFile, mkdir } from "fs/promises";
+import { existsSync } from "fs";
+import { dirname } from "path";
+import { ComponentRegistry } from "@foxlight/core";
+import { analyzeProject } from "@foxlight/analyzer";
+async function compareSnapshots(options) {
+  const { rootDir, commitSha = "unknown", branch = "unknown" } = options;
+  const analysis = await analyzeProject(rootDir);
+  const head = analysis.registry.createSnapshot(commitSha, branch);
+  if (options.outputPath) {
+    const dir = dirname(options.outputPath);
+    if (!existsSync(dir)) {
+      await mkdir(dir, { recursive: true });
+    }
+    await writeFile(options.outputPath, JSON.stringify(head, null, 2));
+  }
+  let base;
+  if (options.basePath && existsSync(options.basePath)) {
+    const raw = await readFile(options.basePath, "utf-8");
+    base = JSON.parse(raw);
+  } else {
+    base = createEmptySnapshot();
+  }
+  const diff = ComponentRegistry.diff(base, head);
+  return { diff, base, head };
+}
+function createEmptySnapshot() {
+  return {
+    id: "empty",
+    commitSha: "0000000",
+    branch: "none",
+    createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+    components: [],
+    imports: [],
+    bundleInfo: [],
+    health: []
+  };
+}
+function hasSignificantChanges(diff) {
+  const { added, removed, modified } = diff.components;
+  if (added.length > 0 || removed.length > 0) return true;
+  if (modified.length > 0) return true;
+  const hasBundleChange = diff.bundleDiff.some((b) => Math.abs(b.delta.gzip) > 1024);
+  if (hasBundleChange) return true;
+  const hasHealthChange = diff.healthDiff.some((h) => Math.abs(h.delta) > 10);
+  if (hasHealthChange) return true;
+  return false;
+}
+export {
+  compareSnapshots,
+  createCheckRun,
+  detectGitHubEnv,
+  detectGitLabEnv,
+  generateCommentBody,
+  hasSignificantChanges,
+  postMRComment,
+  postPRComment
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@foxlight/ci",
+  "version": "0.1.0",
+  "description": "CI/CD integration for Foxlight — GitHub PR comments, check runs, and snapshot comparison.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch"
+  },
+  "dependencies": {
+    "@foxlight/core": "*",
+    "@foxlight/analyzer": "*"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "MIT",
+  "author": "Jose Cruz",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/josegabrielcruz/foxlight.git",
+    "directory": "packages/ci"
+  },
+  "homepage": "https://github.com/josegabrielcruz/foxlight/tree/master/packages/ci#readme",
+  "bugs": {
+    "url": "https://github.com/josegabrielcruz/foxlight/issues"
+  },
+  "keywords": [
+    "foxlight",
+    "ci",
+    "github-actions",
+    "gitlab",
+    "pr-comments"
+  ]
+}