@neverprepared/mcp-phantom-diagrams 1.0.0

package/test/integration.test.ts

@@ -0,0 +1,55 @@
+/**
+ * Integration tests — require a running Kroki instance.
+ * Set SKIP_INTEGRATION=1 to skip (e.g. in CI without Docker).
+ * The tests call ensureKrokiRunning() in before(), so Docker must be available.
+ */
+import { describe, test, before } from "node:test";
+import assert from "node:assert/strict";
+import { convertDiagram } from "../src/kroki.ts";
+import { ensureKrokiRunning } from "../src/docker.ts";
+
+const skip = process.env.SKIP_INTEGRATION === "1" ? "SKIP_INTEGRATION=1" : false;
+
+describe("Kroki round-trips", { skip }, () => {
+  before(async () => {
+    await ensureKrokiRunning();
+  });
+
+  test("plantuml → svg contains <svg> element", async () => {
+    const result = await convertDiagram(
+      "plantuml",
+      "@startuml\nAlice -> Bob: hello\n@enduml",
+      "svg"
+    );
+    assert.equal(result.format, "svg");
+    assert.ok((result.data as string).includes("<svg"), "expected SVG document");
+  });
+
+  test("graphviz → png has PNG magic bytes", async () => {
+    const result = await convertDiagram("graphviz", "digraph { A -> B }", "png");
+    assert.equal(result.format, "png");
+    const buf = result.data as Buffer;
+    // PNG signature: 89 50 4E 47 0D 0A 1A 0A
+    assert.equal(buf[0], 0x89);
+    assert.equal(buf[1], 0x50); // P
+    assert.equal(buf[2], 0x4e); // N
+    assert.equal(buf[3], 0x47); // G
+  });
+
+  test("mermaid → svg (companion container)", async () => {
+    const result = await convertDiagram(
+      "mermaid",
+      "graph TD\n  A --> B",
+      "svg"
+    );
+    assert.equal(result.format, "svg");
+    assert.ok((result.data as string).includes("<svg"), "expected SVG document");
+  });
+
+  test("invalid plantuml source returns 4xx error with hint", async () => {
+    await assert.rejects(
+      () => convertDiagram("plantuml", "this is not valid plantuml markup !!!", "svg"),
+      /syntax error|rejected/i
+    );
+  });
+});

package/test/unit.test.ts

@@ -0,0 +1,124 @@
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { DIAGRAM_TYPES, convertDiagram } from "../src/kroki.ts";
+import { diagramCache } from "../src/cache.ts";
+
+describe("DIAGRAM_TYPES map", () => {
+  test("every type has at least one format", () => {
+    for (const [type, info] of Object.entries(DIAGRAM_TYPES)) {
+      assert.ok(info.formats.length > 0, `${type} has no formats`);
+    }
+  });
+
+  test("svg is supported by every built-in type", () => {
+    for (const [type, info] of Object.entries(DIAGRAM_TYPES)) {
+      if (!info.requiresCompanion) {
+        assert.ok(info.formats.includes("svg"), `built-in type ${type} should support svg`);
+      }
+    }
+  });
+
+  test("mermaid supports png (companion fix)", () => {
+    assert.ok(DIAGRAM_TYPES.mermaid.formats.includes("png"));
+  });
+
+  test("dbml supports png", () => {
+    assert.ok(DIAGRAM_TYPES.dbml.formats.includes("png"));
+  });
+
+  test("blockdiag-family types all marked requiresCompanion", () => {
+    for (const t of ["seqdiag", "actdiag", "nwdiag", "packetdiag", "rackdiag"] as const) {
+      assert.ok(DIAGRAM_TYPES[t].requiresCompanion, `${t} should require companion`);
+    }
+  });
+});
+
+describe("convertDiagram input validation", () => {
+  test("rejects source exceeding 256 KB", async () => {
+    const bigSource = "x".repeat(256 * 1024 + 1);
+    await assert.rejects(
+      () => convertDiagram("plantuml", bigSource, "svg"),
+      /exceeds.*limit/i
+    );
+  });
+
+  test("rejects CRLF in option key", async () => {
+    await assert.rejects(
+      () => convertDiagram("plantuml", "@startuml\n@enduml", "svg", { "bad\r\nkey": "val" }),
+      /Invalid option key/
+    );
+  });
+
+  test("rejects CRLF in option value", async () => {
+    await assert.rejects(
+      () => convertDiagram("plantuml", "@startuml\n@enduml", "svg", { key: "bad\r\nvalue" }),
+      /Invalid option value/
+    );
+  });
+
+  test("rejects non-printable chars in option key", async () => {
+    await assert.rejects(
+      () => convertDiagram("plantuml", "@startuml\n@enduml", "svg", { "key\x00null": "val" }),
+      /Invalid option key/
+    );
+  });
+
+  test("rejects non-printable chars in option value", async () => {
+    await assert.rejects(
+      () => convertDiagram("plantuml", "@startuml\n@enduml", "svg", { key: "val\x00null" }),
+      /Invalid option value/
+    );
+  });
+
+  test("rejects CRLF in query option key", async () => {
+    await assert.rejects(
+      () => convertDiagram("plantuml", "@startuml\n@enduml", "svg", undefined, { "bad\r\nkey": "val" }),
+      /Invalid query option key/
+    );
+  });
+
+  test("rejects CRLF in query option value", async () => {
+    await assert.rejects(
+      () => convertDiagram("plantuml", "@startuml\n@enduml", "svg", undefined, { key: "bad\r\nval" }),
+      /Invalid query option value/
+    );
+  });
+});
+
+describe("DiagramCache", () => {
+  test("miss returns undefined", () => {
+    const key = diagramCache.cacheKey("plantuml", "source", "svg");
+    // Use a fresh key unlikely to exist
+    assert.equal(diagramCache.get("no-such-key-" + Math.random()), undefined);
+  });
+
+  test("set then get returns same result", () => {
+    const result = { format: "svg" as const, data: "<svg/>" };
+    const key = diagramCache.cacheKey("graphviz", "digraph{}", "svg");
+    diagramCache.set(key, result);
+    const hit = diagramCache.get(key);
+    assert.deepEqual(hit, result);
+  });
+
+  test("stats reflect cached entries", () => {
+    const before = diagramCache.stats();
+    const result = { format: "svg" as const, data: "<svg>hello</svg>" };
+    const key = diagramCache.cacheKey("nomnoml", "#direction: right", "svg", {}, { theme: "dark" });
+    diagramCache.set(key, result);
+    const after = diagramCache.stats();
+    assert.ok(after.entries >= before.entries);
+    assert.ok(after.bytes >= before.bytes);
+  });
+
+  test("cacheKey differs with different query_options", () => {
+    const k1 = diagramCache.cacheKey("plantuml", "src", "svg", {}, { theme: "dark" });
+    const k2 = diagramCache.cacheKey("plantuml", "src", "svg", {}, { theme: "light" });
+    assert.notEqual(k1, k2);
+  });
+
+  test("cacheKey differs with different header options", () => {
+    const k1 = diagramCache.cacheKey("plantuml", "src", "svg", { key: "a" });
+    const k2 = diagramCache.cacheKey("plantuml", "src", "svg", { key: "b" });
+    assert.notEqual(k1, k2);
+  });
+});

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true,
+    "sourceMap": true
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}