@axiapps/gw2-data 0.1.0

package/tests/validate-live.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * Live validation script — fetches real GW2 API + wiki data and validates
+ * that our parser + merger produce correct results.
+ *
+ * This is NOT a test file. Run it manually to spot-check against live data:
+ *
+ *   node packages/gw2-data/tests/validate-live.js
+ *   node packages/gw2-data/tests/validate-live.js --ids 5489,30185
+ *   node packages/gw2-data/tests/validate-live.js --type traits --ids 264,1510
+ *
+ * Exits with code 1 if any validation fails.
+ */
+
+const { WikiClient } = require("../src/wiki/client");
+const { Gw2ApiClient } = require("../src/api/client");
+const { MemoryCache } = require("../src/wiki/cache");
+const { mergeFacts } = require("../src/facts/merge");
+const { normalizeFactType } = require("../src/facts/normalize");
+
+const GW2_API = "https://api.guildwars2.com/v2";
+const WIKI_API = "https://wiki.guildwars2.com/api.php";
+
+// Known split skills from the wiki's balance split category.
+// These are good validation targets because they have WvW-specific values.
+const DEFAULT_SKILL_IDS = [
+  5489,  // Fireball
+  5536,  // Arcane Blast
+  30185, // Berserk
+  5507,  // Meteor Shower
+  5548,  // Eruption
+  5569,  // Water Blast
+  5503,  // Glyph of Storms
+  10586, // Mending (Warrior)
+  5694,  // Burning Retreat (Elementalist)
+  10574, // Bull's Charge (Warrior)
+];
+
+const DEFAULT_TRAIT_IDS = [
+  264,  // Burning Precision
+  1510, // Flow like Water
+  1502, // Swift Revenge
+  214,  // Empowering Might
+  1925, // Stalwart Speed
+];
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function color(code, text) {
+  return `\x1b[${code}m${text}\x1b[0m`;
+}
+const green = (t) => color(32, t);
+const red = (t) => color(31, t);
+const yellow = (t) => color(33, t);
+const dim = (t) => color(2, t);
+
+// ── Main ────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const args = process.argv.slice(2);
+  const typeArg = args.includes("--type") ? args[args.indexOf("--type") + 1] : "skills";
+  const idsArg = args.includes("--ids") ? args[args.indexOf("--ids") + 1] : null;
+
+  const ids = idsArg
+    ? idsArg.split(",").map((s) => parseInt(s.trim(), 10))
+    : (typeArg === "traits" ? DEFAULT_TRAIT_IDS : DEFAULT_SKILL_IDS);
+
+  const endpoint = typeArg === "traits" ? "traits" : "skills";
+
+  const wikiClient = new WikiClient({
+    cache: new MemoryCache(),
+    fetch: globalThis.fetch,
+  });
+
+  const apiClient = new Gw2ApiClient({
+    cache: new MemoryCache(),
+    fetch: globalThis.fetch,
+  });
+
+  console.log(`\nValidating ${ids.length} ${endpoint} against live GW2 data...\n`);
+
+  let passed = 0;
+  let failed = 0;
+  let skipped = 0;
+
+  for (const id of ids) {
+    process.stdout.write(`  ${id} `);
+
+    // 1. Fetch API data
+    let apiData;
+    try {
+      const url = `${GW2_API}/${endpoint}/${id}?lang=en`;
+      apiData = await apiClient.fetchJson(url);
+    } catch (err) {
+      console.log(yellow(`SKIP — API error: ${err.message}`));
+      skipped++;
+      continue;
+    }
+
+    const name = apiData.name || `(${endpoint} ${id})`;
+    process.stdout.write(`${name.padEnd(30)} `);
+
+    // 2. Fetch wiki page
+    let wikitext;
+    try {
+      wikitext = await wikiClient.getWikitext(name);
+    } catch (err) {
+      console.log(yellow(`SKIP — wiki error: ${err.message}`));
+      skipped++;
+      continue;
+    }
+
+    if (!wikitext) {
+      console.log(yellow("SKIP — no wiki page"));
+      skipped++;
+      continue;
+    }
+
+    // 3. Parse wiki facts
+    const wikiResult = wikiClient.parseFacts(wikitext);
+    const apiFacts = apiData.facts || [];
+
+    // 4. Validate
+    const issues = [];
+
+    // Check: if wiki has a split, we should get split facts
+    if (wikiResult.splitGrouping?.wvwHasSplit && wikiResult.facts.length === 0) {
+      issues.push("split detected but no WvW facts parsed");
+    }
+
+    // Check: wiki fact types should all be recognized API types
+    for (const fact of wikiResult.facts) {
+      const normalized = normalizeFactType(fact.type);
+      if (!normalized) {
+        issues.push(`unknown fact type: ${fact.type}`);
+      }
+    }
+
+    // Check: merge should not crash
+    try {
+      const merged = mergeFacts(apiFacts, wikiResult.facts, { complete: false });
+      if (wikiResult.facts.length > 0 && merged.length === 0) {
+        issues.push("merge produced empty result from non-empty inputs");
+      }
+    } catch (err) {
+      issues.push(`merge crashed: ${err.message}`);
+    }
+
+    // Check: damage coefficients should be reasonable (0 < coeff < 50)
+    for (const fact of wikiResult.facts) {
+      if (fact.type === "Damage" && fact.dmg_multiplier !== undefined) {
+        if (fact.dmg_multiplier < 0 || fact.dmg_multiplier > 50) {
+          issues.push(`suspicious damage coefficient: ${fact.dmg_multiplier}`);
+        }
+      }
+    }
+
+    // Check: durations should be non-negative
+    for (const fact of wikiResult.facts) {
+      if (fact.duration !== undefined && fact.duration < 0) {
+        issues.push(`negative duration: ${fact.duration}`);
+      }
+    }
+
+    if (issues.length > 0) {
+      console.log(red("FAIL"));
+      for (const issue of issues) {
+        console.log(`      ${red("✗")} ${issue}`);
+      }
+      failed++;
+    } else {
+      const splitLabel = wikiResult.splitGrouping?.wvwHasSplit ? "split" : "universal";
+      console.log(
+        green("OK") +
+        dim(` (${wikiResult.facts.length} wiki facts, ${apiFacts.length} API facts, ${splitLabel})`)
+      );
+      passed++;
+    }
+  }
+
+  console.log(`\n  ${green(`${passed} passed`)}, ${failed > 0 ? red(`${failed} failed`) : `${failed} failed`}, ${skipped} skipped\n`);
+
+  if (failed > 0) process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/tests/wiki-client.test.js

@@ -0,0 +1,468 @@
+"use strict";
+
+const { WikiClient } = require("../src/wiki/client");
+const { MemoryCache } = require("../src/wiki/cache");
+
+describe("WikiClient", () => {
+  let client;
+  let mockFetch;
+
+  beforeEach(() => {
+    mockFetch = jest.fn();
+    client = new WikiClient({
+      cache: new MemoryCache(),
+      fetch: mockFetch,
+    });
+  });
+
+  describe("getWikitext", () => {
+    test("fetches and returns raw wikitext for a page", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: {
+              "123": {
+                title: "Fireball",
+                revisions: [{ "*": "{{skill infobox\n| id = 5489\n}}" }],
+              },
+            },
+          },
+        }),
+      });
+
+      const result = await client.getWikitext("Fireball");
+      expect(result).toBe("{{skill infobox\n| id = 5489\n}}");
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      expect(mockFetch.mock.calls[0][0]).toContain("action=query");
+      expect(mockFetch.mock.calls[0][0]).toContain("rvprop=content");
+    });
+
+    test("returns null for missing page", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: {
+              "-1": { missing: true },
+            },
+          },
+        }),
+      });
+
+      const result = await client.getWikitext("Nonexistent");
+      expect(result).toBeNull();
+    });
+
+    test("caches wikitext on subsequent calls", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: {
+              "123": {
+                title: "Fireball",
+                revisions: [{ "*": "wikitext content" }],
+              },
+            },
+          },
+        }),
+      });
+
+      await client.getWikitext("Fireball");
+      const result2 = await client.getWikitext("Fireball");
+      expect(result2).toBe("wikitext content");
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("getWikitextBatch", () => {
+    test("fetches multiple pages in a single request", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: {
+              "1": { title: "Fireball", revisions: [{ "*": "fireball wikitext" }] },
+              "2": { title: "Shelter", revisions: [{ "*": "shelter wikitext" }] },
+              "3": { title: "Moa Stance", revisions: [{ "*": "moa wikitext" }] },
+            },
+          },
+        }),
+      });
+
+      const result = await client.getWikitextBatch(["Fireball", "Shelter", "Moa Stance"]);
+      expect(result.size).toBe(3);
+      expect(result.get("Fireball")).toBe("fireball wikitext");
+      expect(result.get("Shelter")).toBe("shelter wikitext");
+      expect(result.get("Moa Stance")).toBe("moa wikitext");
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    test("chunks at 50 titles per request", async () => {
+      // Generate 51 titles
+      const titles = Array.from({ length: 51 }, (_, i) => `Skill_${i}`);
+
+      const makeBatchResponse = (batch) => ({
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: Object.fromEntries(
+              batch.map((t, i) => [String(i), { title: t, revisions: [{ "*": `${t} text` }] }])
+            ),
+          },
+        }),
+      });
+
+      // First call: 50 titles, second call: 1 title
+      mockFetch
+        .mockResolvedValueOnce(makeBatchResponse(titles.slice(0, 50)))
+        .mockResolvedValueOnce(makeBatchResponse(titles.slice(50)));
+
+      const result = await client.getWikitextBatch(titles);
+      expect(result.size).toBe(51);
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      expect(result.get("Skill_0")).toBe("Skill_0 text");
+      expect(result.get("Skill_50")).toBe("Skill_50 text");
+    });
+
+    test("uses cached entries without fetching", async () => {
+      // Pre-populate cache
+      client._cache.set("wikitext:Fireball", "cached fireball", 60000);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: {
+              "1": { title: "Shelter", revisions: [{ "*": "shelter text" }] },
+            },
+          },
+        }),
+      });
+
+      const result = await client.getWikitextBatch(["Fireball", "Shelter"]);
+      expect(result.get("Fireball")).toBe("cached fireball");
+      expect(result.get("Shelter")).toBe("shelter text");
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+      // URL should only contain Shelter
+      expect(mockFetch.mock.calls[0][0]).toContain("Shelter");
+      expect(mockFetch.mock.calls[0][0]).not.toContain("Fireball");
+    });
+
+    test("returns null for missing pages", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: {
+              "-1": { title: "Nonexistent Skill", missing: true },
+              "1": { title: "Fireball", revisions: [{ "*": "fireball text" }] },
+            },
+          },
+        }),
+      });
+
+      const result = await client.getWikitextBatch(["Fireball", "Nonexistent Skill"]);
+      expect(result.get("Fireball")).toBe("fireball text");
+      expect(result.get("Nonexistent Skill")).toBe(null);
+    });
+
+    test("handles failed HTTP response gracefully", async () => {
+      mockFetch.mockResolvedValueOnce({ ok: false, status: 500 });
+
+      const result = await client.getWikitextBatch(["Fireball", "Shelter"]);
+      expect(result.get("Fireball")).toBe(null);
+      expect(result.get("Shelter")).toBe(null);
+    });
+
+    test("returns empty map for empty input", async () => {
+      const result = await client.getWikitextBatch([]);
+      expect(result.size).toBe(0);
+      expect(mockFetch).not.toHaveBeenCalled();
+    });
+
+    test("caches missing pages so subsequent batch calls skip them", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: {
+              "-1": { title: "Missing Skill", missing: true },
+              "1": { title: "Fireball", revisions: [{ "*": "fireball text" }] },
+            },
+          },
+        }),
+      });
+
+      const result1 = await client.getWikitextBatch(["Fireball", "Missing Skill"]);
+      expect(result1.get("Missing Skill")).toBeNull();
+      expect(result1.get("Fireball")).toBe("fireball text");
+
+      // Second batch: "Missing Skill" should come from cache, only "Shelter" fetched
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: {
+              "1": { title: "Shelter", revisions: [{ "*": "shelter text" }] },
+            },
+          },
+        }),
+      });
+
+      const result2 = await client.getWikitextBatch(["Missing Skill", "Shelter"]);
+      expect(result2.get("Missing Skill")).toBeNull();
+      expect(result2.get("Shelter")).toBe("shelter text");
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+      // Second fetch should only contain Shelter, not Missing Skill
+      expect(mockFetch.mock.calls[1][0]).toContain("Shelter");
+      expect(mockFetch.mock.calls[1][0]).not.toContain("Missing");
+    });
+
+    test("handles MediaWiki title normalization", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            normalized: [{ from: "fireball", to: "Fireball" }],
+            pages: {
+              "1": { title: "Fireball", revisions: [{ "*": "fireball text" }] },
+            },
+          },
+        }),
+      });
+
+      const result = await client.getWikitextBatch(["fireball"]);
+      expect(result.get("fireball")).toBe("fireball text");
+    });
+  });
+
+  describe("getRecentChanges", () => {
+    test("returns list of recently changed page titles", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            recentchanges: [
+              { title: "Fireball", timestamp: "2026-04-09T10:00:00Z" },
+              { title: "Ice Spike", timestamp: "2026-04-09T09:00:00Z" },
+            ],
+          },
+        }),
+      });
+
+      const changes = await client.getRecentChanges("2026-04-08T00:00:00Z");
+      expect(changes).toEqual(["Fireball", "Ice Spike"]);
+    });
+  });
+
+  describe("getWikitext", () => {
+    test("caches missing pages so subsequent calls skip the network", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: {
+              "-1": { missing: true },
+            },
+          },
+        }),
+      });
+
+      const result1 = await client.getWikitext("Nonexistent");
+      expect(result1).toBeNull();
+
+      // Second call should NOT hit the network
+      const result2 = await client.getWikitext("Nonexistent");
+      expect(result2).toBeNull();
+      expect(mockFetch).toHaveBeenCalledTimes(1);
+    });
+
+    test("returns null on HTTP error", async () => {
+      mockFetch.mockResolvedValueOnce({ ok: false, status: 500 });
+      const result = await client.getWikitext("Fireball");
+      expect(result).toBeNull();
+    });
+
+    test("returns null when query.pages is missing", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({ query: {} }),
+      });
+      const result = await client.getWikitext("Fireball");
+      expect(result).toBeNull();
+    });
+  });
+
+  describe("getRecentChanges", () => {
+    test("returns empty array on HTTP error", async () => {
+      mockFetch.mockResolvedValueOnce({ ok: false, status: 500 });
+      const result = await client.getRecentChanges("2026-04-08T00:00:00Z");
+      expect(result).toEqual([]);
+    });
+
+    test("deduplicates changed page titles", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            recentchanges: [
+              { title: "Fireball", timestamp: "2026-04-09T10:00:00Z" },
+              { title: "Fireball", timestamp: "2026-04-09T09:00:00Z" },
+              { title: "Ice Spike", timestamp: "2026-04-09T08:00:00Z" },
+            ],
+          },
+        }),
+      });
+      const result = await client.getRecentChanges("2026-04-08T00:00:00Z");
+      expect(result).toEqual(["Fireball", "Ice Spike"]);
+    });
+  });
+
+  describe("refresh", () => {
+    test("first call records timestamp and returns empty array", async () => {
+      const result = await client.refresh();
+      expect(result).toEqual([]);
+    });
+
+    test("second call fetches recent changes and invalidates cache", async () => {
+      // First call sets the timestamp
+      await client.refresh();
+
+      // Pre-populate cache
+      const cache = client._cache;
+      cache.set("wikitext:Fireball", "old content", 60000);
+      cache.set("facts:Fireball", [{ type: "Damage" }], 60000);
+
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            recentchanges: [
+              { title: "Fireball", timestamp: "2026-04-09T10:00:00Z" },
+            ],
+          },
+        }),
+      });
+
+      const changed = await client.refresh();
+      expect(changed).toEqual(["Fireball"]);
+      expect(cache.get("wikitext:Fireball")).toBeNull();
+      expect(cache.get("facts:Fireball")).toBeNull();
+    });
+  });
+
+  describe("rate limiting", () => {
+    test("delays subsequent requests within rate limit window", async () => {
+      const response = {
+        ok: true,
+        json: async () => ({
+          query: {
+            pages: { "1": { title: "A", revisions: [{ "*": "a" }] } },
+          },
+        }),
+      };
+      mockFetch.mockResolvedValue(response);
+
+      const start = Date.now();
+      await client.getWikitext("A");
+      await client.getWikitext("B"); // different key, forces second fetch
+      const elapsed = Date.now() - start;
+
+      // Should have waited ~200ms between requests
+      expect(elapsed).toBeGreaterThanOrEqual(150);
+      expect(mockFetch).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe("prefixSearch", () => {
+    test("returns matching page titles", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: {
+            prefixsearch: [
+              { title: "Ring of Fire (elementalist skill)" },
+              { title: "Ring of Fire (location)" },
+            ],
+          },
+        }),
+      });
+
+      const results = await client.prefixSearch("Ring of Fire (");
+      expect(results).toEqual([
+        "Ring of Fire (elementalist skill)",
+        "Ring of Fire (location)",
+      ]);
+    });
+
+    test("returns empty array when no matches", async () => {
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        json: async () => ({
+          query: { prefixsearch: [] },
+        }),
+      });
+
+      const results = await client.prefixSearch("Nonexistent (");
+      expect(results).toEqual([]);
+    });
+
+    test("returns empty array on fetch failure", async () => {
+      mockFetch.mockResolvedValueOnce({ ok: false });
+
+      const results = await client.prefixSearch("Test (");
+      expect(results).toEqual([]);
+    });
+  });
+
+  describe("parseFacts", () => {
+    test("parses wikitext into facts for a game mode", () => {
+      const wikitext = [
+        "{{skill infobox",
+        "| id = 5489",
+        "| split = pve, wvw, pvp",
+        "}}",
+        "{{skill fact|damage|0.8|game mode=wvw}}",
+        "{{skill fact|damage|1.2|game mode=pve}}",
+        "{{skill fact|recharge|25}}",
+      ].join("\n");
+
+      const result = client.parseFacts(wikitext);
+      expect(result.facts.length).toBeGreaterThanOrEqual(2);
+      const damageFact = result.facts.find((f) => f.type === "Damage");
+      expect(damageFact.dmg_multiplier).toBe(0.8);
+      const rechargeFact = result.facts.find((f) => f.type === "Recharge");
+      expect(rechargeFact.value).toBe(25);
+    });
+
+    test("falls back to parseInfoboxParams when no skill fact templates found", () => {
+      const wikitext = [
+        "{{skill infobox",
+        "| id = 1234",
+        "| split = pve, wvw, pvp",
+        "| recharge wvw = 30",
+        "}}",
+      ].join("\n");
+
+      const result = client.parseFacts(wikitext);
+      expect(result.splitGrouping.wvwHasSplit).toBe(true);
+      const rechargeFact = result.facts.find((f) => f.type === "Recharge");
+      expect(rechargeFact).toBeTruthy();
+      expect(rechargeFact.value).toBe(30);
+    });
+
+    test("returns null splitGrouping when no split field present", () => {
+      const wikitext = [
+        "{{skill infobox",
+        "| id = 1234",
+        "}}",
+        "{{skill fact|damage|1.0}}",
+      ].join("\n");
+
+      const result = client.parseFacts(wikitext);
+      expect(result.splitGrouping).toBeNull();
+    });
+  });
+});