@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/lib/setup-info.ts

@@ -7,6 +7,8 @@
  * bundle.
  */
 
+import { djangoAggregateCandidates, djangoAggregateMessage } from "./django-aggregates.ts";
+
 export type SetupPhase = "extract" | "verify" | "generate";
 
 export interface SetupProject {
@@ -59,6 +61,24 @@ export interface SetupRunStep extends SetupStep {
    * fix; a failed step's error stays out, because an error may quote anything.
    */
   warnings: string[];
+  diagnostics: SetupDiagnostic[];
+}
+
+export type SetupDiagnosticSeverity = "error" | "warning" | "info";
+
+export interface SetupDiagnostic {
+  aggregateCandidates?: import("./django-aggregates").DjangoAggregateCandidates;
+  plugin: string;
+  rule: string;
+  severity: SetupDiagnosticSeverity;
+  action: string;
+  message: string;
+  count: number;
+  project: string;
+  phase: SetupPhase;
+  ref?: string;
+  suppressed: boolean;
+  suppressionReason?: string;
 }
 
 export interface SetupRun {
@@ -249,6 +269,10 @@ function runStepFrom(
     .filter((warning): warning is string => typeof warning === "string" && warning.trim() !== "")
     .slice(0, MAX_WARNINGS)
     .map((warning) => warning.slice(0, MAX_WARNING_LENGTH));
+  const diagnostics = array(item.diagnostics)
+    .map((diagnostic) => diagnosticFrom(diagnostic, item.plugin as string, item.phase as SetupPhase))
+    .filter((diagnostic): diagnostic is SetupDiagnostic => diagnostic !== null)
+    .slice(0, MAX_WARNINGS);
 
   return {
     ordinal: item.ordinal,
@@ -267,6 +291,40 @@ function runStepFrom(
     changedCount: item.changedCount,
     files,
     warnings,
+    diagnostics,
+  };
+}
+
+function diagnosticFrom(value: unknown, plugin: string, phase: SetupPhase): SetupDiagnostic | null {
+  const item = record(value);
+  if (
+    item.plugin !== plugin || item.phase !== phase ||
+    typeof item.rule !== "string" || !/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/.test(item.rule) ||
+    !["error", "warning", "info"].includes(item.severity as string) ||
+    typeof item.action !== "string" || item.action.trim() === "" ||
+    typeof item.message !== "string" || item.message.trim() === "" ||
+    !wholeNumber(item.count) || item.count < 1 ||
+    typeof item.project !== "string" ||
+    typeof item.suppressed !== "boolean"
+  ) return null;
+  const ref = typeof item.ref === "string" && item.ref.trim() !== "" ? item.ref.slice(0, MAX_WARNING_LENGTH) : undefined;
+  const suppressionReason = typeof item.suppressionReason === "string" && item.suppressionReason.trim() !== ""
+    ? item.suppressionReason.slice(0, MAX_WARNING_LENGTH)
+    : undefined;
+  if (item.suppressed && !suppressionReason) return null;
+  return {
+    plugin,
+    rule: item.rule,
+    severity: item.severity as SetupDiagnosticSeverity,
+    action: item.action.slice(0, MAX_WARNING_LENGTH),
+    message: djangoAggregateMessage(item.message).slice(0, MAX_WARNING_LENGTH),
+    ...(djangoAggregateCandidates(item.message) ? { aggregateCandidates: djangoAggregateCandidates(item.message)! } : {}),
+    count: item.count,
+    project: item.project.slice(0, MAX_WARNING_LENGTH),
+    phase,
+    ...(ref ? { ref } : {}),
+    suppressed: item.suppressed,
+    ...(suppressionReason ? { suppressionReason } : {}),
   };
 }
 

package/src/lib/shape.test.ts

@@ -211,6 +211,38 @@ describe("schemaChanges", () => {
     expect(removed.map((f) => f.name)).toEqual(["gone"]);
   });
 
+  it("a field whose rules moved is changed, with the rules it had", () => {
+    const rules = {
+      id: "x.y.R",
+      versions: [
+        {
+          version: "v1",
+          fields: [
+            { name: "code", type: "string", doc: "", rules: [{ name: "min_len", value: "8" }] },
+            { name: "who", type: "string", doc: "" },
+            { name: "same", type: "string", doc: "", rules: [{ name: "in", value: "a, b" }, { name: "unique" }] },
+            { name: "both", type: "int32", doc: "", required: true },
+          ],
+        },
+        {
+          version: "v2",
+          fields: [
+            { name: "code", type: "string", doc: "", rules: [{ name: "min_len", value: "12" }] },
+            { name: "who", type: "string", doc: "", required: true, rules: [{ name: "format", value: "uuid" }] },
+            // The same rules in another order are the same rules.
+            { name: "same", type: "string", doc: "", rules: [{ name: "unique" }, { name: "in", value: "a, b" }] },
+            { name: "both", type: "int64", doc: "" },
+          ],
+        },
+      ],
+    } as unknown as Event;
+    const { byField } = schemaChanges(rules, "v2");
+    expect(byField.get("code")).toEqual({ change: "changed", rulesFrom: "≥ 8 chars" });
+    expect(byField.get("who")).toEqual({ change: "changed", rulesFrom: "" });
+    expect(byField.get("same")).toBeUndefined();
+    expect(byField.get("both")).toEqual({ change: "changed", from: "int32", rulesFrom: "required" });
+  });
+
   it("agrees with the fixture: OrderPlaced v2 added channel", () => {
     const placed = eventById("shop.oms.order.OrderPlaced");
     const { byField, removed } = schemaChanges(placed, "v2");

package/src/lib/shape.ts

@@ -26,6 +26,7 @@ import type {
 } from "../catalog";
 import { aggregateBlocks, blockFields, enumsOf } from "../catalog";
 import type { DefUsage } from "./derive";
+import { ruleMarks } from "./rules";
 
 /** How many of the base type a field holds. */
 export type Cardinality = "one" | "many" | "map";
@@ -336,13 +337,19 @@ export interface FieldChange {
   change: Change;
   /** The type the field had in the previous version, when it changed. */
   from?: string;
+  /**
+   * The rules the field had in the previous version, as the marks read -
+   * "required, ≤ 8 chars" - when this version changed them; "" when it had
+   * none. The row itself shows what they are now.
+   */
+  rulesFrom?: string;
 }
 
 /**
  * What a version did to the schema: the fields it added, the ones whose
- * type it changed, and - by name, since they are no longer in the version's
- * own list - the ones it dropped. The first version changes nothing: there
- * is nothing before it to differ from.
+ * type or rules it changed, and - by name, since they are no longer in the
+ * version's own list - the ones it dropped. The first version changes
+ * nothing: there is nothing before it to differ from.
  */
 export function schemaChanges(
   event: Event,
@@ -360,9 +367,14 @@ export function schemaChanges(
   const now = new Set(current.fields.map((f) => f.name));
   for (const field of current.fields) {
     const was = before.get(field.name);
-    if (!was) byField.set(field.name, { change: "new" });
-    else if (was.type !== field.type)
-      byField.set(field.name, { change: "changed", from: was.type });
+    if (!was) {
+      byField.set(field.name, { change: "new" });
+      continue;
+    }
+    const change: FieldChange = { change: "changed" };
+    if (was.type !== field.type) change.from = was.type;
+    if (!sameRules(was, field)) change.rulesFrom = ruleMarks(was).map((m) => m.text).join(", ");
+    if (change.from !== undefined || change.rulesFrom !== undefined) byField.set(field.name, change);
   }
   for (const field of prev.fields) {
     if (!now.has(field.name)) removed.push(field);
@@ -370,6 +382,18 @@ export function schemaChanges(
   return { byField, removed };
 }
 
+/**
+ * Whether two versions of a field ask the same of its value. The order the
+ * rules are listed in is the source's, not a fact about the value, so it
+ * is not a difference.
+ */
+function sameRules(a: Field, b: Field): boolean {
+  if (Boolean(a.required) !== Boolean(b.required)) return false;
+  const key = (field: Field) =>
+    (field.rules ?? []).map((r) => `${r.name}=${r.value ?? ""}`).sort().join("\n");
+  return key(a) === key(b);
+}
+
 // ---------------------------------------------------------------------------
 // An enum and a lifecycle.
 // ---------------------------------------------------------------------------

package/src/lib/tech.ts

@@ -30,6 +30,7 @@ import {
   siApachepulsar,
   siArgo,
   siAuth0,
+  siBackstage,
   siBun,
   siC,
   siCelery,
@@ -37,6 +38,7 @@ import {
   siClickhouse,
   siClojure,
   siCloudflare,
+  siConfluence,
   siCockroachlabs,
   siConsul,
   siCouchbase,
@@ -93,7 +95,9 @@ import {
   siLinkerd,
   siLua,
   siMariadb,
+  siMarkdown,
   siMeilisearch,
+  siMermaid,
   siMinio,
   siMongodb,
   siMqtt,
@@ -107,6 +111,7 @@ import {
   siNginx,
   siNodedotjs,
   siNomad,
+  siNotion,
   siNpm,
   siOllama,
   siOpenapiinitiative,
@@ -346,6 +351,11 @@ export const TECH_MARKS: readonly TechMark[] = [
   mark(siJenkins),
   mark(siArgo, "Argo CD", "ArgoCD"),
 
+  // Where a team writes. Not read off a manifest; the marks are for the
+  // reader-side integrations that open the wiki from a page.
+  mark(siConfluence),
+  mark(siNotion),
+
   // Observability.
   mark(siOpentelemetry, "otel"),
   mark(siPrometheus),
@@ -374,6 +384,11 @@ export const TECH_MARKS: readonly TechMark[] = [
   mark(siJest),
   mark(siVitest),
   mark(siCypress),
+
+  // What the generators write to.
+  mark(siMarkdown),
+  mark(siMermaid),
+  mark(siBackstage),
 ];
 
 const BY_KEY: ReadonlyMap<string, TechGlyph> = (() => {
@@ -417,5 +432,6 @@ export const STORE_KIND_GLYPH: Record<StoreKind, TechGlyph | null> = {
   clickhouse: techGlyph("clickhouse"),
   // simple-icons was asked to drop Amazon's marks, S3's among them.
   s3: null,
+  dynamodb: null,
   other: null,
 };

package/src/lib/trace-project.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+
+import { projectForFlow, projectsForFlow } from "./trace-project";
+
+const projects = [
+  { id: "auth", name: "Auth", root: "examples/auth", context: "auth", service: "auth" },
+  { id: "shop-cart", name: "Cart", root: "examples/shop/cart", context: "shop", service: "cart" },
+  { id: "shop-oms", name: "OMS", root: "examples/shop/oms", group: "shop", component: "oms" },
+];
+
+const flow = (owner: string, ...services: string[]) => ({
+  owner,
+  participants: [
+    { id: "client", kind: "actor" as const, context: null },
+    ...services.map((id) => ({ id, kind: "service" as const, context: id.split(".")[0] ?? null })),
+    { id: "bus", kind: "broker" as const, context: null },
+  ],
+});
+
+describe("which project a recording of a flow belongs to", () => {
+  it("is the one project in the flow's context", () => {
+    expect(projectForFlow(projects, flow("auth", "auth.auth"))?.id).toBe("auth");
+  });
+
+  it("is the project whose service the flow runs through when the context has several", () => {
+    expect(projectForFlow(projects, flow("shop", "shop.oms", "shop.pricing"))?.id).toBe("shop-oms");
+    expect(projectsForFlow(projects, flow("shop", "shop.cart")).map((p) => p.id)).toEqual(["shop-cart", "shop-oms"]);
+  });
+
+  it("is nobody's when the context has no project, or two the flow runs through", () => {
+    expect(projectForFlow(projects, flow("payments", "payments.ledger"))).toBeNull();
+    expect(projectForFlow(projects, flow("shop", "shop.cart", "shop.oms"))).toBeNull();
+  });
+});

package/src/lib/trace-project.ts

@@ -0,0 +1,50 @@
+// Which project a recording of a flow belongs to.
+//
+// A recording is kept beside the project whose verify step reads it, and a
+// flow says which context owns it - one level up from a project. The project
+// is the one in that context whose service the flow runs through; when the
+// context has one project, that one; otherwise the page has to ask.
+
+import type { Flow } from "../catalog";
+import type { SetupProject } from "./setup-info";
+
+/** The projects a flow's recording could be kept under, the likeliest first. */
+export function projectsForFlow(
+  projects: readonly SetupProject[],
+  flow: Pick<Flow, "owner" | "participants">,
+): SetupProject[] {
+  const inContext = projects.filter(
+    (project) => (project.group ?? project.context) === flow.owner,
+  );
+  const services = new Set(
+    flow.participants
+      .filter((p) => p.kind === "service" && p.context === flow.owner)
+      .map((p) => p.id.split(".").slice(1).join(".")),
+  );
+  const runsThrough = (project: SetupProject) =>
+    services.has(project.component ?? project.service ?? "");
+
+  return [...inContext].sort(
+    (a, b) => Number(runsThrough(b)) - Number(runsThrough(a)) || a.id.localeCompare(b.id),
+  );
+}
+
+/** The one project a recording of the flow goes to, or null when it has to be asked. */
+export function projectForFlow(
+  projects: readonly SetupProject[],
+  flow: Pick<Flow, "owner" | "participants">,
+): SetupProject | null {
+  const candidates = projectsForFlow(projects, flow);
+  if (candidates.length === 1) return candidates[0]!;
+  if (candidates.length === 0) return null;
+  const services = new Set(
+    flow.participants
+      .filter((p) => p.kind === "service" && p.context === flow.owner)
+      .map((p) => p.id.split(".").slice(1).join(".")),
+  );
+  const through = candidates.filter((project) =>
+    services.has(project.component ?? project.service ?? ""),
+  );
+
+  return through.length === 1 ? through[0]! : null;
+}

package/src/lib/use-problems.ts

@@ -0,0 +1,23 @@
+// The problems of the live catalog, for a component.
+//
+// Five places show the same list - the page, the sidebar badge, the overview,
+// the landing's demo, the rules table - and each used to compute it once on
+// mount. Now the list depends on the rules in force, which the Settings page
+// changes under a running app, so the computation subscribes to them and the
+// five places re-render together when a switch is flipped.
+
+import { useMemo } from "react";
+import { catalog, index } from "../data";
+import { evaluateProblems } from "./all-problems";
+import type { Problem } from "./derive";
+import { useProblemRules } from "./problem-rules";
+import type { RuleEvaluation } from "./problem-rules";
+
+export function useProblemEvaluation(): RuleEvaluation {
+  const rules = useProblemRules();
+  return useMemo(() => evaluateProblems(catalog, index, rules), [rules]);
+}
+
+export function useProblems(): Problem[] {
+  return useProblemEvaluation().problems;
+}

package/src/lib/warnings.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { groupDiagnostics, groupWarnings, warningDiagnostic } from "./warnings";
+
+describe("warning diagnostics", () => {
+  it("assigns a stable rule, severity and action to known warnings", () => {
+    const diagnostic = warningDiagnostic({
+      plugin: "openapi",
+      message: "aviacore-api: no operationId on 2 of 9 operations; listed by verb and path: POST /book, POST /cancel",
+    });
+
+    expect(diagnostic).toMatchObject({
+      plugin: "openapi",
+      rule: "openapi.missing-operation-id",
+      severity: "warning",
+      ref: "aviacore-api",
+      suppressed: false,
+    });
+    expect(diagnostic.action).toContain("operationId");
+  });
+
+  it("groups repetitions by plugin, rule and severity", () => {
+    const groups = groupWarnings([
+      { plugin: "openapi", message: "api.v1: no operationId on 1 of 3 operations; listed by verb and path: POST /book" },
+      { plugin: "openapi", message: "api.v2: no operationId on 1 of 3 operations; listed by verb and path: POST /cancel" },
+      { plugin: "wsdl", message: "b/schema.xsd: duplicate declaration CodeType and 2 more in namespace urn:common; the declarations in a/schema.xsd are used" },
+    ]);
+
+    expect(groups.map(({ plugin, rule, count }) => ({ plugin, rule, count }))).toEqual([
+      { plugin: "openapi", rule: "openapi.missing-operation-id", count: 2 },
+      { plugin: "wsdl", rule: "schema.duplicate-declaration", count: 1 },
+    ]);
+  });
+
+  it("keeps one rule across the wordings the plugins emit for it", () => {
+    const rules = [
+      "calls ledger.v1 and the manifest names no peer for it; add it under `peers` to say which service answers, until then the calls are unresolved",
+      "src/app.rs: port `clock: Clock` is neither a domain port, a use case nor a client; its calls are left out of the flow",
+      "bus/router.go:12:3: Watermill handler orders is registered on topic `cfg.Topic`, which this reader cannot resolve to a literal, a constant, a config default or a caller's argument; the handler is kept with its topic unresolved",
+    ].map((message) => warningDiagnostic({ plugin: "x", message }).rule);
+    expect(rules).toEqual(["catalog.unmapped-proto-peer", "flow.unknown-port", "watermill.unresolved-topic"]);
+  });
+
+  it("marks read and parse failures as errors and expected absence as info", () => {
+    expect(warningDiagnostic({ plugin: "sql", message: "schema.sql could not be parsed" }).severity).toBe("error");
+    expect(warningDiagnostic({ plugin: "river", message: "root: no River jobs were found" }).severity).toBe("info");
+  });
+
+  it("groups persisted policy decisions without evaluating policies in the browser", () => {
+    const diagnostic = warningDiagnostic({ plugin: "openapi", message: "api: no operationId on 1 of 3 operations; listed by verb and path: POST /book" });
+    const groups = groupDiagnostics([{ ...diagnostic, suppressed: true, suppressionReason: "Owned upstream." }]);
+    expect(groups[0]).toMatchObject({ suppressed: true, suppressionReason: "Owned upstream.", count: 1 });
+  });
+
+  it("keeps unrelated unknown warnings in separate fallback rules", () => {
+    const groups = groupWarnings([
+      { plugin: "custom", message: "service: frobnicator needs attention" },
+      { plugin: "custom", message: "service: another limitation was observed" },
+    ]);
+
+    expect(groups).toHaveLength(2);
+    expect(groups.every((group) => group.rule.startsWith("plugin.custom.other-"))).toBe(true);
+  });
+});