create-ailk 0.18.0 → 0.19.0

package/templates/apps/api/src/services/__tests__/aeo-score.test.ts

@@ -1,652 +0,0 @@
-/**
- * #4666 — the instant AEO score service (D3/D4/D5).
- *
- * Dimension derivation, `lowestTwo` ordering + findings, union states, and
- * fixture loading (AC1, AC3-AC7).
- */
-import {
-  AEO_SCORE_EXCLUDED_READINESS_RULES,
-  AEO_SCORE_RULES,
-  AEO_DIMENSION_SEVERITY,
-  AEO_SCORE_DEFAULT_BUDGET_MS,
-  AEO_SCORE_MAX_BUDGET_MS,
-  resolveScoreBudgetMs,
-  scoreCrawl,
-  scoreUrl,
-  loadExampleScore,
-} from "../aeo-score";
-import {
-  aeoDimensionSchema,
-  aeoScoreResultSchema,
-} from "@working-theory/validation";
-import type { CrawlResult } from "@working-theory/aeo/fetch";
-
-/** Typed as the platform signature so it assigns to `ScoreUrlDeps.fetchImpl` with no cast. */
-type FetchStub = jest.Mock<
-  Promise<Response>,
-  [RequestInfo | URL, RequestInit?]
->;
-
-import expectedResult from "../../../../../packages/aeo/__tests__/fixtures/example-score/result.json";
-
-function page(
-  path: string,
-  type: string,
-  expectedType: string,
-  jsonLd: unknown[],
-): CrawlResult["pages"][number] {
-  return {
-    path,
-    type,
-    expectedType,
-    url: `https://example.com${path}`,
-    jsonLd,
-  };
-}
-
-/**
- * A `fetch`-shaped stub that resolves after `delayMs` with `body`, UNLESS
- * `init.signal` aborts first — mirroring how the real Fetch API honors
- * `AbortController` (the service's own `fetchPage` relies on this to make
- * its per-fetch timeout actually bound the wait; a mock that ignores the
- * signal would never let the budget win the race).
- */
-function delayedResponse(delayMs: number, body: string) {
-  return (_input: RequestInfo | URL, init?: RequestInit): Promise<Response> =>
-    new Promise((resolve, reject) => {
-      const timer = setTimeout(() => resolve(new Response(body)), delayMs);
-      init?.signal?.addEventListener("abort", () => {
-        clearTimeout(timer);
-        reject(new DOMException("Aborted", "AbortError"));
-      });
-    });
-}
-
-describe("AEO_SCORE_RULES", () => {
-  it("is exactly the four content rules — never the example/schema-correctness rules (AC4)", () => {
-    expect(AEO_SCORE_RULES.map((r) => r.id)).toEqual([
-      "schema-coverage",
-      "jsonld-validity",
-      "entity-markup",
-      "faq-howto-incentive",
-    ]);
-    expect(AEO_SCORE_RULES.map((r) => r.id)).not.toContain("always-passes");
-    expect(AEO_SCORE_RULES.map((r) => r.id)).not.toContain("always-fails");
-    expect(AEO_SCORE_RULES.map((r) => r.id)).not.toContain(
-      "schema-correctness",
-    );
-  });
-
-  it("matches the prospect-audit-site severity table verbatim", () => {
-    expect(AEO_DIMENSION_SEVERITY).toEqual({
-      "schema-coverage": "high",
-      "entity-markup": "high",
-      "jsonld-validity": "medium",
-      "faq-howto-incentive": "low",
-    });
-  });
-});
-
-describe("resolveScoreBudgetMs", () => {
-  it("defaults to 6000 when unset", () => {
-    expect(resolveScoreBudgetMs(undefined)).toBe(AEO_SCORE_DEFAULT_BUDGET_MS);
-  });
-
-  it("uses the given value when within bounds", () => {
-    expect(resolveScoreBudgetMs("8000")).toBe(8000);
-  });
-
-  it("falls back to the default and logs when above the 15000ms cap", () => {
-    const warn = jest.fn();
-    expect(resolveScoreBudgetMs("20000", { warn })).toBe(
-      AEO_SCORE_DEFAULT_BUDGET_MS,
-    );
-    expect(warn).toHaveBeenCalledTimes(1);
-    expect(warn.mock.calls[0]?.[0]).toContain(String(AEO_SCORE_MAX_BUDGET_MS));
-  });
-
-  it("falls back silently on an unparseable/non-positive value", () => {
-    const warn = jest.fn();
-    expect(resolveScoreBudgetMs("not-a-number", { warn })).toBe(
-      AEO_SCORE_DEFAULT_BUDGET_MS,
-    );
-    expect(resolveScoreBudgetMs("-5", { warn })).toBe(
-      AEO_SCORE_DEFAULT_BUDGET_MS,
-    );
-    expect(warn).not.toHaveBeenCalled();
-  });
-});
-
-describe("scoreCrawl", () => {
-  it("returns unavailable/no_pages_fetched for an empty crawl", () => {
-    const crawl: CrawlResult = {
-      base: "https://example.com",
-      pages: [],
-      skipped: [],
-    };
-    const result = scoreCrawl(crawl);
-    expect(result).toEqual({
-      status: "unavailable",
-      reason: "no_pages_fetched",
-      message: "No pages were fetched.",
-    });
-  });
-
-  it("(AC5) lowestTwo is [schema-coverage(high), entity-markup(high)] when every page fails those two and one fails jsonld-validity", () => {
-    const crawl: CrawlResult = {
-      base: "https://example.com",
-      pages: [
-        page("/", "homepage", "HomePage", []), // no JSON-LD at all — fails coverage + entity
-        page("/about", "about", "AboutPage", [
-          { "@type": "WebPage", name: "About" }, // wrong type, malformed-ish (missing recommended fields is fine)
-        ]),
-      ],
-      skipped: [],
-    };
-    const result = scoreCrawl(crawl);
-    if (result.status !== "ready") throw new Error("expected ready");
-    const ids = result.lowestTwo.map((d) => d.id);
-    expect(ids).toContain("schema-coverage");
-    expect(ids).toContain("entity-markup");
-    const sc = result.dimensions.find((d) => d.id === "schema-coverage");
-    expect(sc?.severity).toBe("high");
-  });
-
-  it("(AC5) faq-howto-incentive scores 0, enters lowestTwo, and carries the fixed opportunity finding when no page has FAQ/HowTo markup", () => {
-    const crawl: CrawlResult = {
-      base: "https://example.com",
-      pages: [
-        page("/", "homepage", "HomePage", [
-          { "@type": "HomePage", name: "Home", url: "https://example.com" },
-          { "@type": "Organization", name: "Example Co" },
-        ]),
-      ],
-      skipped: [],
-    };
-    const result = scoreCrawl(crawl);
-    if (result.status !== "ready") throw new Error("expected ready");
-    const faq = result.dimensions.find((d) => d.id === "faq-howto-incentive");
-    expect(faq?.score).toBe(0);
-    expect(faq?.finding).toMatch(/no FAQPage or HowTo structured data/);
-    expect(faq?.finding).toMatch(/a visibility opportunity, not a defect/);
-    expect(result.lowestTwo.map((d) => d.id)).toContain("faq-howto-incentive");
-  });
-
-  it("sets meta.partial true when a page was skipped for budget_exceeded", () => {
-    const crawl: CrawlResult = {
-      base: "https://example.com",
-      pages: [
-        page("/", "homepage", "HomePage", [
-          { "@type": "HomePage", name: "Home" },
-        ]),
-      ],
-      skipped: [
-        {
-          path: "/about",
-          url: "https://example.com/about",
-          reason: "budget_exceeded",
-        },
-      ],
-    };
-    const result = scoreCrawl(crawl);
-    if (result.status !== "ready") throw new Error("expected ready");
-    expect(result.meta.partial).toBe(true);
-    expect(result.meta.skipped).toHaveLength(1);
-  });
-
-  it("result satisfies aeoScoreResultSchema (AC7)", () => {
-    const crawl: CrawlResult = {
-      base: "https://example.com",
-      pages: [
-        page("/", "homepage", "HomePage", [
-          { "@type": "HomePage", name: "Home" },
-        ]),
-      ],
-      skipped: [],
-    };
-    const result = scoreCrawl(crawl);
-    expect(() => aeoScoreResultSchema.parse(result)).not.toThrow();
-  });
-
-  // AILK #5110 — mirrors the #4707 fix for the top-level unavailable/
-  // ssrf_blocked path: the per-path SSRF-guard rejection detail
-  // (assertUrlSafe's raw `reason`, which can disclose a resolved internal
-  // host/IP) must never reach a ready response's meta.skipped[].reason.
-  describe("meta.skipped[].reason SSRF-guard scrub (#5110)", () => {
-    let warnSpy: jest.SpyInstance;
-
-    beforeEach(() => {
-      warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
-    });
-
-    afterEach(() => {
-      warnSpy.mockRestore();
-    });
-
-    it("redacts a raw assertUrlSafe rejection reason to the ssrf_blocked sentinel", () => {
-      const crawl: CrawlResult = {
-        base: "https://example.com",
-        pages: [
-          page("/", "homepage", "HomePage", [
-            { "@type": "HomePage", name: "Home" },
-          ]),
-        ],
-        skipped: [
-          {
-            path: "/admin",
-            url: "http://169.254.169.254/admin",
-            reason:
-              "Host 169.254.169.254 resolves to a blocked address: 169.254.169.254",
-          },
-        ],
-      };
-      const result = scoreCrawl(crawl);
-      if (result.status !== "ready") throw new Error("expected ready");
-      expect(result.meta.skipped).toHaveLength(1);
-      expect(result.meta.skipped[0]?.reason).toBe("ssrf_blocked");
-      expect(result.meta.skipped[0]?.reason).not.toMatch(/169\.254\.169\.254/);
-      expect(result.meta.skipped[0]?.reason).not.toMatch(
-        /resolves to a blocked address/i,
-      );
-    });
-
-    it("(AC-2) logs the raw per-path rejection detail server-side before redacting it", () => {
-      const crawl: CrawlResult = {
-        base: "https://example.com",
-        pages: [
-          page("/", "homepage", "HomePage", [
-            { "@type": "HomePage", name: "Home" },
-          ]),
-        ],
-        skipped: [
-          {
-            path: "/admin",
-            url: "http://169.254.169.254/admin",
-            reason:
-              "Host 169.254.169.254 resolves to a blocked address: 169.254.169.254",
-          },
-        ],
-      };
-      scoreCrawl(crawl);
-      expect(warnSpy).toHaveBeenCalledTimes(1);
-      const [message, meta] = warnSpy.mock.calls[0] as [
-        string,
-        Record<string, unknown>,
-      ];
-      expect(message).toMatch(/aeo-score/);
-      expect(meta).toMatchObject({
-        path: "/admin",
-        url: "http://169.254.169.254/admin",
-        reason:
-          "Host 169.254.169.254 resolves to a blocked address: 169.254.169.254",
-      });
-    });
-
-    it("leaves a non-SSRF skip reason (budget_exceeded, an HTTP failure) unchanged", () => {
-      const crawl: CrawlResult = {
-        base: "https://example.com",
-        pages: [
-          page("/", "homepage", "HomePage", [
-            { "@type": "HomePage", name: "Home" },
-          ]),
-        ],
-        skipped: [
-          {
-            path: "/about",
-            url: "https://example.com/about",
-            reason: "budget_exceeded",
-          },
-          {
-            path: "/blog",
-            url: "https://example.com/blog",
-            reason: "HTTP 404: https://example.com/blog",
-          },
-        ],
-      };
-      const result = scoreCrawl(crawl);
-      if (result.status !== "ready") throw new Error("expected ready");
-      expect(result.meta.skipped).toEqual([
-        {
-          path: "/about",
-          url: "https://example.com/about",
-          reason: "budget_exceeded",
-        },
-        {
-          path: "/blog",
-          url: "https://example.com/blog",
-          reason: "HTTP 404: https://example.com/blog",
-        },
-      ]);
-      expect(warnSpy).not.toHaveBeenCalled();
-    });
-
-    it("end-to-end via scoreUrl: a path blocked mid-crawl (simulated DNS rebinding) never surfaces its raw reason on a ready result", async () => {
-      let calls = 0;
-      const resolver = async () => {
-        calls += 1;
-        // Call 1 is scoreUrl's own top-level pre-flight assertUrlSafe check;
-        // call 2 is crawlSite's first per-path re-check (whichever path
-        // processOne reaches first) — both resolve safely. Every subsequent
-        // per-path call — standing in for DNS rebinding mid-crawl —
-        // resolves to an internal address, so at least one page succeeds
-        // and at least one is SSRF-skipped.
-        return calls <= 2 ? ["93.184.216.34"] : ["10.1.2.3"];
-      };
-      const fetchImpl: FetchStub = jest.fn(
-        async () =>
-          new Response(
-            '<html><script type="application/ld+json">{"@type":"HomePage","name":"Home"}</script></html>',
-          ),
-      );
-
-      const result = await scoreUrl("https://example.com", {
-        fetchImpl,
-        resolver,
-      });
-
-      if (result.status !== "ready") {
-        throw new Error(`expected ready, got ${JSON.stringify(result)}`);
-      }
-      expect(result.meta.skipped.length).toBeGreaterThan(0);
-      for (const skip of result.meta.skipped) {
-        expect(skip.reason).toBe("ssrf_blocked");
-        expect(skip.reason).not.toMatch(/10\.1\.2\.3/);
-        expect(skip.reason).not.toMatch(/resolves to a blocked address/i);
-      }
-    });
-  });
-});
-
-describe("aeoScoreResultSchema (AC7)", () => {
-  it("parses ready, computing, and each unavailable reason", () => {
-    expect(() =>
-      aeoScoreResultSchema.parse({
-        status: "ready",
-        score: 50,
-        dimensions: [
-          {
-            id: "schema-coverage",
-            label: "x",
-            weight: 10,
-            score: 50,
-            severity: "high",
-            finding: null,
-            pagesPassing: 1,
-            pagesTotal: 2,
-          },
-          {
-            id: "jsonld-validity",
-            label: "x",
-            weight: 10,
-            score: 50,
-            severity: "medium",
-            finding: null,
-            pagesPassing: 1,
-            pagesTotal: 2,
-          },
-          {
-            id: "entity-markup",
-            label: "x",
-            weight: 1,
-            score: 50,
-            severity: "high",
-            finding: null,
-            pagesPassing: 1,
-            pagesTotal: 2,
-          },
-          {
-            id: "faq-howto-incentive",
-            label: "x",
-            weight: 0,
-            score: 50,
-            severity: "low",
-            finding: null,
-            pagesPassing: 1,
-            pagesTotal: 2,
-          },
-        ],
-        lowestTwo: [
-          {
-            id: "schema-coverage",
-            label: "x",
-            weight: 10,
-            score: 50,
-            severity: "high",
-            finding: null,
-            pagesPassing: 1,
-            pagesTotal: 2,
-          },
-          {
-            id: "entity-markup",
-            label: "x",
-            weight: 1,
-            score: 50,
-            severity: "high",
-            finding: null,
-            pagesPassing: 1,
-            pagesTotal: 2,
-          },
-        ],
-        meta: {
-          auditedAt: new Date().toISOString(),
-          pagesAudited: 2,
-          partial: false,
-          skipped: [],
-          schemaVersion: "1.0.0",
-          registryVersion: "1.0.0",
-        },
-      }),
-    ).not.toThrow();
-
-    expect(() =>
-      aeoScoreResultSchema.parse({ status: "computing" }),
-    ).not.toThrow();
-
-    for (const reason of [
-      "ssrf_blocked",
-      "no_pages_fetched",
-      "crawl_failed",
-    ] as const) {
-      expect(() =>
-        aeoScoreResultSchema.parse({
-          status: "unavailable",
-          reason,
-          message: "x",
-        }),
-      ).not.toThrow();
-    }
-  });
-
-  it("rejects a status that mixes an unavailable discriminant with a ready-only field name absent from the schema", () => {
-    const parsed = aeoScoreResultSchema.safeParse({
-      status: "unavailable",
-      // missing required `reason` / `message` — the mixed/malformed shape.
-      score: 50,
-    });
-    expect(parsed.success).toBe(false);
-  });
-});
-
-describe("scoreUrl", () => {
-  it("returns unavailable/ssrf_blocked without ever calling fetch, for a blocked host", async () => {
-    const fetchImpl: FetchStub = jest.fn();
-    const result = await scoreUrl("http://127.0.0.1/", { fetchImpl });
-    expect(result).toEqual({
-      status: "unavailable",
-      reason: "ssrf_blocked",
-      message: expect.stringMatching(/Blocked host/i),
-    });
-    expect(fetchImpl).not.toHaveBeenCalled();
-  });
-
-  it("(AC1) issues the five default paths concurrently — a 2s-delay fetchImpl completes well under 10s", async () => {
-    const fetchImpl: FetchStub = jest.fn(async () => {
-      await new Promise((resolve) => setTimeout(resolve, 2000));
-      return new Response(
-        '<html><script type="application/ld+json">{"@type":"HomePage","name":"x"}</script></html>',
-      );
-    });
-
-    const t0 = Date.now();
-    const result = await scoreUrl("https://example.com", {
-      fetchImpl,
-      resolver: async () => ["93.184.216.34"],
-    });
-    const elapsed = Date.now() - t0;
-
-    expect(elapsed).toBeLessThan(5000);
-    expect(result.status).toBe("ready");
-  }, 10_000);
-
-  it("(AC1) with budgetMs 500 and a 2s-delay fetchImpl, returns quickly as unavailable/no_pages_fetched", async () => {
-    const fetchImpl: FetchStub = jest.fn(
-      delayedResponse(2000, "<html></html>"),
-    );
-
-    const t0 = Date.now();
-    const result = await scoreUrl("https://example.com", {
-      fetchImpl,
-      resolver: async () => ["93.184.216.34"],
-      budgetMs: 500,
-    });
-    const elapsed = Date.now() - t0;
-
-    // Spec AC1: "returns inside ~600 ms" — tight enough to prove the abort
-    // actually fired at the 500ms budget rather than merely finishing
-    // before the 2000ms fetchImpl delay or the 10s jest timeout.
-    expect(elapsed).toBeLessThan(1000);
-    expect(result).toEqual({
-      status: "unavailable",
-      reason: "no_pages_fetched",
-      message: expect.any(String),
-    });
-  }, 10_000);
-
-  it("(AC1) one fast + four slow pages returns ready with meta.partial true and budget_exceeded skips", async () => {
-    const homeResponse = delayedResponse(
-      0,
-      '<html><script type="application/ld+json">{"@type":"HomePage","name":"x"}</script></html>',
-    );
-    const slowResponse = delayedResponse(5000, "<html></html>");
-    const fetchImpl: FetchStub = jest.fn(
-      (input: RequestInfo | URL, init?: RequestInit) => {
-        const isHome = String(input).endsWith("example.com/");
-        return isHome ? homeResponse(input, init) : slowResponse(input, init);
-      },
-    );
-
-    const result = await scoreUrl("https://example.com", {
-      fetchImpl,
-      resolver: async () => ["93.184.216.34"],
-      budgetMs: 800,
-    });
-
-    if (result.status !== "ready")
-      throw new Error(`expected ready, got ${JSON.stringify(result)}`);
-    expect(result.meta.partial).toBe(true);
-    // Spec AC1: one fast + FOUR slow pages — all four abort at the budget.
-    expect(
-      result.meta.skipped.filter((s) => s.reason === "budget_exceeded").length,
-    ).toBe(4);
-    expect(result.meta.pagesAudited).toBe(1);
-  }, 10_000);
-
-  it("returns a well-formed unavailable result (never a rejected promise) when a per-page fetch throws", async () => {
-    const fetchImpl: FetchStub = jest.fn(() => {
-      throw new Error("boom");
-    });
-    const result = await scoreUrl("https://example.com", {
-      fetchImpl,
-      resolver: async () => ["93.184.216.34"],
-    });
-    // A per-page fetch throw is caught INSIDE crawlSite as a skipped page, not
-    // a crawlSite-level throw — so this surfaces as no_pages_fetched.
-    expect(result).toEqual({
-      status: "unavailable",
-      reason: "no_pages_fetched",
-      message: expect.any(String),
-    });
-  });
-});
-
-describe("loadExampleScore (AC6, D6)", () => {
-  it("returns a ready result with meta.example true, sourceUrl set, and a non-empty annotation on every dimension — no fs on the request path", () => {
-    const result = loadExampleScore();
-    expect(result.status).toBe("ready");
-    if (result.status !== "ready") return;
-    expect(result.meta.example).toBe(true);
-    expect(result.meta.sourceUrl).toBe("https://ailaunchkit.ai");
-    for (const d of result.dimensions) {
-      expect(typeof d.annotation).toBe("string");
-      expect((d.annotation ?? "").length).toBeGreaterThan(0);
-    }
-  });
-
-  it("(acceptance-review finding) surfaces meta.illustrative on the wire — today's hand-authored fixture is not a genuine crawl of sourceUrl", () => {
-    const result = loadExampleScore();
-    if (result.status !== "ready") throw new Error("expected ready");
-    // Sourced from EXAMPLE_SCORE_META, not hardcoded — flips to false the
-    // moment the fixture is regenerated from a real crawl.
-    expect(result.meta.illustrative).toBe(true);
-    expect(() => aeoScoreResultSchema.parse(result)).not.toThrow();
-  });
-
-  it("deep-equals the committed fixture (minus auditedAt, plus annotations/meta) — proves the service's rule set never diverges from the generator's", () => {
-    const result = loadExampleScore();
-    if (result.status !== "ready") throw new Error("expected ready");
-    const { auditedAt: _auditedAt, ...metaWithoutAuditedAt } = result.meta;
-    void _auditedAt;
-    const stripAnnotation = (d: (typeof result.dimensions)[number]) => {
-      const { annotation: _annotation, ...rest } = d;
-      void _annotation;
-      return rest;
-    };
-    expect({
-      status: result.status,
-      score: result.score,
-      dimensions: result.dimensions.map(stripAnnotation),
-      lowestTwo: result.lowestTwo.map(stripAnnotation),
-      meta: {
-        pagesAudited: metaWithoutAuditedAt.pagesAudited,
-        partial: metaWithoutAuditedAt.partial,
-        skipped: metaWithoutAuditedAt.skipped,
-        schemaVersion: metaWithoutAuditedAt.schemaVersion,
-        registryVersion: metaWithoutAuditedAt.registryVersion,
-      },
-    }).toEqual(expectedResult);
-  });
-});
-
-/**
- * #5949 D6/FR11 — the readiness rules are deliberately NOT in this service's
- * rule set. They grade frontmatter and site-set facts, and `buildAuditPayload`
- * produces no frontmatter, so on a crawl input all three would pass vacuously:
- * three always-100 dimensions in a closed four-member public enum.
- *
- * `/v1/aeo/score` has no MCP twin (apps/api/CLAUDE.md § API ↔ MCP parity), so
- * the skip is not a parity divergence — and these assertions are the "stated
- * and tested" half AC-3 asks for, failing loudly if either side drifts.
- */
-describe("readiness-rule exclusion (#5949 D6)", () => {
-  it("AEO_SCORE_RULES carries none of the excluded readiness rules", () => {
-    const ids = AEO_SCORE_RULES.map((r) => r.id);
-    for (const excluded of AEO_SCORE_EXCLUDED_READINESS_RULES) {
-      expect(ids).not.toContain(excluded);
-    }
-  });
-
-  it("the public dimension enum is still exactly the four content rules", () => {
-    expect([...aeoDimensionSchema.shape.id.options].sort()).toEqual([
-      "entity-markup",
-      "faq-howto-incentive",
-      "jsonld-validity",
-      "schema-coverage",
-    ]);
-  });
-
-  it("AEO_SCORE_RULES' ids are exactly the dimension enum's options", () => {
-    expect(AEO_SCORE_RULES.map((r) => r.id).sort()).toEqual(
-      [...aeoDimensionSchema.shape.id.options].sort(),
-    );
-  });
-});