@shortlink-org/portolan 0.2.2 → 0.2.4

package/README.md

@@ -201,8 +201,13 @@ for against what is on `PATH`. The Docker image contains all of them.
 
 While `portolan dev` is running, open **Settings → Delivery presets**. Portolan
 detects GitHub or GitLab from the repository's `origin`, previews the exact CI
-changes, and installs architecture checks and static catalog publishing in one
-step. Existing unmanaged workflow files are never overwritten.
+changes, and generates only the jobs selected there. Architecture checks and
+static catalog publishing are selected by default; pull-request architecture
+diffs and GitHub SARIF annotations are opt-in. Check, review, and publication
+live in separate GitHub workflows, while SARIF augments the review workflow, so
+comment and code-scanning permissions are granted only when those capabilities
+are enabled. Existing unmanaged workflow files are never overwritten, and
+disabling a capability removes only files managed by Portolan.
 
 ### Run without installing Node or language toolchains
 

package/cli/portolan.mjs

@@ -19,6 +19,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
 import { fileURLToPath } from "node:url";
 
 import { InitError, commandWorks, init as runInit, isInteractive, promptAnswers, toolchainFor } from "./init.mjs";
+import { loadManifest, readManifest } from "../scripts/manifest.mjs";
 
 const installRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const packageJson = JSON.parse(readFileSync(resolve(installRoot, "package.json"), "utf8"));
@@ -54,7 +55,10 @@ export async function main(argv = process.argv.slice(2)) {
       return dev(workspace, parsed);
     case "diff":
       if (!parsed.positionals[0]) fail("diff requires a base branch, tag, or commit");
-      return runScript("scripts/diff.mjs", parsed.positionals, workspace);
+      return runScript("scripts/diff.mjs", diffArgs(parsed), workspace);
+    case "comment":
+      if (!parsed.positionals[0]) fail("comment requires a markdown file");
+      return runScript("scripts/forge-comment.mjs", [parsed.positionals[0]], workspace);
     case "doctor":
       return doctor(workspace);
     default:
@@ -68,7 +72,7 @@ function parse(argv) {
     const arg = argv[index];
     if (arg === "--help" || arg === "-h") value.help = true;
     else if (arg === "--version" || arg === "-v") value.version = true;
-    else if (["--cwd", "--output", "--base", "--host", "--port"].includes(arg)) {
+    else if (["--cwd", "--output", "--base", "--host", "--port", "--format", "--site", "--head"].includes(arg)) {
       const next = argv[++index];
       if (!next) fail(`${arg} requires a value`);
       value[arg.slice(2)] = next;
@@ -80,6 +84,14 @@ function parse(argv) {
   return value;
 }
 
+function diffArgs(parsed) {
+  const args = [parsed.positionals[0]];
+  for (const name of ["format", "output", "site", "head"]) {
+    if (parsed[name]) args.push(`--${name}`, parsed[name]);
+  }
+  return args;
+}
+
 function help() {
   console.log(`Portolan ${VERSION}
 
@@ -92,6 +104,7 @@ Commands:
   check      fail when committed generated files are out of date
   build      build the static site
   diff BASE  describe architecture changes against BASE
+  comment FILE  post or update a pull-request comment from Markdown
   doctor     check the local runtime and project configuration
   version    print the CLI version
 
@@ -99,6 +112,9 @@ Options:
   --cwd DIR       project directory (default: current directory)
   --output DIR    build output (default: dist)
   --base PATH     deployed URL base (default: /)
+  --format TYPE   diff format: markdown, json, or sarif
+  --site URL      catalog URL linked from an architecture diff
+  --head BRANCH   head branch linked from an architecture diff
   --host HOST     dev server host (default: 127.0.0.1)
   --port PORT     dev server port
   --yes, -y       init without questions: take every detected default`);
@@ -118,10 +134,24 @@ async function init(workspace, options) {
 
 function doctor(workspace) {
   const manifestPath = resolve(workspace, "portolan.json");
-  const manifest = existsSync(manifestPath) ? JSON.parse(readFileSync(manifestPath, "utf8")) : null;
+  let manifest = null;
+  let manifestProblems = [];
+  if (existsSync(manifestPath)) {
+    try {
+      const loaded = loadManifest(manifestPath);
+      manifest = loaded.manifest;
+      manifestProblems = loaded.problems;
+    } catch (cause) {
+      manifestProblems = [cause instanceof Error ? cause.message : String(cause)];
+    }
+  }
   const checks = [
     ["Node.js >= 24", Number(process.versions.node.split(".")[0]) >= 24, process.version],
-    ["portolan.json", Boolean(manifest), "required"],
+    [
+      "portolan.json",
+      Boolean(manifest) && manifestProblems.length === 0,
+      manifestProblems.length > 0 ? manifestProblems.join("; ") : "required",
+    ],
     ["Git", commandWorks("git", ["--version"]), "used for deterministic source stamps"],
   ];
 
@@ -157,7 +187,7 @@ async function build(workspace, options) {
   runNode(packageBin("vite", "bin/vite.js"), ["build", stage, "--config", resolve(stage, "vite.config.ts"), "--outDir", output, "--emptyOutDir"], workspace, env);
 
   const { siteDocs } = await import(resolve(installRoot, "scripts/site-docs.mjs"));
-  const manifest = JSON.parse(readFileSync(resolve(workspace, "portolan.json"), "utf8"));
+  const manifest = readManifest(resolve(workspace, "portolan.json"));
   const written = siteDocs({ manifest, dist: output });
   copyFileSync(resolve(output, "index.html"), resolve(output, "404.html"));
   console.log(`site: ${relative(workspace, output) || "."}${written.length ? `; mounted ${written.join(", ")}` : ""}`);
@@ -178,7 +208,7 @@ async function dev(workspace, options) {
 export async function prepareSite(workspace) {
   const manifestPath = resolve(workspace, "portolan.json");
   if (!existsSync(manifestPath)) fail("portolan.json is missing; run portolan init first");
-  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const manifest = readManifest(manifestPath);
   const stage = resolve(workspace, ".portolan", "site");
   rmSync(stage, { recursive: true, force: true });
   mkdirSync(stage, { recursive: true });

package/package.json

@@ -2,7 +2,7 @@
   "name": "@shortlink-org/portolan",
   "description": "Generate a navigable architecture catalog from code and specifications.",
   "private": false,
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/shortlink-org/portolan#readme",
@@ -68,10 +68,10 @@
   },
   "dependencies": {
     "@ai-sdk/openai-compatible": "3.0.45",
-    "@ai-sdk/react": "4.0.97",
+    "@ai-sdk/react": "4.0.98",
     "@asyncapi/react-component": "^3.1.8",
     "@clack/prompts": "^1.8.0",
-    "@floating-ui/react": "^0.27.0",
+    "@floating-ui/react": "^0.27.20",
     "@headlessui/react": "^2.2.10",
     "@scalar/api-reference-react": "^0.9.66",
     "@tailwindcss/vite": "^4.0.0",
@@ -80,7 +80,7 @@
     "@tanstack/react-virtual": "^3.14.10",
     "@vitejs/plugin-react": "^6.1.1",
     "@xyflow/react": "^12.11.5",
-    "ai": "7.0.94",
+    "ai": "7.0.95",
     "ajv": "^8.20.0",
     "elkjs": "^0.12.0",
     "html-to-image": "^1.11.13",

package/plugins/README.md

@@ -1142,6 +1142,11 @@ live in another estate — would be the wrong end of the trade.
 service declares — the address the broker knows, and each message on it with the
 direction it travels. What it does **not** answer with is events.
 
+A message's `contentType`, or the document's `defaultContentType` when the
+message leaves it out, is kept as the exact declared media type. MessagePack
+media types are additionally normalized to `encoding: msgpack`, so source and
+contract extractors can be compared without depending on one MIME spelling.
+
 That looks like a gap and is a boundary. `Event.id` is
 `<service>.<aggregate>.<Name>`, and an AsyncAPI document knows the message on the
 wire, not the aggregate that raised it. An extractor that guessed would either

package/plugins/extract-python-kafka/README.md

@@ -22,6 +22,12 @@ id, consumer group, key, headers and serializer facts. Authentication values
 are never emitted. Partitions, replication and retention are broker-side facts
 and remain explicitly unknown unless another catalog source declares them.
 
+MessagePack serializers and deserializers declared through `msgpack` or
+`messagepack` calls are normalized to `encoding: "msgpack"` on the affected
+channel message. This includes constructor callbacks and payloads packed
+directly before a publish; Portolan records the wire format without importing
+or executing the codec.
+
 ```json
 {
   "plugin": "python-kafka",

package/plugins/extract-python-kafka/extract.py

@@ -99,7 +99,7 @@ def channel(topic: str, sends: List[kafka.Publish], receives: List[kafka.Subscri
     for item in sends:
         key = (item.message, "send")
         if key not in seen:
-            messages.append(catalog.message(item.message, title(item.message), message_doc(item), "send"))
+            messages.append(catalog.message(item.message, title(item.message), message_doc(item), "send", item.encoding))
             seen.add(key)
     for item in receives:
         # Kafka subscriptions dispatch records, and source often does not prove
@@ -108,7 +108,7 @@ def channel(topic: str, sends: List[kafka.Publish], receives: List[kafka.Subscri
         name = sends[0].message if len({sent.message for sent in sends}) == 1 else "message"
         key = (name, "receive")
         if key not in seen:
-            messages.append(catalog.message(name, title(name), consumer_doc(item), "receive"))
+            messages.append(catalog.message(name, title(name), consumer_doc(item), "receive", item.client.encoding))
             seen.add(key)
     clients = []
     for item in list(sends) + list(receives):

package/plugins/extract-python-kafka/extract_test.py

@@ -1,5 +1,6 @@
 """Framework-neutral Kafka extraction contracts."""
 
+import ast
 import json
 import os
 import sys
@@ -9,6 +10,7 @@ sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 sys.path.insert(1, os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "pyplugin"))
 
 from extract import extract  # noqa: E402
+import kafka  # noqa: E402
 from options import Options  # noqa: E402
 from protocol import Builder, Input  # noqa: E402
 
@@ -33,7 +35,7 @@ class PythonKafka(unittest.TestCase):
 
     def test_three_standard_clients_form_message_channels(self):
         channels = {item["address"]: item for item in self.service["channels"]}
-        self.assertEqual(sorted(channels), ["audit.records", "orders.created", "payments.accepted"])
+        self.assertEqual(sorted(channels), ["audit.records", "inventory.snapshots", "orders.created", "payments.accepted"])
         self.assertTrue(all(item["kind"] == "message" for item in channels.values()))
         self.assertEqual(
             [message["direction"] for message in channels["orders.created"]["messages"]],
@@ -50,6 +52,20 @@ class PythonKafka(unittest.TestCase):
         self.assertNotIn("sasl.password", self.contents)
         self.assertNotIn("sasl.username", self.contents)
 
+    def test_messagepack_serializer_and_deserializer_are_machine_readable(self):
+        snapshots = next(item for item in self.service["channels"] if item["address"] == "inventory.snapshots")
+        self.assertEqual([message["encoding"] for message in snapshots["messages"]], ["msgpack", "msgpack"])
+        self.assertIn("value serializer: lambda value: msgpack.packb(value)", snapshots["doc"])
+        self.assertIn("value deserializer: msgpack.unpackb", snapshots["doc"])
+
+    def test_direct_messagepack_call_keeps_the_payload_name(self):
+        call = ast.parse("msgpack.packb(snapshot)", mode="eval").body
+        self.assertEqual(kafka.payload_name(call), "snapshot")
+        self.assertEqual(kafka.payload_encoding(call), "msgpack")
+        packer = ast.parse("msgpack.Packer()", mode="eval").body
+        method = ast.parse("packer.pack(snapshot)", mode="eval").body
+        self.assertEqual(kafka.payload_encoding(method, {"packer": ("expr", packer)}), "msgpack")
+
     def test_publish_and_receive_flows_have_kafka_handoffs_and_source(self):
         steps = [step for flow in self.fragment["flows"] for step in flow["steps"]]
         handoffs = [step["handoff"] for step in steps]

package/plugins/pyplugin/catalog.py

@@ -81,13 +81,24 @@ def channel(address: str, kind: str, title: str, doc: str, messages: List[Dict[s
     return out
 
 
-def message(name: str, title: str, doc: str, direction: str) -> Dict[str, Any]:
+def message(
+    name: str,
+    title: str,
+    doc: str,
+    direction: str,
+    encoding: str = "",
+    content_type: str = "",
+) -> Dict[str, Any]:
     out: Dict[str, Any] = {"name": name}
     if title:
         out["title"] = title
     if doc:
         out["doc"] = doc
     out["direction"] = direction
+    if encoding:
+        out["encoding"] = encoding
+    if content_type:
+        out["contentType"] = content_type
     return out
 
 

package/plugins/pyplugin/kafka.py

@@ -23,6 +23,8 @@ class Spec:
 CONSTRUCTORS = {
     "confluent_kafka.Producer": Spec("confluent-kafka", "producer"),
     "confluent_kafka.Consumer": Spec("confluent-kafka", "consumer"),
+    "confluent_kafka.SerializingProducer": Spec("confluent-kafka", "producer"),
+    "confluent_kafka.DeserializingConsumer": Spec("confluent-kafka", "consumer"),
     "kafka.KafkaProducer": Spec("kafka-python", "producer"),
     "kafka.KafkaConsumer": Spec("kafka-python", "consumer"),
     "aiokafka.AIOKafkaProducer": Spec("aiokafka", "producer"),
@@ -62,6 +64,23 @@ CONFIG_KEYS = {
     "enable_auto_commit": "auto commit",
     "key_serializer": "key serializer",
     "value_serializer": "value serializer",
+    "key_deserializer": "key deserializer",
+    "value_deserializer": "value deserializer",
+    "key.serializer": "key serializer",
+    "value.serializer": "value serializer",
+    "key.deserializer": "key deserializer",
+    "value.deserializer": "value deserializer",
+}
+
+SERDE_KEYS = {
+    "key_serializer",
+    "value_serializer",
+    "key_deserializer",
+    "value_deserializer",
+    "key.serializer",
+    "value.serializer",
+    "key.deserializer",
+    "value.deserializer",
 }
 
 
@@ -73,6 +92,10 @@ class Client:
     source: str = ""
     constructor_topics: List[str] = field(default_factory=list)
 
+    @property
+    def encoding(self) -> str:
+        return encoding_of_text(" ".join(str(self.config.get(key, "")) for key in ("value serializer", "value deserializer")))
+
 
 @dataclass
 class Publish:
@@ -86,6 +109,7 @@ class Publish:
     message_expression: str
     key: str = ""
     headers: str = ""
+    encoding: str = ""
 
     @property
     def line(self) -> str:
@@ -181,6 +205,8 @@ def value(
         for key_node, val_node in zip(node.keys, node.values):
             key = value(project, module, key_node, settings, variables, depth + 1)
             val = value(project, module, val_node, settings, variables, depth + 1)
+            if val is None and isinstance(key, str) and key in SERDE_KEYS:
+                val = serialization_expression(module, val_node, variables)
             if not isinstance(key, str) or val is None:
                 continue
             out[key] = val
@@ -239,14 +265,21 @@ def _config_values(project: Project, module: Module, call: ast.Call, settings: s
         first = value(project, module, call.args[0], settings, variables)
         if isinstance(first, dict):
             raw.update(first)
+        # Callable serializer values are not safe scalar values, but their
+        # syntax is still the evidence needed to identify MessagePack.
+        if isinstance(call.args[0], ast.Dict):
+            for key_node, val_node in zip(call.args[0].keys, call.args[0].values):
+                key = value(project, module, key_node, settings, variables)
+                if isinstance(key, str) and key in SERDE_KEYS and key not in raw:
+                    raw[key] = serialization_expression(module, val_node, variables)
     for kw in call.keywords:
         if not kw.arg:
             continue
         resolved = value(project, module, kw.value, settings, variables)
         if resolved is not None:
             raw[kw.arg] = resolved
-        elif kw.arg in ("key_serializer", "value_serializer"):
-            raw[kw.arg] = expression(kw.value)
+        elif kw.arg in SERDE_KEYS:
+            raw[kw.arg] = serialization_expression(module, kw.value, variables)
     out: Dict[str, Any] = {}
     for key, val in raw.items():
         normalized = CONFIG_KEYS.get(key)
@@ -377,7 +410,7 @@ def payload_name(node: Optional[ast.AST], variables: Optional[Dict[str, Tuple[st
         return node.id
     if isinstance(node, ast.Call):
         last = dotted(node.func).split(".")[-1]
-        if last in ("dumps", "dump", "encode", "serialize", "SerializeToString", "asdict", "dict", "model_dump") and node.args:
+        if last in ("dumps", "dump", "encode", "serialize", "SerializeToString", "asdict", "dict", "model_dump", "pack", "packb") and node.args:
             return payload_name(node.args[0], variables, depth + 1)
         return last or "message"
     if isinstance(node, ast.Attribute):
@@ -387,6 +420,43 @@ def payload_name(node: Optional[ast.AST], variables: Optional[Dict[str, Tuple[st
     return "message"
 
 
+def encoding_of_text(text: str) -> str:
+    lowered = text.lower()
+    if "msgpack" in lowered or "messagepack" in lowered:
+        return "msgpack"
+    return ""
+
+
+def serialization_expression(module: Optional[Module], node: Optional[ast.AST], variables: Optional[Dict[str, Tuple[str, object]]] = None) -> str:
+    if node is None:
+        return ""
+    parts = [expression(node)]
+    if module is not None:
+        parts.append(external_name(module, dotted(node.func) if isinstance(node, ast.Call) else dotted(node)))
+    owner = node.func.value if isinstance(node, ast.Call) and isinstance(node.func, ast.Attribute) else (node.value if isinstance(node, ast.Attribute) else None)
+    if isinstance(owner, ast.Name):
+        bound = (variables or {}).get(owner.id)
+        if bound is not None and bound[0] == "expr" and isinstance(bound[1], ast.AST):
+            parts.append(expression(bound[1]))
+    return " ".join(filter(None, parts))
+
+
+def payload_encoding(
+    node: Optional[ast.AST],
+    variables: Optional[Dict[str, Tuple[str, object]]] = None,
+    depth: int = 0,
+    module: Optional[Module] = None,
+) -> str:
+    if node is None or depth > 6:
+        return ""
+    variables = variables or {}
+    if isinstance(node, ast.Name):
+        bound = variables.get(node.id)
+        if bound is not None and bound[0] == "expr" and isinstance(bound[1], ast.AST):
+            return payload_encoding(bound[1], variables, depth + 1, module)
+    return encoding_of_text(serialization_expression(module, node, variables))
+
+
 def _text(node: Optional[ast.AST]) -> str:
     text = expression(node)
     return text if len(text) <= 100 else text[:97] + "..."
@@ -541,6 +611,7 @@ class Scanner:
                 _text(payload),
                 _text(keyword(call, "key")),
                 _text(keyword(call, "headers")),
+                payload_encoding(payload, env, module=module) or client.encoding,
             )
         )
 

package/scripts/builtin-plugins.mjs

@@ -4,10 +4,11 @@
 // package happens to run them. Custom plugins may still be declared in the
 // manifest with `process` or `wasm`; those declarations always win.
 
-import { readFileSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { readManifest } from "./manifest.mjs";
+
 export const INSTALL_ROOT = process.env.PORTOLAN_INSTALL_ROOT
   ? resolve(process.env.PORTOLAN_INSTALL_ROOT)
   : resolve(dirname(fileURLToPath(import.meta.url)), "..");
@@ -16,7 +17,7 @@ let definitions;
 
 function shippedDefinitions() {
   if (definitions) return definitions;
-  const manifest = JSON.parse(readFileSync(resolve(INSTALL_ROOT, "portolan.json"), "utf8"));
+  const manifest = readManifest(resolve(INSTALL_ROOT, "portolan.json"));
   definitions = new Map((manifest.plugins ?? []).map((plugin) => [plugin.name, plugin]));
   return definitions;
 }

package/scripts/catalog-sources.mjs

@@ -14,6 +14,7 @@ import { validateCatalog } from "../src/catalog.ts";
 import { filterCatalogForProfile } from "../src/catalog-profile.ts";
 import { enrichCatalog } from "../src/enrich.ts";
 import { mergeCatalogs } from "../src/merge.ts";
+import { readManifest } from "./manifest.mjs";
 
 /**
  * `exclude` names source files to leave out, as the manifest would spell
@@ -22,7 +23,7 @@ import { mergeCatalogs } from "../src/merge.ts";
  * what it wrote last time would count as what it saw this time.
  */
 export async function loadCatalog(manifestPath = "portolan.json", { exclude = [], profile } = {}) {
-  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  const manifest = readManifest(manifestPath);
   const excluded = new Set(exclude.map((path) => normalize(path)));
   const selected = profile
     ? (manifest.catalogs ?? []).find((candidate) => candidate.id === profile)

package/scripts/catalog-sources.test.mjs

@@ -29,7 +29,17 @@ describe("catalog sources", () => {
 
   it("still reports missing sources for a configured project", async () => {
     const { path, missing } = manifest({ sources: [], projects: [] });
-    writeFileSync(path, `${JSON.stringify({ sources: [missing], projects: [{ id: "billing" }], extract: [] }, null, 2)}\n`);
+    writeFileSync(path, `${JSON.stringify({
+      sources: [missing],
+      projects: [{
+        id: "billing",
+        name: "Billing",
+        root: "services/billing",
+        context: "shop",
+        service: "billing",
+      }],
+      extract: [],
+    }, null, 2)}\n`);
     await expect(loadCatalog(path)).rejects.toThrow(/no catalog matched/);
   });
 });