install-glo 2.0.1 → 2.0.2

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+## 2.0.2
+
+- Refactor glo-loop monolith (675 LOC) into 6 focused modules under `lib/`
+  - `vitals.mjs` — Web Vitals constants and thresholds
+  - `lighthouse.mjs` — Lighthouse runner, metric/diagnostic extraction
+  - `source-discovery.mjs` — Page file and component import discovery
+  - `ai-analysis.mjs` — AI prompt construction and analysis
+  - `model.mjs` — Provider selection (Anthropic/OpenAI)
+  - `display.mjs` — Terminal output formatting
+- Add 36 unit tests using `node:test` with dependency injection
+- Fix duplicate file discovery bug for root route candidates
+- Add `npm test` script
+
+## 2.0.1
+
+- Add missing `zod` dependency
+
+## 2.0.0
+
+- Rewrite as GLO Loop — AI-powered web vitals optimization engine
+- Built on Vercel AI SDK with Anthropic and OpenAI support
+- Interactive Lighthouse → AI analysis → fix loop
+- Source file discovery for Next.js App/Pages Router
+- Support for LCP, FCP, CLS, TBT, SI, TTFB targets
+
+## 1.0.0
+
+- Initial release

package/__tests__/ai-analysis.test.mjs

@@ -0,0 +1,108 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { analyzeWithAI, buildPrompt } from "../lib/ai-analysis.mjs";
+
+describe("buildPrompt", () => {
+  const baseMetrics = {
+    LCP: { value: 3200, display: "3.2 s", score: 0 },
+    FCP: { value: 1500, display: "1.5 s", score: 1 },
+    performanceScore: 72,
+  };
+
+  it("includes target vital and current value", () => {
+    const prompt = buildPrompt("LCP", baseMetrics, [], [], 1, []);
+    assert.ok(prompt.includes("LCP"));
+    assert.ok(prompt.includes("3200ms"));
+    assert.ok(prompt.includes("Largest Contentful Paint"));
+  });
+
+  it("includes performance score", () => {
+    const prompt = buildPrompt("LCP", baseMetrics, [], [], 1, []);
+    assert.ok(prompt.includes("72/100"));
+  });
+
+  it("includes diagnostics", () => {
+    const diags = [
+      { title: "Remove unused JS", displayValue: "200 KiB", score: 0.3 },
+    ];
+    const prompt = buildPrompt("LCP", baseMetrics, diags, [], 1, []);
+    assert.ok(prompt.includes("Remove unused JS"));
+    assert.ok(prompt.includes("200 KiB"));
+  });
+
+  it("includes source file contents", () => {
+    const files = [{ path: "app/page.tsx", content: "<Hero />" }];
+    const prompt = buildPrompt("LCP", baseMetrics, [], files, 1, []);
+    assert.ok(prompt.includes("app/page.tsx"));
+    assert.ok(prompt.includes("<Hero />"));
+  });
+
+  it("includes previous suggestions context", () => {
+    const prev = ["DIAGNOSIS: images not optimized"];
+    const prompt = buildPrompt("LCP", baseMetrics, [], [], 2, prev);
+    assert.ok(prompt.includes("Previous suggestions already applied"));
+    assert.ok(prompt.includes("images not optimized"));
+    assert.ok(prompt.includes("Do NOT repeat"));
+  });
+
+  it("handles CLS (unitless) correctly", () => {
+    const metrics = {
+      CLS: { value: 0.25, display: "0.25", score: 0 },
+      performanceScore: 60,
+    };
+    const prompt = buildPrompt("CLS", metrics, [], [], 1, []);
+    assert.ok(prompt.includes("0.250"));
+    assert.ok(prompt.includes("<0.1"));
+  });
+
+  it("handles missing target vital value gracefully", () => {
+    const metrics = { performanceScore: 50 };
+    const prompt = buildPrompt("LCP", metrics, [], [], 1, []);
+    assert.ok(prompt.includes("unknown"));
+  });
+});
+
+describe("analyzeWithAI", () => {
+  it("calls generateText with model and prompt", async () => {
+    let capturedArgs;
+    const fakeGenerateText = async (args) => {
+      capturedArgs = args;
+      return { text: "DIAGNOSIS: test response" };
+    };
+
+    const fakeModel = { id: "fake-model" };
+    const metrics = {
+      LCP: { value: 3200, display: "3.2 s", score: 0 },
+      performanceScore: 72,
+    };
+
+    const result = await analyzeWithAI(
+      fakeModel,
+      "LCP",
+      metrics,
+      [],
+      [],
+      1,
+      [],
+      { generateText: fakeGenerateText }
+    );
+
+    assert.equal(result, "DIAGNOSIS: test response");
+    assert.equal(capturedArgs.model, fakeModel);
+    assert.ok(capturedArgs.prompt.includes("LCP"));
+  });
+
+  it("propagates errors from generateText", async () => {
+    const fakeGenerateText = async () => {
+      throw new Error("API down");
+    };
+
+    await assert.rejects(
+      () =>
+        analyzeWithAI({}, "LCP", { performanceScore: 0 }, [], [], 1, [], {
+          generateText: fakeGenerateText,
+        }),
+      { message: "API down" }
+    );
+  });
+});

package/__tests__/lighthouse.test.mjs

@@ -0,0 +1,192 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  checkLighthouse,
+  runLighthouse,
+  extractMetrics,
+  extractDiagnostics,
+} from "../lib/lighthouse.mjs";
+
+// ── Fixtures ──────────────────────────────────────────────────────────
+
+function makeLighthouseReport({
+  perfScore = 0.72,
+  lcp = 3200,
+  fcp = 1500,
+  cls = 0.05,
+  tbt = 300,
+  si = 4000,
+  ttfb = 600,
+  diagnostics = {},
+} = {}) {
+  return {
+    categories: { performance: { score: perfScore } },
+    audits: {
+      "largest-contentful-paint": {
+        numericValue: lcp,
+        displayValue: `${(lcp / 1000).toFixed(1)} s`,
+        score: lcp <= 2500 ? 1 : 0,
+      },
+      "first-contentful-paint": {
+        numericValue: fcp,
+        displayValue: `${(fcp / 1000).toFixed(1)} s`,
+        score: fcp <= 1800 ? 1 : 0,
+      },
+      "cumulative-layout-shift": {
+        numericValue: cls,
+        displayValue: cls.toFixed(3),
+        score: cls <= 0.1 ? 1 : 0,
+      },
+      "total-blocking-time": {
+        numericValue: tbt,
+        displayValue: `${tbt} ms`,
+        score: tbt <= 200 ? 1 : 0,
+      },
+      "speed-index": {
+        numericValue: si,
+        displayValue: `${(si / 1000).toFixed(1)} s`,
+        score: si <= 3400 ? 1 : 0,
+      },
+      "server-response-time": {
+        numericValue: ttfb,
+        displayValue: `${ttfb} ms`,
+        score: ttfb <= 800 ? 1 : 0,
+      },
+      ...diagnostics,
+    },
+  };
+}
+
+// ── checkLighthouse ───────────────────────────────────────────────────
+
+describe("checkLighthouse", () => {
+  it("returns true when lighthouse is available", () => {
+    const execSync = () => "10.0.0";
+    assert.equal(checkLighthouse({ execSync }), true);
+  });
+
+  it("returns false when lighthouse throws", () => {
+    const execSync = () => {
+      throw new Error("not found");
+    };
+    assert.equal(checkLighthouse({ execSync }), false);
+  });
+});
+
+// ── runLighthouse ─────────────────────────────────────────────────────
+
+describe("runLighthouse", () => {
+  it("parses JSON output from execSync", () => {
+    const fakeReport = { categories: {}, audits: {} };
+    const execSync = () => Buffer.from(JSON.stringify(fakeReport));
+    const result = runLighthouse("http://localhost:3000", { execSync });
+    assert.deepStrictEqual(result, fakeReport);
+  });
+
+  it("passes the URL into the command", () => {
+    let capturedCmd;
+    const execSync = (cmd) => {
+      capturedCmd = cmd;
+      return Buffer.from("{}");
+    };
+    runLighthouse("http://example.com", { execSync });
+    assert.ok(capturedCmd.includes('"http://example.com"'));
+  });
+
+  it("throws on invalid JSON", () => {
+    const execSync = () => Buffer.from("not json");
+    assert.throws(() => runLighthouse("http://localhost:3000", { execSync }));
+  });
+});
+
+// ── extractMetrics ────────────────────────────────────────────────────
+
+describe("extractMetrics", () => {
+  it("extracts all six vitals from a report", () => {
+    const report = makeLighthouseReport();
+    const metrics = extractMetrics(report);
+
+    assert.equal(metrics.LCP.value, 3200);
+    assert.equal(metrics.FCP.value, 1500);
+    assert.equal(metrics.CLS.value, 0.05);
+    assert.equal(metrics.TBT.value, 300);
+    assert.equal(metrics.SI.value, 4000);
+    assert.equal(metrics.TTFB.value, 600);
+  });
+
+  it("computes performanceScore as percentage", () => {
+    const report = makeLighthouseReport({ perfScore: 0.85 });
+    const metrics = extractMetrics(report);
+    assert.equal(metrics.performanceScore, 85);
+  });
+
+  it("defaults performanceScore to 0 when missing", () => {
+    const report = { audits: {}, categories: {} };
+    const metrics = extractMetrics(report);
+    assert.equal(metrics.performanceScore, 0);
+  });
+
+  it("skips audits that are missing", () => {
+    const report = { audits: {}, categories: { performance: { score: 0.5 } } };
+    const metrics = extractMetrics(report);
+    assert.equal(metrics.LCP, undefined);
+    assert.equal(metrics.performanceScore, 50);
+  });
+});
+
+// ── extractDiagnostics ────────────────────────────────────────────────
+
+describe("extractDiagnostics", () => {
+  it("returns failing audits sorted worst-first", () => {
+    const report = makeLighthouseReport({
+      diagnostics: {
+        "unused-javascript": {
+          title: "Remove unused JavaScript",
+          displayValue: "200 KiB",
+          score: 0.3,
+        },
+        "render-blocking-resources": {
+          title: "Eliminate render-blocking resources",
+          displayValue: "1,200 ms",
+          score: 0.1,
+        },
+      },
+    });
+    const diags = extractDiagnostics(report);
+    assert.ok(diags.length >= 2);
+    assert.equal(diags[0].id, "render-blocking-resources");
+    assert.equal(diags[1].id, "unused-javascript");
+  });
+
+  it("excludes audits with score === 1 (passing)", () => {
+    const report = makeLighthouseReport({
+      diagnostics: {
+        "dom-size": { title: "DOM size", score: 1, displayValue: "" },
+      },
+    });
+    const diags = extractDiagnostics(report);
+    const domSize = diags.find((d) => d.id === "dom-size");
+    assert.equal(domSize, undefined);
+  });
+
+  it("excludes audits with score === null", () => {
+    const report = makeLighthouseReport({
+      diagnostics: {
+        "font-display": {
+          title: "Font display",
+          score: null,
+          displayValue: "",
+        },
+      },
+    });
+    const diags = extractDiagnostics(report);
+    const fontDisplay = diags.find((d) => d.id === "font-display");
+    assert.equal(fontDisplay, undefined);
+  });
+
+  it("returns empty array for clean report", () => {
+    const report = { audits: {} };
+    const diags = extractDiagnostics(report);
+    assert.deepStrictEqual(diags, []);
+  });
+});

package/__tests__/model.test.mjs

@@ -0,0 +1,59 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { getModel } from "../lib/model.mjs";
+
+describe("getModel", () => {
+  it("returns Anthropic model when ANTHROPIC_API_KEY is set", () => {
+    const fakeModel = { id: "claude" };
+    const createAnthropic = () => () => fakeModel;
+    const createOpenAI = () => () => ({ id: "gpt" });
+
+    const result = getModel({
+      env: { ANTHROPIC_API_KEY: "sk-ant-test" },
+      createAnthropic,
+      createOpenAI,
+    });
+
+    assert.equal(result.model, fakeModel);
+    assert.equal(result.label, "Claude (Anthropic)");
+  });
+
+  it("falls back to OpenAI when only OPENAI_API_KEY is set", () => {
+    const fakeModel = { id: "gpt" };
+    const createAnthropic = () => () => ({ id: "claude" });
+    const createOpenAI = () => () => fakeModel;
+
+    const result = getModel({
+      env: { OPENAI_API_KEY: "sk-test" },
+      createAnthropic,
+      createOpenAI,
+    });
+
+    assert.equal(result.model, fakeModel);
+    assert.equal(result.label, "GPT-4o-mini (OpenAI)");
+  });
+
+  it("prefers Anthropic when both keys are set", () => {
+    const claudeModel = { id: "claude" };
+    const createAnthropic = () => () => claudeModel;
+    const createOpenAI = () => () => ({ id: "gpt" });
+
+    const result = getModel({
+      env: { ANTHROPIC_API_KEY: "sk-ant-test", OPENAI_API_KEY: "sk-test" },
+      createAnthropic,
+      createOpenAI,
+    });
+
+    assert.equal(result.model, claudeModel);
+  });
+
+  it("returns null when no API keys are set", () => {
+    const result = getModel({
+      env: {},
+      createAnthropic: () => () => ({}),
+      createOpenAI: () => () => ({}),
+    });
+
+    assert.equal(result, null);
+  });
+});

package/__tests__/source-discovery.test.mjs

@@ -0,0 +1,78 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { discoverPageFiles } from "../lib/source-discovery.mjs";
+
+function makeFs(fileMap) {
+  return {
+    existsSync: (path) => path in fileMap,
+    readFileSync: (path) => {
+      if (!(path in fileMap)) throw new Error(`ENOENT: ${path}`);
+      return fileMap[path];
+    },
+  };
+}
+
+describe("discoverPageFiles", () => {
+  it("finds App Router page.tsx for root route", () => {
+    const fs = makeFs({
+      "/project/app/page.tsx": "export default function Home() {}",
+      "/project/app/layout.tsx": "<html>{children}</html>",
+    });
+    const files = discoverPageFiles("/project", "/", fs);
+    assert.ok(files.length >= 2);
+    assert.equal(files[0].path, "app/page.tsx");
+  });
+
+  it("finds Pages Router file for named route", () => {
+    const fs = makeFs({
+      "/project/pages/about.tsx": "export default function About() {}",
+    });
+    const files = discoverPageFiles("/project", "/about", fs);
+    assert.equal(files.length, 1);
+    assert.equal(files[0].path, "pages/about.tsx");
+  });
+
+  it("returns empty array when no files match", () => {
+    const fs = makeFs({});
+    const files = discoverPageFiles("/project", "/", fs);
+    assert.deepStrictEqual(files, []);
+  });
+
+  it("truncates large files", () => {
+    const bigContent = "x".repeat(20_000);
+    const fs = makeFs({
+      "/project/app/page.tsx": bigContent,
+    });
+    const files = discoverPageFiles("/project", "/", fs);
+    assert.ok(files[0].content.length < bigContent.length);
+    assert.ok(files[0].content.endsWith("// ... truncated"));
+  });
+
+  it("resolves relative imports from page file", () => {
+    const fs = makeFs({
+      "/project/app/page.tsx": 'import Hero from "./components/Hero";\nexport default function Home() {}',
+      "/project/app/components/Hero.tsx": "export default function Hero() {}",
+    });
+    const files = discoverPageFiles("/project", "/", fs);
+    const hero = files.find((f) => f.path.includes("Hero"));
+    assert.ok(hero, "should discover imported Hero component");
+  });
+
+  it("does not duplicate already-discovered files", () => {
+    const fs = makeFs({
+      "/project/app/page.tsx": 'import Layout from "./layout";\nexport default function Home() {}',
+      "/project/app/layout.tsx": "export default function Layout() {}",
+    });
+    const files = discoverPageFiles("/project", "/", fs);
+    const layouts = files.filter((f) => f.path === "app/layout.tsx");
+    assert.equal(layouts.length, 1);
+  });
+
+  it("discovers next.config.js when present", () => {
+    const fs = makeFs({
+      "/project/next.config.js": "module.exports = { images: {} }",
+    });
+    const files = discoverPageFiles("/project", "/", fs);
+    assert.ok(files.find((f) => f.path === "next.config.js"));
+  });
+});

package/__tests__/vitals.test.mjs

@@ -0,0 +1,24 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { VITALS } from "../lib/vitals.mjs";
+
+describe("VITALS", () => {
+  it("has all six core web vitals", () => {
+    const keys = Object.keys(VITALS);
+    assert.deepStrictEqual(keys, ["LCP", "FCP", "CLS", "TBT", "SI", "TTFB"]);
+  });
+
+  it("each vital has required fields", () => {
+    for (const [key, info] of Object.entries(VITALS)) {
+      assert.ok(typeof info.good === "number", `${key}.good should be a number`);
+      assert.ok(typeof info.unit === "string", `${key}.unit should be a string`);
+      assert.ok(typeof info.name === "string", `${key}.name should be a string`);
+      assert.ok(typeof info.audit === "string", `${key}.audit should be a string`);
+    }
+  });
+
+  it("CLS threshold is sub-1 (unitless)", () => {
+    assert.equal(VITALS.CLS.unit, "");
+    assert.ok(VITALS.CLS.good < 1);
+  });
+});