@shortlink-org/portolan 0.2.1 → 0.2.3

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.",

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)
@@ -37,7 +38,11 @@ export async function loadCatalog(manifestPath = "portolan.json", { exclude = []
     if (!excluded.has(normalize(path))) paths.push(path);
   }
 
-  if (paths.length === 0) {
+  const emptyWorkspace = Array.isArray(manifest.projects)
+    && manifest.projects.length === 0
+    && (manifest.extract ?? []).length === 0
+    && (manifest.verify ?? []).length === 0;
+  if (paths.length === 0 && !emptyWorkspace) {
     throw new Error(
       `${manifestPath}: no catalog matched ${JSON.stringify(patterns)}`,
     );
@@ -49,6 +54,13 @@ export async function loadCatalog(manifestPath = "portolan.json", { exclude = []
       catalog: JSON.parse(readFileSync(path, "utf8")),
     })),
   );
+  if (paths.length === 0) {
+    // An intentionally empty workspace still needs a valid, deterministic
+    // catalog value for generators and the local preview. These are state
+    // markers, not provenance claims: there is no source file to stamp.
+    merged.catalog.generatedAt = "1970-01-01T00:00:00Z";
+    merged.catalog.commit = "empty";
+  }
 
   // The edges the flows imply are added before validation, the same way the
   // app does it, so a generator draws the same estate the reader sees.

package/scripts/catalog-sources.test.mjs

@@ -0,0 +1,45 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+
+import { loadCatalog } from "./catalog-sources.mjs";
+
+const roots = [];
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+function manifest(value) {
+  const root = mkdtempSync(join(tmpdir(), "portolan-empty-catalog-"));
+  roots.push(root);
+  const path = join(root, "portolan.json");
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+  return { path, missing: join(root, "portolan/*.json") };
+}
+
+describe("catalog sources", () => {
+  it("loads an intentional empty workspace as an empty catalog", async () => {
+    const { path, missing } = manifest({ sources: [], projects: [], extract: [], verify: [] });
+    writeFileSync(path, `${JSON.stringify({ sources: [missing], projects: [], extract: [], verify: [] }, null, 2)}\n`);
+    const loaded = await loadCatalog(path);
+    expect(loaded.sources).toEqual([]);
+    expect(loaded.catalog).toMatchObject({ contexts: [], defs: {}, flows: [], adrs: [] });
+  });
+
+  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",
+        name: "Billing",
+        root: "services/billing",
+        context: "shop",
+        service: "billing",
+      }],
+      extract: [],
+    }, null, 2)}\n`);
+    await expect(loadCatalog(path)).rejects.toThrow(/no catalog matched/);
+  });
+});

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])