@shortlink-org/portolan 0.2.0 → 0.2.2

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

@@ -175,7 +175,7 @@ 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"));
@@ -189,14 +189,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 +208,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 +273,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 +344,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.0",
+  "version": "0.2.2",
   "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.97",
     "@asyncapi/react-component": "^3.1.8",
     "@clack/prompts": "^1.8.0",
+    "@floating-ui/react": "^0.27.0",
     "@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.94",
     "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"];

package/schema/portolan.schema.json

@@ -888,6 +888,16 @@
           "minLength": 1,
           "description": "Component slug inside the group."
         },
+        "components": {
+          "type": "array",
+          "minItems": 2,
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "description": "Deployable component slugs discovered inside one repository-backed project."
+        },
         "groupKind": {
           "enum": [
             "bounded-context",
@@ -1025,6 +1035,14 @@
           ],
           "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."
@@ -1058,6 +1076,41 @@
           "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.",
@@ -1133,6 +1186,14 @@
           "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.",