@shortlink-org/portolan 0.2.1 → 0.2.3

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/init.mjs

@@ -75,13 +75,14 @@ export async function init(workspace, { version, ask = defaultAnswers, log = con
   writeManifest(manifestPath, manifest);
   log("created portolan.json");
 
-  const scripts = projectPackage ? await ask.scripts(Object.keys(SCRIPTS).filter((name) => !(name in (projectPackage.scripts ?? {})))) : false;
-  if (scripts) {
+  const addScripts = projectPackage ? await ask.scripts(Object.keys(SCRIPTS).filter((name) => !(name in (projectPackage.scripts ?? {})))) : false;
+  if (addScripts) {
     const merged = { ...(projectPackage.scripts ?? {}) };
     for (const [name, command] of Object.entries(SCRIPTS)) if (!(name in merged)) merged[name] = command;
     writeFileSync(resolve(workspace, "package.json"), `${JSON.stringify({ ...projectPackage, scripts: merged }, null, 2)}\n`);
     log("added architecture scripts to package.json");
   }
+  const scriptsReady = Boolean(projectPackage) && Object.keys(SCRIPTS).every((name) => addScripts || name in (projectPackage.scripts ?? {}));
 
   const ignorePath = resolve(workspace, ".gitignore");
   const ignore = existsSync(ignorePath) ? readFileSync(ignorePath, "utf8") : "";
@@ -90,10 +91,17 @@ export async function init(workspace, { version, ask = defaultAnswers, log = con
   }
 
   const generate = await ask.generate();
-  ask.finish(generate);
+  ask.finish(generate, scriptsReady);
   return { manifest, projects, generate };
 }
 
+export function nextStep(generate, scriptsReady) {
+  const command = scriptsReady
+    ? generate ? "npm run architecture" : "npm run architecture:gen && npm run architecture"
+    : generate ? "npx @shortlink-org/portolan dev" : "npx @shortlink-org/portolan generate && npx @shortlink-org/portolan dev";
+  return `${generate ? "Generating; then" : "Next"}: ${command}`;
+}
+
 /** Every question answered with its default: the `--yes` and CI path. */
 export const defaultAnswers = {
   roots: (choices) => choices.filter((choice) => choice.selected).map((choice) => choice.path),
@@ -103,7 +111,7 @@ export const defaultAnswers = {
   write: () => true,
   scripts: (names) => names.length > 0,
   generate: () => false,
-  finish: (generate) => { if (!generate) console.log("next: portolan generate && portolan dev"); },
+  finish: (generate, scriptsReady) => { if (!generate) console.log(nextStep(generate, scriptsReady)); },
 };
 
 /** The same questions, asked in a terminal with @clack/prompts. */
@@ -163,8 +171,8 @@ export function promptAnswers(version) {
     async generate() {
       return answer(await p.confirm({ message: "Run portolan generate now?", initialValue: true }));
     },
-    finish(generate) {
-      p.outro(generate ? "Generating; then: portolan dev" : "Next: portolan generate && portolan dev");
+    finish(generate, scriptsReady) {
+      p.outro(nextStep(generate, scriptsReady));
     },
   };
 }

package/cli/init.test.mjs

@@ -4,7 +4,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { afterEach, beforeAll, describe, expect, it } from "vitest";
 
-import { InitError, defaultAnswers, init } from "./init.mjs";
+import { InitError, defaultAnswers, init, nextStep } from "./init.mjs";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const created = [];
@@ -36,6 +36,13 @@ const goService = {
 };
 
 describe("init with defaults", () => {
+  it("prints runnable next commands with and without package scripts", () => {
+    expect(nextStep(false, true)).toBe("Next: npm run architecture:gen && npm run architecture");
+    expect(nextStep(true, true)).toBe("Generating; then: npm run architecture");
+    expect(nextStep(false, false)).toBe("Next: npx @shortlink-org/portolan generate && npx @shortlink-org/portolan dev");
+    expect(nextStep(true, false)).toBe("Generating; then: npx @shortlink-org/portolan dev");
+  });
+
   it("reads what the repository contains into one project at the root", async () => {
     const dir = workspace({
       "package.json": '{"name":"@acme/order-service","scripts":{"test":"vitest"}}\n',

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(", ")}` : ""}`);
@@ -175,10 +205,10 @@ async function dev(workspace, options) {
   });
 }
 
-async function prepareSite(workspace) {
+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 });
@@ -189,14 +219,18 @@ async function prepareSite(workspace) {
   for (const file of ["index.html", "vite.config.ts", "tsconfig.json"]) {
     copyFileSync(resolve(installRoot, file), resolve(stage, file));
   }
-  writeFileSync(resolve(stage, "package.json"), '{"private":true,"type":"module"}\n');
+  writeFileSync(resolve(stage, "package.json"), `${JSON.stringify({ private: true, type: "module", version: VERSION })}\n`);
 
   const patternSets = [manifest.sources ?? [], ...(manifest.catalogs ?? []).map((profile) => profile.sources ?? [])];
   const allSources = new Set();
   for (const patterns of patternSets) {
     for (const path of await matchedFiles(workspace, patterns)) allSources.add(path);
   }
-  if (allSources.size === 0) fail("no catalog source matches portolan.json; run portolan generate first");
+  const emptyWorkspace = Array.isArray(manifest.projects)
+    && manifest.projects.length === 0
+    && (manifest.extract ?? []).length === 0
+    && (manifest.verify ?? []).length === 0;
+  if (allSources.size === 0 && !emptyWorkspace) fail("no catalog source matches portolan.json; run portolan generate first");
 
   const flattened = new Map();
   let ordinal = 0;
@@ -204,16 +238,27 @@ async function prepareSite(workspace) {
     const name = `portolan/source-${String(++ordinal).padStart(4, "0")}.json`;
     flattened.set(source, name);
     copyIntoStage(workspace, stage, source, name);
-    copyReferencedFiles(workspace, stage, JSON.parse(readFileSync(resolve(workspace, source), "utf8")));
+    const catalog = JSON.parse(readFileSync(resolve(workspace, source), "utf8"));
+    copyReferencedFiles(workspace, stage, catalog);
+    copyReadmeAssets(workspace, stage, catalog);
+  }
+  let stagedSources = [...flattened.values()];
+  if (allSources.size === 0) {
+    const name = "portolan/source-0000.json";
+    mkdirSync(dirname(resolve(stage, name)), { recursive: true });
+    writeFileSync(resolve(stage, name), `${JSON.stringify({ generatedAt: "1970-01-01T00:00:00Z", commit: "empty", contexts: [], defs: {}, flows: [], adrs: [] }, null, 2)}\n`);
+    stagedSources = [name];
   }
 
   const stagedManifest = {
     ...manifest,
-    sources: [...flattened.values()],
+    sources: stagedSources,
     ...(manifest.catalogs ? {
       catalogs: await Promise.all(manifest.catalogs.map(async (profile) => ({
         ...profile,
-        sources: (await matchedFiles(workspace, profile.sources ?? [])).map((path) => flattened.get(path)).filter(Boolean),
+        sources: allSources.size === 0
+          ? stagedSources
+          : (await matchedFiles(workspace, profile.sources ?? [])).map((path) => flattened.get(path)).filter(Boolean),
       }))),
     } : {}),
   };
@@ -258,6 +303,40 @@ function copyReferencedFiles(workspace, stage, value) {
   visit(value);
 }
 
+function copyReadmeAssets(workspace, stage, catalog) {
+  for (const context of catalog.contexts ?? []) {
+    for (const service of context.services ?? []) {
+      if (typeof service.path !== "string" || typeof service.readme !== "string") continue;
+      const root = resolve(workspace, service.path);
+      if (!inside(workspace, root)) continue;
+      for (const target of markdownTargets(service.readme)) {
+        const source = resolveMarkdownTarget(root, target);
+        if (!source || !inside(root, source) || !existsSync(source) || !statSync(source).isFile()) continue;
+        const relativeSource = relative(workspace, source).split(sep).join("/");
+        copyIntoStage(workspace, stage, relativeSource, `public/portolan-assets/${relativeSource}`);
+      }
+    }
+  }
+}
+
+function markdownTargets(markdown) {
+  const targets = [];
+  const links = /!?\[[^\]]*\]\(\s*(?:<([^>\n]+)>|([^\s)\n]+))(?:\s+["'][^"']*["'])?\s*\)/g;
+  for (const match of markdown.matchAll(links)) targets.push(match[1] ?? match[2]);
+  const html = /<(?:img|source)\b[^>]*\bsrc=["']([^"']+)["'][^>]*>/gi;
+  for (const match of markdown.matchAll(html)) targets.push(match[1]);
+  return targets.filter(Boolean);
+}
+
+function resolveMarkdownTarget(root, target) {
+  const value = String(target).trim();
+  if (!value || value.startsWith("#") || value.startsWith("/") || /^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(value)) return null;
+  const pathname = value.split(/[?#]/, 1)[0];
+  if (!pathname) return null;
+  try { return resolve(root, decodeURIComponent(pathname)); }
+  catch { return null; }
+}
+
 function copyIntoStage(workspace, stage, source, target) {
   const from = resolve(workspace, source);
   const to = resolve(stage, target);
@@ -295,7 +374,7 @@ function prepareHost(workspace) {
   mkdirSync(host, { recursive: true });
   cpSync(resolve(installRoot, "scripts"), resolve(host, "scripts"), { recursive: true });
   cpSync(resolve(installRoot, "src"), resolve(host, "src"), { recursive: true });
-  writeFileSync(resolve(host, "package.json"), '{"private":true,"type":"module"}\n');
+  writeFileSync(resolve(host, "package.json"), `${JSON.stringify({ private: true, type: "module", version: VERSION })}\n`);
   symlinkSync(dependencyRoot(), resolve(host, "node_modules"), process.platform === "win32" ? "junction" : "dir");
   return host;
 }

package/cli/portolan.test.mjs

@@ -0,0 +1,47 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { prepareSite, VERSION } from "./portolan.mjs";
+
+const roots = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe("site staging", () => {
+  it("stages a deterministic source for an intentional empty workspace", async () => {
+    const root = mkdtempSync(join(tmpdir(), "portolan-empty-site-"));
+    roots.push(root);
+    writeFileSync(join(root, "portolan.json"), `${JSON.stringify({ sources: ["portolan/*.json"], projects: [], extract: [], verify: [], generate: [] }, null, 2)}\n`);
+
+    const stage = await prepareSite(root);
+    const stagedPackage = JSON.parse(readFileSync(join(stage, "package.json"), "utf8"));
+    const stagedManifest = JSON.parse(readFileSync(join(stage, "portolan.json"), "utf8"));
+    expect(stagedPackage.version).toBe(VERSION);
+    expect(stagedManifest.sources).toEqual(["portolan/source-0000.json"]);
+    expect(existsSync(join(stage, "portolan/source-0000.json"))).toBe(true);
+  });
+
+  it("stages binary files referenced by a service README as public assets", async () => {
+    const root = mkdtempSync(join(tmpdir(), "portolan-readme-assets-"));
+    roots.push(root);
+    const project = "vendor/repos/acme/shop";
+    mkdirSync(join(root, project, "portolan"), { recursive: true });
+    mkdirSync(join(root, project, "docs"), { recursive: true });
+    const image = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0xff, 0x00]);
+    writeFileSync(join(root, project, "docs/example.png"), image);
+    writeFileSync(join(root, project, "README.md"), "# Shop\n");
+    writeFileSync(join(root, project, "portolan/project.json"), `${JSON.stringify({
+      generatedAt: "2026-09-09T00:00:00Z",
+      commit: "abc1234",
+      contexts: [{ id: "shop", slug: "shop", name: "Shop", services: [{ id: "shop.api", slug: "api", name: "API", repo: "github.com/acme/shop", path: project, readme: "![example](./docs/example.png)", provides: [], consumes: [], aggregates: [] }] }],
+      defs: {}, flows: [], adrs: [],
+    }, null, 2)}\n`);
+    writeFileSync(join(root, "portolan.json"), `${JSON.stringify({ sources: [`${project}/portolan/*.json`] }, null, 2)}\n`);
+
+    const stage = await prepareSite(root);
+    expect(readFileSync(join(stage, "public/portolan-assets", project, "docs/example.png"))).toEqual(image);
+  });
+});

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.1",
+  "version": "0.2.3",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/shortlink-org/portolan#readme",
@@ -67,19 +67,20 @@
     "prepack": "npm run plugins:build"
   },
   "dependencies": {
-    "@tailwindcss/vite": "^4.0.0",
-    "@vitejs/plugin-react": "^6.1.1",
-    "@ai-sdk/openai-compatible": "3.0.44",
-    "@ai-sdk/react": "4.0.96",
+    "@ai-sdk/openai-compatible": "3.0.45",
+    "@ai-sdk/react": "4.0.98",
     "@asyncapi/react-component": "^3.1.8",
     "@clack/prompts": "^1.8.0",
+    "@floating-ui/react": "^0.27.20",
     "@headlessui/react": "^2.2.10",
     "@scalar/api-reference-react": "^0.9.66",
+    "@tailwindcss/vite": "^4.0.0",
     "@tanstack/react-query": "^5.102.8",
     "@tanstack/react-table": "^9.2.4",
     "@tanstack/react-virtual": "^3.14.10",
+    "@vitejs/plugin-react": "^6.1.1",
     "@xyflow/react": "^12.11.5",
-    "ai": "7.0.93",
+    "ai": "7.0.95",
     "ajv": "^8.20.0",
     "elkjs": "^0.12.0",
     "html-to-image": "^1.11.13",

package/plugins/extract-django/README.md

@@ -244,7 +244,7 @@ without it the wrapper is shown as an operation inside the current service.
 vendored from. The code names the verb and the route —
 `self._http.post("/v1/quotes")`, httpx or requests alike — and the document
 says which operation answers there, so the call is recorded under the id the
-callee's own extractor gives it: `pricing.v1.Quotes/createQuote`, spelled by
+callee's own extractor gives it: `pricing.v1/createQuote`, spelled by
 the same rules as `plugins/openapi`. The peer is the manifest's `peers` entry
 for that api id; without one the lane is `unknown` and the step unresolved.
 Without a document there is no id to share, and the call is recorded against

package/plugins/extract-django/extract_test.py

@@ -265,7 +265,7 @@ class Reading(unittest.TestCase):
         self.assertEqual(wire["InvoiceIssued"], {"name": "billing.InvoiceIssued", "channel": "shop.billing.invoice"})
 
     def test_a_client_call_is_the_id_the_callee_would_give_it(self):
-        self.assertEqual([c["id"] for c in self.service["consumes"]], ["pricing.v1.Quotes/createQuote"])
+        self.assertEqual([c["id"] for c in self.service["consumes"]], ["pricing.v1/createQuote"])
         self.assertEqual(self.service["consumes"][0]["peer"], "shop.pricing")
 
     def test_the_http_contract_points_at_the_generated_openapi_document(self):

package/plugins/extract-django/openapi.py

@@ -2,7 +2,7 @@
 
 The same rules as `plugins/openapi/ids.go`, spelled a second time so that a
 Django caller and the service that answers spell one call the same way:
-`auth.v1.Sessions/validateSession` on both sides, or the call would never
+`auth.v1/validateSession` on both sides, or the call would never
 resolve to the method.
 
 The reader underneath is a small one. A document is a mapping of mappings with
@@ -16,7 +16,6 @@ from __future__ import annotations
 
 import json
 import os
-import re
 from dataclasses import dataclass, field
 from typing import Any, Dict, List, Optional
 
@@ -30,18 +29,9 @@ def api_id(title: str, version: str) -> str:
     return name + ".v" + major if major else name
 
 
-def title_of(name: str) -> str:
-    """users becomes Users, price_list becomes PriceList: it sits in an id
-    beside a proto-shaped service name."""
-    out = ""
-    for word in re.split(r"[_\-\s]+", name):
-        if word:
-            out += word[0].upper() + word[1:]
-    return out
-
-
-def interface_id(api: str, tag: str) -> str:
-    return api + "." + title_of(tag) if tag else api
+def interface_id(api: str, _tag: str) -> str:
+    """Tags organise operations inside a contract; they do not create interfaces."""
+    return api
 
 
 @dataclass

package/plugins/extract-django/openapi_test.py

@@ -20,9 +20,9 @@ class Ids(unittest.TestCase):
         self.assertEqual(openapi.api_id("Price List", "2.1.0"), "price-list.v2")
         self.assertEqual(openapi.api_id("", ""), "api")
 
-    def test_an_interface_is_the_api_and_the_first_tag(self):
-        self.assertEqual(openapi.interface_id("auth.v1", "sessions"), "auth.v1.Sessions")
-        self.assertEqual(openapi.interface_id("auth.v1", "price_list"), "auth.v1.PriceList")
+    def test_tags_stay_inside_the_document_interface(self):
+        self.assertEqual(openapi.interface_id("auth.v1", "sessions"), "auth.v1")
+        self.assertEqual(openapi.interface_id("auth.v1", "price_list"), "auth.v1")
         self.assertEqual(openapi.interface_id("auth.v1", ""), "auth.v1")
 
     def test_a_parameter_is_compared_by_position(self):
@@ -39,7 +39,7 @@ class Read(unittest.TestCase):
         self.assertEqual([o.id for o in spec.operations], ["createQuote"])
         found = spec.find("POST", "/v1/quotes")
         self.assertIsNotNone(found)
-        self.assertEqual(found.call_id(spec.api), "pricing.v1.Quotes/createQuote")
+        self.assertEqual(found.call_id(spec.api), "pricing.v1/createQuote")
 
     def test_a_route_the_document_does_not_declare_finds_nothing(self):
         spec = openapi.read(DOCUMENT)

package/plugins/extract-go/options.schema.json

@@ -29,6 +29,11 @@
       "type": "string",
       "description": "What the service is called on the page. Defaults to the title of its README, and failing that to the slug, titled."
     },
+    "scope": {
+      "type": "string",
+      "description": "Deployable name in a shared Go module. Limits owned source to internal/<scope> while allowing calls to imported application packages to be followed.",
+      "examples": ["api", "billing"]
+    },
     "repo": {
       "type": "string",
       "description": "Where the source lives. Defaults to the module path in go.mod.",

package/plugins/extract-project/options.schema.json

@@ -18,6 +18,10 @@
       "enum": ["bounded-context", "system", "product", "team", "namespace"],
       "description": "Semantic role of the top-level group. Defaults to system for this neutral extractor."
     },
+    "classification": {
+      "enum": ["core", "supporting", "generic"],
+      "description": "DDD classification of a bounded context when the group represents one."
+    },
     "component": {
       "type": "string",
       "description": "Slug of the component. Defaults to the input directory name."
@@ -39,6 +43,23 @@
       "type": "string",
       "description": "Source repository identity. Defaults to a Go module, package.json repository, Cargo package, or Maven coordinates when present."
     },
+    "components": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["slug"],
+        "properties": {
+          "slug": { "type": "string", "minLength": 1 },
+          "name": { "type": "string", "minLength": 1 },
+          "kind": {
+            "enum": ["service", "application", "webapp", "worker", "job", "function", "cli", "library", "data-pipeline"]
+          }
+        }
+      },
+      "description": "Independently deployable runtime components found inside one repository. When present, the singular component fields are ignored."
+    },
     "out": {
       "type": "string",
       "description": "Name of the fragment file inside the step output directory.",

package/plugins/extract-ts/README.md

@@ -221,7 +221,7 @@ bus; a field read off one is not.
 the path in the code - `client.GET("/v1/sessions/current", …)` - and the
 document vendored beside `gen/types.ts` says which operation answers on that
 route and which interface it belongs to, spelled by `plugins/openapi` so the
-call and the method on the other side share one id: `auth.v1.Sessions/validateSession`.
+call and the method on the other side share one id: `auth.v1/validateSession`.
 **gRPC peer.** A Connect-ES client is created from a service descriptor whose
 `typeName` is the proto service, `shop.v1.Pricing`, and a call on it is the
 method in the descriptor's own case: `client.getQuote(…)` is

package/plugins/extract-ts/clients.ts

@@ -18,7 +18,7 @@ import type { WarningSink } from "./domain.ts";
 
 /** One call the adapter makes, in the catalog's terms. */
 export interface RpcHop {
-  /** "auth.v1.Sessions/validateSession" or "shop.v1.Pricing/GetQuote" */
+  /** "auth.v1/validateSession" or "shop.v1.Pricing/GetQuote" */
   id: string;
   /** What the manifest's peers map is keyed by: the api id or the proto package. */
   pkg: string;

package/plugins/extract-ts/extract.test.ts

@@ -114,7 +114,7 @@ describe("the service", () => {
 
   it("records what it calls, named the way the callee names the method", () => {
     expect(svc.consumes.map((c: { id: string; peer: string; status: string }) => `${c.id}→${c.peer}:${c.status}`)).toEqual([
-      "auth.v1.Sessions/validateSession→auth.auth:declared",
+      "auth.v1/validateSession→auth.auth:declared",
       "shop.v1.Pricing/GetQuote→shop.pricing:declared",
     ]);
   });
@@ -146,7 +146,7 @@ describe("the flows", () => {
     ]);
     expect(checkout.participants.map((p) => `${p.id}/${p.kind}`)).toContain("auth.auth/service");
     const rpc = checkout.steps[1] as Step;
-    expect(rpc.ref).toBe("auth.v1.Sessions/validateSession");
+    expect(rpc.ref).toBe("auth.v1/validateSession");
   });
 
   it("opens a policy on the bus and draws its choices", () => {

package/plugins/extract-ts/graphql.test.ts

@@ -45,13 +45,13 @@ describe("a service read through its resolvers", () => {
   it("follows the port on the context to the peer behind it", () => {
     const [, second] = flow("bff-query-viewer").steps as Step[];
 
-    expect(second).toMatchObject({ from: "storefront.bff", to: "auth.auth", ref: "auth.v1.Sessions/validateSession" });
+    expect(second).toMatchObject({ from: "storefront.bff", to: "auth.auth", ref: "auth.v1/validateSession" });
   });
 
   it("names the call among what the service consumes", () => {
     const { consumes } = fragment().contexts[0]!.services[0]!;
 
-    expect(consumes).toEqual([{ id: "auth.v1.Sessions/validateSession", peer: "auth.auth", status: "declared", source: `${ROOT}/src/infrastructure/auth/gen/openapi.yaml` }]);
+    expect(consumes).toEqual([{ id: "auth.v1/validateSession", peer: "auth.auth", status: "declared", source: `${ROOT}/src/infrastructure/auth/gen/openapi.yaml` }]);
   });
 
   // A resolver that answers out of its arguments reaches nothing, and the flow

package/plugins/extract-ts/openapi.test.ts

@@ -2,7 +2,7 @@ import { mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { describe, expect, it } from "vitest";
-import { apiID, callID, documentApiID, findOperation, interfaceID, readSpec, tagTitle } from "./openapi.ts";
+import { apiID, callID, documentApiID, findOperation, interfaceID, readSpec } from "./openapi.ts";
 
 // The same cases plugins/openapi/ids_test.go holds the Go side to.
 describe("openapi ids", () => {
@@ -14,9 +14,8 @@ describe("openapi ids", () => {
     expect(documentApiID(" stripe.v1 ", "Stripe API", "2026-08-26.dahlia")).toBe("stripe.v1");
     expect(documentApiID("", "Stripe API", "2026-08-26.dahlia")).toBe("stripe-api.v2026-08-26");
   });
-  it("titles tags and builds interface ids", () => {
-    expect(tagTitle("price_list")).toBe("PriceList");
-    expect(interfaceID("auth.v1", "sessions")).toBe("auth.v1.Sessions");
+  it("keeps tags inside the document's interface", () => {
+    expect(interfaceID("auth.v1", "sessions")).toBe("auth.v1");
     expect(interfaceID("auth.v1", "")).toBe("auth.v1");
   });
 });
@@ -55,9 +54,9 @@ describe("readSpec and findOperation", () => {
   });
   it("finds a route however the parameter is spelled", () => {
     const login = findOperation(spec, "post", "/v1/sessions")!;
-    expect(callID(spec, login)).toBe("auth.v1.Sessions/login");
-    expect(callID(spec, findOperation(spec, "GET", "/v1/users/{userId}")!)).toBe("auth.v1.Users/getUser");
-    expect(callID(spec, findOperation(spec, "GET", "/v1/users/${id}")!)).toBe("auth.v1.Users/getUser");
+    expect(callID(spec, login)).toBe("auth.v1/login");
+    expect(callID(spec, findOperation(spec, "GET", "/v1/users/{userId}")!)).toBe("auth.v1/getUser");
+    expect(callID(spec, findOperation(spec, "GET", "/v1/users/${id}")!)).toBe("auth.v1/getUser");
     expect(callID(spec, findOperation(spec, "GET", "/v1/health")!)).toBe("auth.v1/GET /v1/health");
     expect(findOperation(spec, "DELETE", "/v1/sessions")).toBeUndefined();
   });

package/plugins/extract-ts/openapi.ts

@@ -25,16 +25,9 @@ export function documentApiID(declared: string, title: string, version: string):
 }
 
 /** users → Users, price_list → PriceList. */
-export function tagTitle(name: string): string {
-  return name
-    .split(/[_\- ]+/)
-    .filter(Boolean)
-    .map((w) => (w[0]! >= "a" && w[0]! <= "z" ? w[0]!.toUpperCase() + w.slice(1) : w))
-    .join("");
-}
-
-export function interfaceID(api: string, tag: string): string {
-  return tag ? `${api}.${tagTitle(tag)}` : api;
+/** Tags organise operations inside an OpenAPI contract; they do not create interfaces. */
+export function interfaceID(api: string, _tag: string): string {
+  return api;
 }
 
 export const VERBS = ["get", "put", "post", "delete", "options", "head", "patch", "trace"];