@shortlink-org/portolan 0.2.1 → 0.2.3

package/scripts/gen-likec4.test.mjs

@@ -1,9 +1,4 @@
-import {
-  mkdirSync,
-  mkdtempSync,
-  readFileSync,
-  writeFileSync,
-} from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -12,7 +7,12 @@ import { execFileSync } from "node:child_process";
 import { describe, expect, it } from "vitest";
 
 const generator = fileURLToPath(new URL("./gen-likec4.mjs", import.meta.url));
-const likec4 = join(dirname(dirname(generator)), "node_modules", ".bin", "likec4");
+const likec4 = join(
+  dirname(dirname(generator)),
+  "node_modules",
+  ".bin",
+  "likec4",
+);
 
 /** Runs the generator over one catalog in a scratch tree, and validates what it wrote. */
 function generate(catalog) {
@@ -35,12 +35,151 @@ function generate(catalog) {
   execFileSync(process.execPath, [generator], { cwd: root });
   execFileSync(likec4, ["validate", "likec4"], { cwd: root });
   return {
+    spec: readFileSync(join(root, "likec4", "spec.c4"), "utf8"),
     model: readFileSync(join(root, "likec4", "model.c4"), "utf8"),
     views: readFileSync(join(root, "likec4", "views.c4"), "utf8"),
   };
 }
 
 describe("the LikeC4 generator", () => {
+  it("emits valid fallback views for an empty catalog", () => {
+    const { model, views } = generate({ contexts: [], flows: [] });
+    expect(model).toContain("model {");
+    expect(views).toContain("view landscape");
+    expect(views).toContain("view landscape_default");
+    expect(views).toContain("view containers_default");
+    expect(views).toContain("include *");
+  });
+
+  it("makes the implicit default profile include the complete catalog", () => {
+    const { views } = generate({
+      contexts: [
+        {
+          id: "platform",
+          slug: "platform",
+          name: "Platform",
+          summary: "",
+          services: [
+            {
+              id: "platform.api",
+              slug: "api",
+              name: "API",
+              repo: "example/platform",
+              path: "",
+              readme: "",
+              provides: [],
+              consumes: [],
+              aggregates: [],
+            },
+          ],
+        },
+      ],
+      flows: [],
+    });
+    expect(views).toContain("view landscape_default");
+    expect(views).toContain("include platform");
+    expect(views).toContain("view containers_default");
+    expect(views).toContain("include platform, platform.api");
+  });
+
+  it("draws synchronous requests solid and synthesized responses dashed", () => {
+    const service = (slug, provides = []) => ({
+      id: `demo.${slug}`,
+      slug,
+      name: slug,
+      repo: "example/demo",
+      path: slug,
+      readme: "",
+      provides,
+      consumes: [],
+      aggregates: [],
+    });
+    const { spec, views } = generate({
+      contexts: [
+        {
+          id: "demo",
+          slug: "demo",
+          name: "Demo",
+          summary: "",
+          services: [
+            service("api"),
+            service("book", [
+              {
+                id: "book.v1.Book",
+                source: "book.proto",
+                methods: [
+                  {
+                    name: "Get",
+                    request: "GetRequest",
+                    response: "GetResponse",
+                  },
+                ],
+              },
+            ]),
+          ],
+        },
+      ],
+      flows: [
+        {
+          id: "flow.get-book",
+          slug: "get-book",
+          name: "Get book",
+          summary: "",
+          owner: "demo",
+          participants: [
+            { id: "demo.api", kind: "service", context: "demo" },
+            { id: "demo.book", kind: "service", context: "demo" },
+          ],
+          steps: [
+            {
+              type: "step",
+              id: "request",
+              from: "demo.api",
+              to: "demo.book",
+              kind: "rpc",
+              ref: "book.v1.Book/Get",
+              label: "Get",
+              status: "declared",
+            },
+            {
+              type: "step",
+              id: "response",
+              from: "demo.book",
+              to: "demo.api",
+              kind: "response",
+              label: "GetResponse",
+              status: "declared",
+              replyTo: "request",
+            },
+            {
+              type: "step",
+              id: "failure",
+              from: "demo.book",
+              to: "demo.api",
+              kind: "response",
+              label: "500 · Error",
+              status: "declared",
+              replyTo: "request",
+              http: { status: 500, outcome: "error" },
+            },
+          ],
+        },
+      ],
+    });
+
+    expect(views).toContain(
+      "demo.api -> demo.book 'Get' {\n      color declared  line solid  head normal",
+    );
+    expect(views).toContain(
+      "demo.book -> demo.api 'GetResponse' {\n      color declared  line dashed  head normal",
+    );
+    expect(views).toContain(
+      "demo.book -> demo.api '500 · Error' {\n      color response_error  line dashed  head normal",
+    );
+    expect(spec).toContain("color response_error #b7646b");
+    expect(views).not.toContain("Get → GetResponse");
+  });
+
   it("treats dots in a root participant id as data, not containment", () => {
     const { model, views } = generate({
       contexts: [
@@ -152,7 +291,12 @@ describe("the LikeC4 generator", () => {
                       slug: "basket-checked-out",
                       name: "BasketCheckedOut",
                       versions: [
-                        { version: "v1", doc: "", source: "cart.go:1", fields: [] },
+                        {
+                          version: "v1",
+                          doc: "",
+                          source: "cart.go:1",
+                          fields: [],
+                        },
                       ],
                       consumers: [{ service: "shop.oms", status: "declared" }],
                     },
@@ -231,18 +375,26 @@ describe("the LikeC4 generator", () => {
     expect(model).toContain("technology 'postgres'");
     // Every relation says what kind of fact it is; a call carries its protocol.
     expect(model).toContain("shop.oms -[calls]-> shop.cart 'getBasket' 'HTTP'");
-    expect(model).toContain("shop.cart -[consumes]-> shop.oms 'BasketCheckedOut'");
+    expect(model).toContain(
+      "shop.cart -[consumes]-> shop.oms 'BasketCheckedOut'",
+    );
     // The hop through the broker, once per direction, with the step's status.
-    expect(model).toContain("shop.cart -[bus]-> bus 'BasketCheckedOut' {\n    style { color verified");
-    expect(model).toContain("bus -[bus]-> shop.oms 'BasketCheckedOut' {\n    style { color declared");
+    expect(model).toContain(
+      "shop.cart -[bus]-> bus 'BasketCheckedOut' {\n    style { color verified",
+    );
+    expect(model).toContain(
+      "bus -[bus]-> shop.oms 'BasketCheckedOut' {\n    style { color declared",
+    );
 
     // The estate's containers: contexts opened, stores and the bus named.
-    expect(views).toMatch(/view containers \{[^}]*include shop, shop\.cart, shop\.oms, shop\.cart\.pg, bus\n/);
+    expect(views).toMatch(
+      /view containers \{[^}]*include shop, shop\.cart, shop\.oms, shop\.cart\.pg, bus\n/,
+    );
     // One edge per pair, counted, with the protocol and the best status.
     const pair =
       "include shop.oms -> shop.cart with { title '2 calls'  technology 'HTTP'  color verified  line solid }";
     expect(views).toContain(`view containers {\n    title 'Containers'`);
-    expect(views.split(pair)).toHaveLength(3); // containers, and ctx_shop
+    expect(views.split(pair)).toHaveLength(4); // containers, containers_default, and ctx_shop
     // With the bus on the picture the direct consumer arrow is not drawn twice.
     expect(views).toContain(
       "view ctx_shop of shop {\n" +
@@ -253,6 +405,8 @@ describe("the LikeC4 generator", () => {
         "  }",
     );
     // The neighbours view keeps every method as its own relation.
-    expect(views).toMatch(/view svc_shop_oms of shop\.oms \{\n    title[^\n]*\n    include \*, -> \*, \* ->\n  \}/);
+    expect(views).toMatch(
+      /view svc_shop_oms of shop\.oms \{\n    title[^\n]*\n    include \*, -> \*, \* ->\n  \}/,
+    );
   });
 });

package/scripts/gen.mjs

@@ -485,21 +485,23 @@ function apply(files, out, key, checkOnly) {
   for (const file of files) {
     const target = safeJoin(out, file.name);
     written.add(file.name);
+    const binary = file.encoding === "base64";
+    const wanted = binary ? Buffer.from(file.contents, "base64") : file.contents;
 
     let current = null;
     try {
-      current = readFileSync(target, "utf8");
+      current = readFileSync(target, binary ? undefined : "utf8");
     } catch {
       // Absent, which the comparison below reports as added.
     }
 
-    if (current === file.contents) continue;
+    if (binary ? Buffer.isBuffer(current) && current.equals(wanted) : current === wanted) continue;
 
     changes.push({ kind: current === null ? "added" : "changed", path: join(out, file.name) });
     if (checkOnly) continue;
 
     try {
-      writeOutputFile(out, file.name, file.contents);
+      writeOutputFile(out, file.name, wanted);
     } catch (cause) {
       fail(cause.message);
     }

package/scripts/host-plugins/fetch-git.mjs

@@ -69,6 +69,7 @@ export function describe() {
  */
 export function run(request, { env = process.env } = {}) {
   const options = request.options ?? {};
+  const generatedAt = String(request.input?.generatedAt ?? "");
   const repos = Array.isArray(options.repos) ? options.repos : [];
   if (repos.length === 0) throw new Error("no repositories to fetch: name at least one in the manifest");
   if (!options.cache) {
@@ -86,7 +87,7 @@ export function run(request, { env = process.env } = {}) {
     const at = join(options.cache, ...dir.split("/"));
 
     if (skip) {
-      emitCached(out, dir, at, want, "offline");
+      emitCached(out, dir, at, want, "offline", generatedAt);
       continue;
     }
 
@@ -97,14 +98,14 @@ export function run(request, { env = process.env } = {}) {
       // Rule 2: the tree still holds a good copy, so the output is unchanged
       // and `--check` stays clean.
       try {
-        emitCached(out, dir, at, want, cause.message);
+        emitCached(out, dir, at, want, cause.message, generatedAt);
       } catch (cacheCause) {
         // Rule 3: nothing to fall back to.
         throw new Error(`${want.repo} could not be fetched (${cause.message}) and there is no usable copy in the tree (${cacheCause.message})`);
       }
       continue;
     }
-    emitFetched(out, dir, want, fetched.commit, fetched.files);
+    emitFetched(out, dir, want, fetched.commit, fetched.files, generatedAt);
   }
 
   return out.response();
@@ -164,8 +165,8 @@ export function webRepo(name) {
 }
 
 /** The fragment for one repository at one commit: a catalog with one pin. */
-export function pin(repo, commit) {
-  return `${JSON.stringify({ contexts: [], defs: {}, flows: [], adrs: [], repos: [{ repo: webRepo(repo), commit }] }, null, 2)}\n`;
+export function pin(repo, commit, generatedAt = "") {
+  return `${JSON.stringify({ ...(generatedAt ? { generatedAt } : {}), contexts: [], defs: {}, flows: [], adrs: [], repos: [{ repo: webRepo(repo), commit }] }, null, 2)}\n`;
 }
 
 /** The lock, written the way every generated file here is written. */
@@ -195,15 +196,15 @@ function live(url, want, out, env) {
   return { commit, files };
 }
 
-function emitFetched(out, dir, want, commit, files) {
+function emitFetched(out, dir, want, commit, files, generatedAt) {
   const entry = { repo: want.repo, commit, paths: want.paths ?? [], files: [] };
   for (const path of [...files.keys()].sort()) {
     const contents = files.get(path);
-    out.file(posix.join(dir, path), contents.toString("utf8"));
+    out.file(posix.join(dir, path), contents);
     entry.files.push({ path, sha256: digestOf(contents), size: contents.length });
   }
   out.file(posix.join(dir, LOCK_NAME), encodeLock(entry));
-  out.file(posix.join(dir, PIN_NAME), pin(want.repo, commit));
+  out.file(posix.join(dir, PIN_NAME), pin(want.repo, commit, generatedAt));
 }
 
 /**
@@ -211,18 +212,18 @@ function emitFetched(out, dir, want, commit, files) {
  * online run wrote, so `gen:check` sees no drift and CI can verify an estate
  * whose services live in repositories it never clones.
  */
-function emitCached(out, dir, at, want, why) {
+function emitCached(out, dir, at, want, why, generatedAt = "") {
   if (!want.commit) throw new Error(`${want.repo} is not pinned to a commit, so there is nothing to replay`);
   const held = replay(at);
   if (held.lock.commit !== want.commit) {
     throw new Error(`${want.repo} holds commit ${held.lock.commit} but the manifest pins ${want.commit}; fetch it`);
   }
-  for (const file of held.lock.files) out.file(posix.join(dir, file.path), held.files.get(file.path).toString("utf8"));
+  for (const file of held.lock.files) out.file(posix.join(dir, file.path), held.files.get(file.path));
   out.file(posix.join(dir, LOCK_NAME), encodeLock(held.lock));
   // From the LOCK's commit, not the manifest's. They are equal by the check
   // above, and taking it from the copy is what keeps the fragment describing
   // what is actually on disk rather than what was asked for.
-  out.file(posix.join(dir, PIN_NAME), pin(want.repo, held.lock.commit));
+  out.file(posix.join(dir, PIN_NAME), pin(want.repo, held.lock.commit, generatedAt));
   out.warn(want.repo, `not fetched (${why}); the copy committed in this repository is used unchanged`);
 }
 
@@ -366,7 +367,16 @@ class Builder {
   warnings = [];
 
   file(name, contents) {
-    this.files.push({ name, contents });
+    if (!Buffer.isBuffer(contents)) {
+      this.files.push({ name, contents });
+      return;
+    }
+    const text = contents.toString("utf8");
+    this.files.push(
+      Buffer.from(text, "utf8").equals(contents)
+        ? { name, contents: text }
+        : { name, contents: contents.toString("base64"), encoding: "base64" },
+    );
   }
 
   warn(ref, message) {

package/scripts/host-plugins/fetch-git.test.mjs

@@ -1,5 +1,5 @@
 import { execFileSync } from "node:child_process";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
@@ -30,6 +30,7 @@ function repository() {
   write("services/oms/internal/domain/order/order.go", "package order\n");
   write("services/oms/README.md", "# OMS\n");
   write("proto/shop/v1/orders.proto", 'syntax = "proto3";\n');
+  write("docs/example.png", Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0x00]));
   write("README.md", "# shop\n");
   git(["add", "."]);
   git(["commit", "--quiet", "-m", "the estate"]);
@@ -48,21 +49,22 @@ function cache() {
 const online = { CI: "", [OFFLINE_ENV]: "" };
 const offline = { CI: "", [OFFLINE_ENV]: "1" };
 const options = (remote, cacheDir, paths) => ({ cache: cacheDir, repos: [{ repo: remote.url, commit: remote.commit, ...(paths ? { paths } : {}) }] });
-const fetch = (opts, env) => run({ options: opts }, { env: { ...process.env, ...env } });
+const fetch = (opts, env, input) => run({ options: opts, ...(input ? { input } : {}) }, { env: { ...process.env, ...env } });
 const names = (response) => response.files.map((file) => file.name).sort();
 const contentsOf = (response, name) => response.files.find((file) => file.name === name)?.contents ?? "";
 // What the host does with a response.
 const write = (dir, response) => {
   for (const file of response.files) {
     mkdirSync(dirname(join(dir, file.name)), { recursive: true });
-    writeFileSync(join(dir, file.name), file.contents);
+    writeFileSync(join(dir, file.name), file.encoding === "base64" ? Buffer.from(file.contents, "base64") : file.contents);
   }
 };
 
 describe("fetch-git", () => {
   it("writes the narrowed copy, a lock and a pin", () => {
     const remote = repository();
-    const response = fetch(options(remote, cache(), ["services/oms", "proto"]), online);
+    const generatedAt = "2026-09-09T03:00:00.000Z";
+    const response = fetch(options(remote, cache(), ["services/oms", "proto"]), online, { generatedAt });
     // The directory is owner/name, read off the URL; the paths inside are
     // the repository's own, so an extractor can read the copy as a checkout.
     const dir = remote.copyDir;
@@ -82,7 +84,7 @@ describe("fetch-git", () => {
 
     // The fragment is the lock's commit said in the shape the catalog reads.
     const fragment = contentsOf(response, `${dir}/git.repo.json`);
-    expect(JSON.parse(fragment)).toEqual({ contexts: [], defs: {}, flows: [], adrs: [], repos: [{ repo: remote.dir.slice(1), commit: remote.commit }] });
+    expect(JSON.parse(fragment)).toEqual({ generatedAt, contexts: [], defs: {}, flows: [], adrs: [], repos: [{ repo: remote.dir.slice(1), commit: remote.commit }] });
     expect(fragment.endsWith("\n")).toBe(true);
   });
 
@@ -103,6 +105,20 @@ describe("fetch-git", () => {
     expect(inCi.warnings).toHaveLength(1);
   });
 
+  it("preserves binary blobs online and from the offline cache", () => {
+    const remote = repository();
+    const cacheDir = cache();
+    const first = fetch(options(remote, cacheDir, ["docs/example.png"]), online);
+    const name = `${remote.copyDir}/docs/example.png`;
+    const image = first.files.find((file) => file.name === name);
+    expect(image?.encoding).toBe("base64");
+    write(cacheDir, first);
+    expect(readFileSync(join(cacheDir, name))).toEqual(readFileSync(join(remote.dir, "docs/example.png")));
+
+    const replayed = fetch(options(remote, cacheDir, ["docs/example.png"]), offline);
+    expect(replayed.files.find((file) => file.name === name)).toEqual(image);
+  });
+
   it("names the edited file when a vendored copy no longer matches its lock", () => {
     const remote = repository();
     const cacheDir = cache();
@@ -202,6 +218,10 @@ describe("names", () => {
     const fragment = pin("git@github.com:acme/shop.git", "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0");
     expect(fragment).toBe(`${JSON.stringify({ contexts: [], defs: {}, flows: [], adrs: [], repos: [{ repo: "github.com/acme/shop", commit: "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0" }] }, null, 2)}\n`);
     expect(pin("github.com/acme/shop", "c1d2e3f")).toBe(pin("github.com/acme/shop", "c1d2e3f"));
+    expect(JSON.parse(pin("github.com/acme/shop", "c1d2e3f", "2026-09-09T03:00:00.000Z"))).toMatchObject({
+      generatedAt: "2026-09-09T03:00:00.000Z",
+      repos: [{ repo: "github.com/acme/shop", commit: "c1d2e3f" }],
+    });
 
     const lock = encodeLock({ repo: "github.com/acme/shop", commit: "abc", paths: ["services/oms", "proto"], files: [{ path: "b", sha256: "2", size: 1 }, { path: "a", sha256: "1", size: 1 }] });
     expect(JSON.parse(lock)).toEqual({ repos: [{ repo: "github.com/acme/shop", commit: "abc", paths: ["proto", "services/oms"], files: [{ path: "a", sha256: "1", size: 1 }, { path: "b", sha256: "2", size: 1 }] }] });