@shortlink-org/portolan 0.2.2 → 0.2.4

package/scripts/delivery-presets.mjs

@@ -22,6 +22,26 @@ const GENERATED = "# Generated by Portolan. Preview changes in Settings before u
 const GITLAB_START = "# >>> Portolan delivery preset >>>";
 const GITLAB_END = "# <<< Portolan delivery preset <<<";
 const PROVIDERS = new Set(["github", "gitlab"]);
+const FEATURE_IDS = ["check", "diff", "sarif", "pages"];
+const DEFAULT_FEATURES = ["check", "pages"];
+const FEATURE_DETAILS = {
+  check: {
+    label: "Architecture check",
+    description: "Fail when committed architecture files are stale.",
+  },
+  diff: {
+    label: "Pull-request architecture diff",
+    description: "Post a sticky architecture summary where review happens.",
+  },
+  sarif: {
+    label: "SARIF annotations",
+    description: "Annotate changed architecture in GitHub's checks and code-scanning views.",
+  },
+  pages: {
+    label: "Static catalog publishing",
+    description: "Build and publish the catalog after changes reach the default branch.",
+  },
+};
 
 function exists(path) {
   try { lstatSync(path); return true; } catch { return false; }
@@ -153,9 +173,58 @@ jobs:
 `;
 }
 
-function gitlabBlock() {
-  return `${GITLAB_START}
-"portolan:check":
+function githubDiff({ pages, sarif }) {
+  const site = pages
+    ? "\n          site: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}"
+    : "";
+  const sarifInput = sarif ? "\n          sarif-output: .portolan/diff.sarif" : "";
+  const sarifPermission = sarif ? "\n  security-events: write # annotations in the checks tab" : "";
+  const upload = sarif
+    ? `
+      - name: Annotate the checks tab
+        uses: github/codeql-action/upload-sarif@v4
+        with:
+          sarif_file: .portolan/diff.sarif
+          category: architecture-diff
+        # Fork pull requests have a read-only token; the Markdown summary still works.
+        continue-on-error: true
+`
+    : "";
+  return `${GENERATED}
+name: Portolan architecture diff
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write${sarifPermission}
+
+concurrency:
+  group: portolan-diff-\${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  describe:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: shortlink-org/portolan@${VERSION}
+        env:
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        with:
+          command: diff
+          version: ${VERSION}
+          base-ref: origin/\${{ github.base_ref }}
+          head-ref: \${{ github.head_ref }}
+          comment: true${site}${sarifInput}
+${upload}`;
+}
+
+function gitlabCheck() {
+  return `"portolan:check":
   stage: .pre
   image:
     name: ghcr.io/shortlink-org/portolan:${VERSION}
@@ -167,8 +236,30 @@ function gitlabBlock() {
   rules:
     - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
     - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
+`;
+}
 
-"portolan:pages":
+function gitlabDiff({ pages }) {
+  const site = pages ? ' --site "$CI_PAGES_URL"' : "";
+  return `"portolan:review":
+  stage: .pre
+  image:
+    name: ghcr.io/shortlink-org/portolan:${VERSION}
+    entrypoint: [""]
+  variables:
+    GIT_DEPTH: "0"
+  script:
+    - portolan diff "origin/$CI_MERGE_REQUEST_TARGET_BRANCH_NAME" --head "$CI_MERGE_REQUEST_SOURCE_BRANCH_NAME"${site} --output .portolan/diff.md
+    - cat .portolan/diff.md
+    - portolan comment .portolan/diff.md
+  allow_failure: true
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+`;
+}
+
+function gitlabPages() {
+  return `"portolan:pages":
   stage: .post
   image:
     name: ghcr.io/shortlink-org/portolan:${VERSION}
@@ -182,11 +273,19 @@ function gitlabBlock() {
     publish: dist
   rules:
     - if: '$CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH'
-${GITLAB_END}
 `;
 }
 
-function mergeGitlab(existing) {
+function gitlabBlock(features) {
+  const jobs = [];
+  if (features.has("check")) jobs.push(gitlabCheck());
+  if (features.has("diff")) jobs.push(gitlabDiff({ pages: features.has("pages") }));
+  if (features.has("pages")) jobs.push(gitlabPages());
+  if (jobs.length === 0) return "";
+  return `${GITLAB_START}\n${jobs.join("\n")}${GITLAB_END}\n`;
+}
+
+function mergeGitlab(existing, features) {
   const start = existing.indexOf(GITLAB_START);
   const end = existing.indexOf(GITLAB_END);
   if ((start === -1) !== (end === -1) || (start !== -1 && end < start)) {
@@ -194,12 +293,17 @@ function mergeGitlab(existing) {
   }
   if (start !== -1) {
     const after = end + GITLAB_END.length;
-    return { content: `${existing.slice(0, start)}${gitlabBlock().trimEnd()}${existing.slice(after)}`.replace(/\n*$/, "\n") };
+    const replacement = gitlabBlock(features).trimEnd();
+    const content = `${existing.slice(0, start)}${replacement}${existing.slice(after)}`
+      .replace(/\n{3,}/g, "\n\n")
+      .replace(/^\n+|\n+$/g, "");
+    return { content: content ? `${content}\n` : "" };
   }
-  if (/^[ \t]*["']?portolan:(?:check|pages)["']?\s*:/m.test(existing)) {
+  if (/^[ \t]*["']?portolan:(?:check|review|pages)["']?\s*:/m.test(existing)) {
     return { conflict: "This pipeline already declares a Portolan job outside the managed region." };
   }
-  return { content: `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${gitlabBlock()}` };
+  const block = gitlabBlock(features);
+  return { content: block ? `${existing.trimEnd()}${existing.trim() ? "\n\n" : ""}${block}` : existing };
 }
 
 function textDiff(path, before, after) {
@@ -251,6 +355,16 @@ function readTarget(workspace, path) {
 function githubFile(workspace, path, content) {
   const current = readTarget(workspace, path);
   const managed = current.safe && current.content.startsWith(GENERATED);
+  if (content === null) {
+    if (!current.exists || !managed) return null;
+    return {
+      path,
+      status: "removed",
+      diff: textDiff(path, current.content, ""),
+      current: current.content,
+      next: "",
+    };
+  }
   const status = !current.exists ? "added" : !current.safe || !managed ? "conflict" : current.content === content ? "unchanged" : "changed";
   return {
     path,
@@ -262,39 +376,102 @@ function githubFile(workspace, path, content) {
   };
 }
 
-function gitlabFile(workspace) {
+function gitlabFile(workspace, features) {
   const path = ".gitlab-ci.yml";
   const current = readTarget(workspace, path);
   if (!current.safe) return { path, status: "conflict", message: "The existing pipeline is not a safe UTF-8 file.", diff: "", current: "", next: "" };
-  const merged = mergeGitlab(current.content);
+  const merged = mergeGitlab(current.content, features);
   if (merged.conflict) return { path, status: "conflict", message: merged.conflict, diff: "", current: current.content, next: "" };
-  const status = !current.exists ? "added" : current.content === merged.content ? "unchanged" : "changed";
+  const status = current.content === merged.content ? "unchanged" : !current.exists ? "added" : "changed";
   return { path, status, diff: textDiff(path, current.content, merged.content), current: current.content, next: merged.content };
 }
 
-function revisionFor(provider, files) {
+function revisionFor(provider, features, files) {
   const hash = createHash("sha256").update(provider);
+  hash.update("\0"); hash.update([...features].sort().join(","));
   for (const file of files) {
     hash.update("\0"); hash.update(file.path); hash.update("\0"); hash.update(file.current); hash.update("\0"); hash.update(file.next);
   }
   return hash.digest("hex");
 }
 
-export function planDeliveryPreset(workspace, requestedProvider) {
+function deliveryRequest(request) {
+  return typeof request === "string" || request == null ? { provider: request ?? undefined } : request;
+}
+
+function installedFeatures(workspace, provider) {
+  const selected = new Set();
+  if (provider === "github") {
+    const check = readTarget(workspace, ".github/workflows/portolan-check.yml");
+    const review = readTarget(workspace, ".github/workflows/portolan-review.yml");
+    const pages = readTarget(workspace, ".github/workflows/portolan-pages.yml");
+    if (check.safe && check.content.startsWith(GENERATED)) selected.add("check");
+    if (review.safe && review.content.startsWith(GENERATED)) {
+      selected.add("diff");
+      if (review.content.includes("sarif-output:")) selected.add("sarif");
+    }
+    if (pages.safe && pages.content.startsWith(GENERATED)) selected.add("pages");
+    return selected;
+  }
+  const pipeline = readTarget(workspace, ".gitlab-ci.yml");
+  if (!pipeline.safe || !pipeline.content.includes(GITLAB_START)) return selected;
+  const managed = pipeline.content.slice(
+    pipeline.content.indexOf(GITLAB_START),
+    pipeline.content.indexOf(GITLAB_END) + GITLAB_END.length,
+  );
+  if (/^[ \t]*["']?portolan:check["']?\s*:/m.test(managed)) selected.add("check");
+  if (/^[ \t]*["']?portolan:review["']?\s*:/m.test(managed)) selected.add("diff");
+  if (/^[ \t]*["']?portolan:pages["']?\s*:/m.test(managed)) selected.add("pages");
+  return selected;
+}
+
+function selectedFeatures(workspace, request, provider) {
+  const installed = request.features == null ? installedFeatures(workspace, provider) : null;
+  const raw = request.features == null
+    ? installed.size > 0 ? [...installed] : DEFAULT_FEATURES
+    : Array.isArray(request.features)
+      ? request.features
+      : String(request.features).split(",").filter(Boolean);
+  const selected = new Set(raw);
+  for (const feature of selected) {
+    if (!FEATURE_IDS.includes(feature)) throw new Error(`Unknown delivery feature ${feature}.`);
+  }
+  if (selected.has("sarif")) selected.add("diff");
+  if (provider !== "github" && selected.has("sarif")) {
+    throw new Error("SARIF annotations are currently available only for GitHub.");
+  }
+  return selected;
+}
+
+function featureOptions(provider, selected) {
+  return FEATURE_IDS.map((id) => ({
+    id,
+    ...FEATURE_DETAILS[id],
+    selected: selected.has(id),
+    available: id !== "sarif" || provider === "github",
+    requires: id === "sarif" ? ["diff"] : [],
+  }));
+}
+
+export function planDeliveryPreset(workspace, requested = {}) {
+  const request = deliveryRequest(requested);
   const detected = detectDeliveryForge(workspace);
-  const provider = requestedProvider || detected.provider || "github";
+  const provider = request.provider || detected.provider || "github";
   if (!PROVIDERS.has(provider)) throw new Error("Delivery preset must be github or gitlab.");
+  const features = selectedFeatures(workspace, request, provider);
   const files = provider === "github"
     ? [
-        githubFile(workspace, ".github/workflows/portolan-check.yml", githubCheck(detected.defaultBranch)),
-        githubFile(workspace, ".github/workflows/portolan-pages.yml", githubPages(detected.defaultBranch)),
-      ]
-    : [gitlabFile(workspace)];
+        githubFile(workspace, ".github/workflows/portolan-check.yml", features.has("check") ? githubCheck(detected.defaultBranch) : null),
+        githubFile(workspace, ".github/workflows/portolan-review.yml", features.has("diff") ? githubDiff({ pages: features.has("pages"), sarif: features.has("sarif") }) : null),
+        githubFile(workspace, ".github/workflows/portolan-pages.yml", features.has("pages") ? githubPages(detected.defaultBranch) : null),
+      ].filter(Boolean)
+    : [gitlabFile(workspace, features)];
   const status = files.some((file) => file.status === "conflict")
     ? "conflict"
     : files.every((file) => file.status === "unchanged")
       ? "installed"
-      : files.some((file) => file.status === "changed") && (provider !== "gitlab" || files[0].current.includes(GITLAB_START))
+      : files.some((file) => ["removed", "unchanged"].includes(file.status))
+          || files.some((file) => file.status === "changed" && (provider !== "gitlab" || file.current.includes(GITLAB_START)))
         ? "update"
         : "available";
   return {
@@ -304,8 +481,8 @@ export function planDeliveryPreset(workspace, requestedProvider) {
     repository: detected.repository,
     defaultBranch: detected.defaultBranch,
     status,
-    revision: revisionFor(provider, files),
-    features: ["Validate generated architecture in reviews", "Publish the static catalog"],
+    revision: revisionFor(provider, features, files),
+    features: featureOptions(provider, features),
     files,
   };
 }
@@ -315,7 +492,8 @@ export function publicDeliveryPreset(plan) {
 }
 
 export function installDeliveryPreset(workspace, request) {
-  const plan = planDeliveryPreset(workspace, request.provider);
+  const selection = { provider: request.provider, features: request.features };
+  const plan = planDeliveryPreset(workspace, selection);
   if (!request.revision || request.revision !== plan.revision) {
     const error = new Error("Files changed after this preset preview. Preview it again.");
     error.status = 409;
@@ -339,6 +517,11 @@ export function installDeliveryPreset(workspace, request) {
   for (const file of plan.files) {
     if (file.status === "unchanged") continue;
     const target = resolve(workspace, file.path);
+    if (file.status === "removed") {
+      rmSync(target);
+      written.push(file.path);
+      continue;
+    }
     mkdirSync(dirname(target), { recursive: true });
     const temporary = join(dirname(target), `.portolan-${randomUUID()}.tmp`);
     try {
@@ -349,5 +532,5 @@ export function installDeliveryPreset(workspace, request) {
     }
     written.push(file.path);
   }
-  return { ...publicDeliveryPreset(planDeliveryPreset(workspace, request.provider)), written };
+  return { ...publicDeliveryPreset(planDeliveryPreset(workspace, selection)), written };
 }

package/scripts/diff.mjs

@@ -29,6 +29,7 @@ import { enrichCatalog } from "../src/enrich.ts";
 import { mergeCatalogs } from "../src/merge.ts";
 import { diffCatalogs, SEVERITIES } from "../src/lib/catalog-diff.ts";
 import { loadCatalog } from "./catalog-sources.mjs";
+import { readManifestText } from "./manifest.mjs";
 
 const HEADINGS = {
   breaking: "Breaking",
@@ -142,7 +143,10 @@ function defaultBase() {
 
 /** The merged, enriched, validated catalog as it stood at `ref`. */
 function catalogAt(ref) {
-  const manifest = JSON.parse(git(["show", ref + ":portolan.json"]));
+  const manifest = readManifestText(
+    git(["show", ref + ":portolan.json"]),
+    `${ref}:portolan.json`,
+  );
   const patterns = (manifest.sources ?? []).map(globToRegExp);
 
   const paths = git(["ls-tree", "-r", "--name-only", ref])

package/scripts/gen-likec4.mjs

@@ -590,10 +590,11 @@ function containerPredicates(pairs, carried, indent) {
  * in a `break` frame, which is what a sequence diagram calls a branch that
  * leaves the flow rather than rejoining it.
  */
-// --- what comes back from a call (mirrors src/flow/answers.ts) -------------
-// Standalone calls keep the contract answer on the request label. Composition
-// turns a proven synchronous return into an explicit response step, so the
-// request then keeps only its own label and the return gets a dashed arrow.
+// --- request and response edges (mirrors src/flow/answers.ts) --------------
+// A unary RPC is two messages, not one long edge label. When composition has
+// already materialised a response step, that step is the return. Otherwise we
+// draw the contract response: immediately for a nested call, and at the end of
+// the flow for the actor request that opened it.
 const methodOf = new Map();
 const serviceById = new Map();
 for (const context of catalog.contexts) {
@@ -615,29 +616,43 @@ for (const external of catalog.externals ?? []) {
   }
 }
 
-function answerOf(step) {
-  if (step.kind !== "rpc") return "";
-  if (step.ref) return methodOf.get(step.ref)?.response ?? "";
+function contractOf(step) {
+  if (step.kind !== "rpc") return null;
+  if (step.ref) return methodOf.get(step.ref) ?? null;
   const service = serviceById.get(step.to);
-  if (!service || !step.label) return "";
+  if (!service || !step.label) return null;
   for (const provided of service.provides) {
     const found = provided.methods.find((m) => m.name === step.label);
-    if (found) return found.response ?? "";
+    if (found) return found;
   }
-  return "";
+  return null;
+}
+
+function emitSyntheticResponse(out, indent, node, response) {
+  out.push(
+    `${indent}${participantRef(node.to)} -> ${participantRef(node.from)} ${q(response)} {`,
+  );
+  out.push(
+    `${indent}  color ${node.status}  line dashed  head ${KIND_HEAD.response}`,
+  );
+  out.push(`${indent}}`);
 }
 
-function emitSteps(nodes, out, indent, replied) {
+function emitSteps(nodes, out, indent, replied, deferredResponseId) {
   for (const node of nodes) {
     if (node.type === "step") {
-      const answer = replied.has(node.id) ? "" : answerOf(node);
+      const contract = contractOf(node);
+      const request = contract?.request ?? "";
+      const response = replied.has(node.id) ? "" : (contract?.response ?? "");
       const storeLabel =
         node.storeAccess?.operation && node.storeAccess?.keyspace
           ? `${node.storeAccess.operation.toUpperCase()} ${node.storeAccess.keyspace}`
           : "";
       const label =
-        (storeLabel || node.label || node.ref || node.kind) +
-        (answer ? ` → ${answer}` : "");
+        storeLabel ||
+        (node.kind === "rpc" && request
+          ? request
+          : node.label || node.ref || node.kind);
       const attrs = [
         `color ${node.http?.outcome === "error" ? "response_error" : node.status}`,
         `line ${node.kind === "response" ? "dashed" : "solid"}`,
@@ -656,18 +671,21 @@ function emitSteps(nodes, out, indent, replied) {
       if (notes.length > 0)
         out.push(`${indent}  notes ${q(notes.join(" — "))}`);
       out.push(`${indent}}`);
+      if (response && node.id !== deferredResponseId) {
+        emitSyntheticResponse(out, indent, node, response);
+      }
       continue;
     }
     if (node.type === "parallel") {
       out.push(`${indent}par ${node.title ? `${q(node.title)} ` : ""}{`);
       for (const branch of node.branches)
-        emitSteps(branch, out, `${indent}  `, replied);
+        emitSteps(branch, out, `${indent}  `, replied, deferredResponseId);
       out.push(`${indent}}`);
       continue;
     }
     if (node.type === "loop") {
       out.push(`${indent}loop ${q(node.title)} {`);
-      emitSteps(node.steps, out, `${indent}  `, replied);
+      emitSteps(node.steps, out, `${indent}  `, replied, deferredResponseId);
       out.push(`${indent}}`);
       continue;
     }
@@ -678,10 +696,22 @@ function emitSteps(nodes, out, indent, replied) {
         out.push(`${indent}  ${keyword} ${q(branch.title)} {`);
         if (branch.terminal) {
           out.push(`${indent}    break 'ends the flow' {`);
-          emitSteps(branch.steps, out, `${indent}      `, replied);
+          emitSteps(
+            branch.steps,
+            out,
+            `${indent}      `,
+            replied,
+            deferredResponseId,
+          );
           out.push(`${indent}    }`);
         } else {
-          emitSteps(branch.steps, out, `${indent}    `, replied);
+          emitSteps(
+            branch.steps,
+            out,
+            `${indent}    `,
+            replied,
+            deferredResponseId,
+          );
         }
         out.push(`${indent}  }`);
       });
@@ -961,16 +991,34 @@ views.push("");
 for (const flow of catalog.flows) {
   const contexts = new Map(flow.participants.map((p) => [p.id, p.context]));
   const contextOf = (id) => contexts.get(id) ?? null;
+  const actorIds = new Set(
+    flow.participants.filter((p) => p.kind === "actor").map((p) => p.id),
+  );
   const replied = new Set();
   walkFlowSteps(flow.steps, (step) => {
     if (step.kind === "response" && step.replyTo) replied.add(step.replyTo);
   });
+  let deferredResponse = null;
+  walkFlowSteps(flow.steps, (step) => {
+    if (deferredResponse || step.kind !== "rpc" || !actorIds.has(step.from))
+      return;
+    const response = replied.has(step.id) ? "" : (contractOf(step)?.response ?? "");
+    if (response) deferredResponse = { step, response };
+  });
 
   views.push(`  dynamic view ${flowViewId(flow)} {`);
   views.push(`    title ${q(flow.name)}`);
   views.push(`    description ${q(flow.summary)}`);
   const body = [];
-  emitSteps(flow.steps, body, "    ", replied);
+  emitSteps(flow.steps, body, "    ", replied, deferredResponse?.step.id);
+  if (deferredResponse) {
+    emitSyntheticResponse(
+      body,
+      "    ",
+      deferredResponse.step,
+      deferredResponse.response,
+    );
+  }
   views.push(...body);
   views.push("  }");
   views.push("");
@@ -979,7 +1027,17 @@ for (const flow of catalog.flows) {
   views.push(`  dynamic view ${flowCrossViewId(flow)} {`);
   views.push(`    title ${q(`${flow.name} — crossings only`)}`);
   const crossBody = [];
-  emitSteps(cross, crossBody, "    ", replied);
+  const crossStepIds = new Set();
+  walkFlowSteps(cross, (step) => crossStepIds.add(step.id));
+  emitSteps(cross, crossBody, "    ", replied, deferredResponse?.step.id);
+  if (deferredResponse && crossStepIds.has(deferredResponse.step.id)) {
+    emitSyntheticResponse(
+      crossBody,
+      "    ",
+      deferredResponse.step,
+      deferredResponse.response,
+    );
+  }
   if (crossBody.length === 0) {
     // A flow with no crossing at all still needs a renderable view.
     const first = flow.participants[0];

package/scripts/gen-likec4.test.mjs

@@ -164,11 +164,34 @@ describe("the LikeC4 generator", () => {
             },
           ],
         },
+        {
+          id: "flow.get-book-contract",
+          slug: "get-book-contract",
+          name: "Get book contract",
+          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",
+            },
+          ],
+        },
       ],
     });
 
     expect(views).toContain(
-      "demo.api -> demo.book 'Get' {\n      color declared  line solid  head normal",
+      "demo.api -> demo.book 'GetRequest' {\n      color declared  line solid  head normal",
     );
     expect(views).toContain(
       "demo.book -> demo.api 'GetResponse' {\n      color declared  line dashed  head normal",
@@ -177,7 +200,7 @@ describe("the LikeC4 generator", () => {
       "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");
+    expect(views).not.toContain("GetRequest → GetResponse");
   });
 
   it("treats dots in a root participant id as data, not containment", () => {