@shortlink-org/portolan 0.2.4 → 0.4.0

package/src/pages/ServicePage.tsx

@@ -10,11 +10,18 @@ import {
   technologiesOf,
 } from "../catalog";
 import { flowRoles } from "../lib/derive";
+import { bridges } from "../lib/centrality";
 import { treeHref } from "../lib/source-link";
 import { flowHealth } from "../lib/flow-tree";
 import { adrsForService, isCurrent } from "../lib/adr";
 import { ADR_ROW_COLUMNS, AdrRow } from "../components/AdrRow";
-import { EVENT_ANCHOR, SERVICE_ANCHOR, aggregatePath, paths } from "../routes";
+import {
+  EVENT_ANCHOR,
+  OVERVIEW_ANCHOR,
+  SERVICE_ANCHOR,
+  aggregatePath,
+  paths,
+} from "../routes";
 import { Markdown } from "../components/Markdown";
 import { middleTruncate, plural } from "../lib/format";
 import { Empty, PageHeader, SectionTitle } from "../components/PageHeader";
@@ -31,6 +38,8 @@ import {
   hasAsyncSpec,
 } from "../components/AsyncApiReference";
 import { ChannelRows } from "../components/ChannelRows";
+import { DocsLinks } from "../components/DocsLinks";
+import { DeploymentRows } from "../components/DeploymentRows";
 import { CommandRows } from "../components/CommandRows";
 import { ModuleSpec } from "../components/SourceDoc";
 import { hasSchema, SchemaDocument } from "../components/SchemaDocument";
@@ -45,7 +54,11 @@ import { NotFound } from "./NotFound";
 import { C4View } from "../likec4/C4View";
 import { LevelSwitch } from "../likec4/levels";
 import type { C4Level } from "../likec4/levels";
-import { serviceInsideViewId, serviceViewId } from "../likec4/ids";
+import {
+  serviceDeployViewId,
+  serviceInsideViewId,
+  serviceViewId,
+} from "../likec4/ids";
 import { index } from "../data";
 import { storesOfService } from "../lib/data-model";
 import { ErCanvas } from "../er/ErCanvas";
@@ -112,6 +125,11 @@ export function ServicePage() {
   const flows = flowRoles(catalog, service.id);
   const tree = treeHref(service.path, service, allRepos(catalog));
   const owners = ownersOf(service);
+  const deployments = index.deploymentsByService.get(service.id) ?? [];
+  // The service as a road: the pairs of contexts it stands between, if any.
+  // Derived from the whole estate, so it is computed here and not carried
+  // on the service, which knows only its own edges.
+  const road = bridges(catalog).find((b) => b.id === service.id) ?? null;
   const adrs = adrsForService(catalog, service.id, context.id);
   const current = adrs.filter(isCurrent);
   const retired = adrs.filter((a) => !isCurrent(a));
@@ -130,6 +148,7 @@ export function ServicePage() {
     .find((source) => source !== undefined && hasAsyncSpec(source));
   const showDomain =
     componentKind(service) === "service" || service.aggregates.length > 0;
+  const hasModelGroups = service.aggregates.some((aggregate) => aggregate.kind === "model-group");
   const integrations = integrationsFor(service, catalog);
 
   const counts: Record<Tab, number | null> = {
@@ -167,6 +186,17 @@ export function ServicePage() {
         right={
           <>
             <span className="chip-lg">{componentKind(service)}</span>
+            {road ? (
+              <Link
+                to={`${paths.overview()}#${OVERVIEW_ANCHOR.bridges}`}
+                className="chip-lg border-line text-muted hover:text-ink"
+                title={`${Math.round(road.betweenness * 100)}% of the shortest paths between other services run through this one — see the bridges on the overview`}
+              >
+                bridge
+                <span className="text-muted">·</span>
+                {road.between.map((pair) => `${pair.a} ↔ ${pair.b}`).join(", ")}
+              </Link>
+            ) : null}
             <ContextPill id={context.id} name={context.name} />
           </>
         }
@@ -185,6 +215,7 @@ export function ServicePage() {
               open ↗
             </a>
           ) : null}
+          <DocsLinks name={service.name} />
           {/* Who to ask, read out of CODEOWNERS. A handle is copied rather
               than linked: it is what a reviewer types into a request, and a
               link to a team page is a page most readers cannot open. */}
@@ -219,7 +250,7 @@ export function ServicePage() {
               className="rounded-control hover:text-ink"
             >
               <span className="tnum">{service.aggregates.length}</span>{" "}
-              {plural(service.aggregates.length, "aggregate")}
+              {plural(service.aggregates.length, hasModelGroups ? "group" : "aggregate")}
             </a>
           ) : null}
           {showDomain ? (
@@ -306,13 +337,39 @@ export function ServicePage() {
                 />
               </section>
             ) : null}
+            {/* Where it runs, read from the deployer's snapshot. Beside the
+                commands because it answers the next question after "how do
+                I build it": which commit stands where. Absent entirely when
+                no snapshot places it - a heading over an empty list would
+                claim the service runs nowhere, and nobody made that claim. */}
+            {deployments.length > 0 ? (
+              <section
+                id={SERVICE_ANCHOR.deployments}
+                className="mt-section max-w-table"
+              >
+                <SectionTitle anchor={SERVICE_ANCHOR.deployments}>
+                  Where it runs
+                </SectionTitle>
+                <DeploymentRows deployments={deployments} />
+                {/* The same rows as a picture: the service's instances with
+                    the environment, cluster and namespace drawn as the
+                    frames they are. Under the rows, because the rows carry
+                    the commit and the images and the picture carries where. */}
+                <div className="mt-3">
+                  <C4View
+                    viewId={serviceDeployViewId(service)}
+                    height={220}
+                  />
+                </div>
+              </section>
+            ) : null}
             {showDomain ? (
               <section
                 id={SERVICE_ANCHOR.aggregates}
                 className="mt-section max-w-table"
               >
                 <SectionTitle anchor={SERVICE_ANCHOR.aggregates}>
-                  Aggregates
+                  {hasModelGroups ? "Aggregates and model groups" : "Aggregates"}
                 </SectionTitle>
                 {/* icon, slug, name, event count, actions - one column each,
                   so the counts stack up instead of drifting with the name. */}
@@ -336,7 +393,7 @@ export function ServicePage() {
                         >
                           {aggregate.slug}
                         </Link>
-                        <span className="meta">{aggregate.name}</span>
+                        <span className="meta">{aggregate.name}{aggregate.kind === "model-group" ? " · model group" : ""}</span>
                         <Link
                           to={`${to}#bb-events`}
                           className="mono rounded-control hover:underline"

package/src/pages/Settings.tsx

@@ -48,17 +48,26 @@ import {
 import type { Discovery, ProjectDraft, ProjectPlan, RunEvent } from "../lib/local-api";
 import { useQuery, useQueryClient } from "@tanstack/react-query";
 import { localKeys, localStatusQuery } from "../lib/queries";
-import { sourceHref, treeHref } from "../lib/source-link";
+import { pluginByName, pluginIcon } from "../lib/plugins";
+import { PluginIcon } from "../components/PluginIcon";
+import { bare, sourceHref, treeHref } from "../lib/source-link";
 import { paths } from "../routes";
 import { CapabilityEmpty, Empty, SectionTitle } from "../components/PageHeader";
 import { Modal } from "../components/Overlay";
 import { MachineDocs } from "../components/MachineDocs";
 import { DeliverySettings } from "./settings/DeliverySettings";
+import { RecordingSettings } from "./settings/RecordingSettings";
+import { RulesSettings } from "./settings/RulesSettings";
 import { PreferencesSettings } from "./settings/PreferencesSettings";
 import { AboutSettings } from "./settings/AboutSettings";
 import { IntegrationsSettings } from "./settings/IntegrationsSettings";
+import { DjangoAggregateChoices } from "./settings/DjangoAggregateChoices";
+import { djangoAggregateCandidates, djangoAggregateMessage } from "../lib/django-aggregates";
 import { CatEmptyState, CatIllustration } from "../components/CatIllustration";
 import { CommitLink } from "../components/CommitLink";
+import { groupDiagnostics, warningDiagnostic } from "../lib/warnings";
+import type { WarningDiagnostic, WarningSeverity } from "../lib/warnings";
+import { AnimatePresence, m, rise } from "../lib/motion";
 
 type Health = "healthy" | "changed" | "failed" | "unchecked";
 type ProjectSource = ProjectDraft["source"];
@@ -261,44 +270,89 @@ function PipelineSteps({ steps }: { steps: SetupRunStep[] }) {
   if (steps.length === 0) {
     return <p className="mono text-muted">No result recorded for these steps.</p>;
   }
+  const warnings = steps.flatMap((step) => step.warnings.map((message) => ({ plugin: step.plugin, message })));
+  const diagnostics = steps.flatMap((step) => step.diagnostics.length
+    ? step.diagnostics
+    : step.warnings.map((message) => warningDiagnostic({ plugin: step.plugin, message })));
   return (
-    <div className="divide-y divide-line rounded-control border border-line">
-      {steps.map((step) => (
-        <div key={step.ordinal} className="px-3 py-2">
-          <div className="grid gap-2 sm:grid-cols-[5rem_minmax(7rem,1fr)_auto_auto] sm:items-center">
-            <span className="mono text-muted">{step.phase}</span>
-            <span className="mono truncate text-ink" title={step.plugin}>{step.plugin}</span>
-            <span className="mono text-muted">{step.fileCount} {plural(step.fileCount, "file")}</span>
-            <div className="flex items-center justify-between gap-2 sm:justify-end">
-              <span className="mono text-muted">{duration(step.durationMs)}</span>
-              <StepStatus status={step.status} />
+    <div className="space-y-2">
+      <div className="divide-y divide-line rounded-control border border-line">
+        {steps.map((step) => (
+          <div key={step.ordinal} className="px-3 py-2">
+            <div className="grid gap-2 sm:grid-cols-[5rem_minmax(7rem,1fr)_auto_auto] sm:items-center">
+              <span className="mono text-muted">{step.phase}</span>
+              <span className="mono truncate text-ink" title={step.plugin}>{step.plugin}</span>
+              <span className="mono text-muted">{step.fileCount} {plural(step.fileCount, "file")}</span>
+              <div className="flex items-center justify-between gap-2 sm:justify-end">
+                <span className="mono text-muted">{duration(step.durationMs)}</span>
+                <StepStatus status={step.status} />
+              </div>
             </div>
           </div>
-          <StepWarnings warnings={step.warnings} />
-        </div>
-      ))}
+        ))}
+      </div>
+      {warnings.length ? <details open={warnings.length <= 5}>
+        <summary className="mono cursor-pointer text-muted">{warnings.length} {plural(warnings.length, "warning")}</summary>
+        <div className="mt-2"><WarningPanel diagnostics={diagnostics} compact /></div>
+      </details> : null}
     </div>
   );
 }
 
-// What a plugin could not read, in its own words. For a tree the extractor
-// only half understood this is the list of what to fix, so it is shown where
-// the step is rather than left on the terminal it scrolled off.
-function StepWarnings({ warnings }: { warnings: string[] }) {
-  if (warnings.length === 0) return null;
+function WarningPanel({ diagnostics, compact = false }: { diagnostics: WarningDiagnostic[]; compact?: boolean }) {
+  const groups = groupDiagnostics(diagnostics);
+  const plugins = [...new Set(groups.map((group) => group.plugin))].sort();
+  const rules = [...new Set(groups.map((group) => group.rule))].sort();
+  const [plugin, setPlugin] = useState("all");
+  const [rule, setRule] = useState("all");
+  const [severity, setSeverity] = useState<WarningSeverity | "all">("all");
+  const [visibility, setVisibility] = useState<"active" | "suppressed" | "all">("active");
+  const shown = groups.filter((group) =>
+    (plugin === "all" || group.plugin === plugin)
+    && (rule === "all" || group.rule === rule)
+    && (severity === "all" || group.severity === severity)
+    && (visibility === "all" || (visibility === "suppressed") === group.suppressed),
+  );
+  const activeCount = groups.filter((group) => !group.suppressed).reduce((sum, group) => sum + group.count, 0);
+  const suppressedCount = diagnostics.length - activeCount;
+
   return (
-    <details className="mt-2" open={warnings.length <= 5}>
-      <summary className="mono cursor-pointer text-muted">
-        {warnings.length} {plural(warnings.length, "warning")}
-      </summary>
-      <ul className="mono mt-1 space-y-1 text-muted">
-        {warnings.map((warning, index) => (
-          <li key={`${index}:${warning}`} className="break-words border-l-2 border-line pl-2">
-            {warning}
-          </li>
-        ))}
-      </ul>
-    </details>
+    <div className="space-y-2">
+      <div className="flex flex-wrap items-center gap-2">
+        <span className="mono text-muted">{activeCount} active · {groups.length} {plural(groups.length, "rule")}</span>
+        {suppressedCount ? <span className="chip status-verified">{suppressedCount} suppressed</span> : null}
+        <div className="flex flex-wrap gap-2 sm:ml-auto">
+          {plugins.length > 1 ? <select aria-label="Filter warnings by plugin" className={`${FIELD} w-auto py-1`} value={plugin} onChange={(event) => setPlugin(event.target.value)}><option value="all">all plugins</option>{plugins.map((name) => <option key={name} value={name}>{name}</option>)}</select> : null}
+          {rules.length > 1 ? <select aria-label="Filter warnings by rule" className={`${FIELD} w-auto py-1`} value={rule} onChange={(event) => setRule(event.target.value)}><option value="all">all rules</option>{rules.map((name) => <option key={name} value={name}>{name}</option>)}</select> : null}
+          <select aria-label="Filter warnings by severity" className={`${FIELD} w-auto py-1`} value={severity} onChange={(event) => setSeverity(event.target.value as WarningSeverity | "all")}><option value="all">all severities</option><option value="error">error</option><option value="warning">warning</option><option value="info">info</option></select>
+          <select aria-label="Filter active or suppressed warnings" className={`${FIELD} w-auto py-1`} value={visibility} onChange={(event) => setVisibility(event.target.value as "active" | "suppressed" | "all")}><option value="active">active</option><option value="suppressed">suppressed</option><option value="all">all</option></select>
+        </div>
+      </div>
+      {shown.length ? <div className="space-y-2">{shown.map((group) => {
+        const color = group.severity === "error" ? "text-unresolved" : group.severity === "warning" ? "text-declared" : "text-muted";
+        const candidates = group.messages.filter((warning) => warning.aggregateCandidates || djangoAggregateCandidates(warning.message));
+        const examples = group.messages.filter((warning) => !warning.aggregateCandidates && !djangoAggregateCandidates(warning.message)).slice(0, compact ? 3 : 12);
+        return <details key={`${group.plugin}:${group.rule}:${group.suppressed}`} className={`rounded-control border px-3 py-2 ${group.suppressed ? "border-line opacity-75" : group.severity === "error" ? "border-unresolved" : "border-line"}`} open={!compact && shown.length <= 4}>
+          <summary className="cursor-pointer list-none">
+            <span className="flex flex-wrap items-center gap-2">
+              <CircleAlert size={15} className={`shrink-0 ${color}`} />
+              <span className="mono text-ink">{group.plugin}</span>
+              <span className={`chip ${group.severity === "error" ? "status-unresolved" : group.severity === "warning" ? "status-declared" : ""}`}>{group.severity}</span>
+              <span className="mono text-muted">{group.rule}</span>
+              <span className="chip ml-auto">×{group.count}</span>
+            </span>
+            <span className="mt-1 block text-muted"><span className="font-medium text-ink">Next:</span> {group.action}</span>
+            {group.suppressionReason ? <span className="mt-1 block text-muted"><span className="font-medium text-ink">Suppressed:</span> {group.suppressionReason}</span> : null}
+          </summary>
+          <ul className="mono mt-2 space-y-1 text-muted">
+            {examples.map((warning, index) => <li key={`${index}:${warning.message}`} className="break-words border-l-2 border-line pl-2">{djangoAggregateMessage(warning.message)}</li>)}
+          </ul>
+          {candidates.length ? <DjangoAggregateChoices warnings={candidates} /> : null}
+          {group.count > examples.length + candidates.length ? <p className="mono mt-2 text-faint">{group.count - examples.length - candidates.length} more occurrences</p> : null}
+        </details>;
+      })}</div> : <p className="rounded-control border border-line px-3 py-2 text-muted">No warnings match these filters.</p>}
+      {!compact && groups.some((group) => !group.suppressed) ? <p className="text-faint">Suppress a reviewed limitation with a typed CEL entry in <span className="mono">portolan.json → warningPolicies</span>. The reason is required and remains visible here after regeneration.</p> : null}
+    </div>
   );
 }
 
@@ -307,11 +361,22 @@ function ProjectCard({ project, onRemove }: { project: SetupProject; onRemove?:
   const declared = setupInfo.steps.filter((step) => step.projectId === project.id);
   const runSteps = setupInfo.run?.steps.filter((step) => step.projectId === project.id) ?? [];
   const pluginNames = [...new Set(declared.map((step) => step.plugin))];
+  // A project rooted at the repository itself owns every source in it.
+  const rootedAtRepository = project.root === "." || project.root === "";
   const sources = catalogSources.filter(
-    (source) => source.path === project.root || source.path.startsWith(`${project.root}/`),
+    (source) => rootedAtRepository || source.path === project.root || source.path.startsWith(`${project.root}/`),
   );
   const outputs = [...new Set(runSteps.flatMap((step) => step.files))];
+  // A vendored project's provenance is its pin: the upstream commit the copy
+  // was fetched at, which is also what its source links open. The history of
+  // THIS checkout says when the copy landed here, which is a different fact.
+  const pin = project.repository
+    ? catalog.repos?.find((held) => bare(held.repo) === bare(project.repository!))
+    : undefined;
   const commits = [...new Set(sources.map((source) => source.commit).filter(Boolean))];
+  // "uncommitted" is what the history says of a file it does not hold yet;
+  // it is not a commit, and a link built from it would open nothing.
+  const committed = commits.filter((commit) => commit !== "uncommitted");
   const href = projectHref(project);
   const sourceLink = forge(project);
   const health = healthFor(runSteps, declared.length, setupInfo);
@@ -342,7 +407,7 @@ function ProjectCard({ project, onRemove }: { project: SetupProject; onRemove?:
         <dt>scope</dt><dd className="truncate text-ink">{project.components?.length ? `${project.group ?? project.context} · ${project.components.length} components` : [project.group ?? project.context, project.component ?? project.service].filter(Boolean).join(" · ") || "estate"}</dd>
         <dt>pipeline</dt><dd className="text-ink">{declared.length} {plural(declared.length, "step")}</dd>
         <dt>fragments</dt><dd className="text-ink">{sources.length}</dd>
-        <dt>commit</dt><dd className="truncate text-ink" title={commits.join(", ")}>{commits.length === 0 ? "not stamped" : commits.length === 1 ? <CommitLink commit={commits[0]!} repository={project.repository} length={12} /> : `${commits.length} source commits`}</dd>
+        <dt>commit</dt><dd className="truncate text-ink" title={pin ? pin.commit : commits.join(", ")}>{pin ? <CommitLink commit={pin.commit} repository={project.repository} length={12} /> : committed.length === 1 ? <CommitLink commit={committed[0]!} repository={project.repository} length={12} /> : committed.length > 1 ? `${committed.length} source commits` : commits.length > 0 ? "uncommitted" : "not stamped"}</dd>
       </dl>
 
       <div className="mt-4 flex flex-wrap gap-1.5" aria-label="Active plugins">
@@ -457,10 +522,15 @@ function PluginsList() {
             const runSteps = setupInfo.run?.steps.filter((step) => step.plugin === plugin.name) ?? [];
             const health = plugin.stepCount === 0 ? "unchecked" : healthFor(runSteps, declared.length, setupInfo);
             const outputs = [...new Set(runSteps.flatMap((step) => step.files))];
+            // What the plugin says of itself, when it is one the package ships.
+            // A plugin the manifest declares by its own `process` is not on the
+            // index, and the row says nothing rather than something made up.
+            const shipped = pluginByName(plugin.name);
             return (
               <details key={plugin.name} id={`plugin-${plugin.name}`} className="group scroll-mt-4 border-t border-line">
                 <summary className="flex cursor-pointer list-none items-center gap-2.5 px-3 py-1.5 hover:bg-surface/60">
                   {health === "healthy" ? <HealthDot health={health} /> : null}
+                  <PluginIcon icon={pluginIcon(plugin.name, shipped?.category)} className="text-muted" />
                   <span className="mono truncate text-ink" title={plugin.name}>{plugin.name}</span>
                   <Runtime plugin={plugin} icon />
                   {health === "healthy" ? null : <HealthBadge health={health} />}
@@ -477,6 +547,7 @@ function PluginsList() {
                   <div className="grid gap-5 lg:grid-cols-[minmax(0,1.4fr)_minmax(14rem,1fr)]">
                     <div><div className="label mb-2">last run</div><PipelineSteps steps={runSteps} /></div>
                     <div className="space-y-4">
+                      {shipped ? <div><div className="label mb-2">what it reads</div><p className="text-muted">{shipped.summary}</p><Link to={paths.plugin(plugin.name)} className="mono mt-1 inline-block text-accent hover:underline">options and source →</Link></div> : null}
                       <div><div className="label mb-2">runtime</div><p className="mono"><Runtime plugin={plugin} /></p></div>
                       <div><div className="label mb-2">used by</div>{plugin.projectIds.length > 0 ? <div className="flex flex-wrap gap-1.5">{plugin.projectIds.map((id) => <Link key={id} to={`${paths.settingsProjects()}#project-${id}`} className="chip border-line-strong hover:border-accent hover:text-accent">{projectNames.get(id) ?? id}</Link>)}</div> : <p className="mono text-muted">{plugin.stepCount > 0 ? "Estate-wide catalog" : "No pipeline step uses this plugin."}</p>}</div>
                       {outputs.length > 0 ? <div><div className="label mb-2">outputs</div><ul className="mono space-y-1 text-muted">{outputs.map((output) => <li key={output} className="truncate"><FileLink path={output} /></li>)}</ul></div> : null}
@@ -581,6 +652,8 @@ const CAPABILITIES: Record<string, { title: string; summary: string }> = {
   "rust-domain": { title: "Rust domain model", summary: "Aggregates, entities, value objects and domain events." },
   "java-domain": { title: "Java domain model", summary: "Aggregates, entities, value objects and domain events." },
   "django-domain": { title: "Django data model", summary: "Models and their relationships." },
+  "laravel-domain": { title: "Laravel data model", summary: "Eloquent models, events and listeners, routes and controllers." },
+  "php-ddd": { title: "PHP DDD model", summary: "Bounded contexts laid out by module and hexagonal layer: aggregates, value objects, domain events, commands, queries, subscribers, Doctrine mappings." },
   openapi: { title: "HTTP API contract", summary: "Operations and messages declared by OpenAPI or Swagger." },
   wsdl: { title: "SOAP contract", summary: "Services, operations and messages declared by WSDL." },
   "http-clients": { title: "Outbound integrations", summary: "HTTP and SOAP calls, provider branches and code flows." },
@@ -712,7 +785,7 @@ function Wizard({ open, initialSource, onClose, onAdded, onRunStarted }: { open:
   function configure(found: Discovery, commit: string, selectedSourcePath: string, projectId?: string) {
     setDiscovery(found);
     const plugins = found.detections.filter((item) => item.selected).map((item) => item.plugin);
-    const domainModel = plugins.some((plugin) => ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain"].includes(plugin));
+    const domainModel = plugins.some((plugin) => ["go-domain", "ts-domain", "rust-domain", "java-domain", "django-domain", "laravel-domain", "php-ddd"].includes(plugin));
     setDraft({ source, root: found.root, repository, ref, commit, sourcePath: selectedSourcePath, ...found.defaults, ...(projectId ? { id: projectId } : {}), contextName: found.defaults.group ? found.defaults.group.replace(/(^|-)([a-z])/g, (_, gap, letter) => `${gap ? " " : ""}${letter.toUpperCase()}`) : "", contextSummary: "", classification: "supporting", groupKind: domainModel ? "bounded-context" : "system", componentKind: domainModel ? "service" : "application", replaceStarter: Boolean(starter), plugins });
     setStage("configure");
   }
@@ -829,11 +902,15 @@ function Wizard({ open, initialSource, onClose, onAdded, onRunStarted }: { open:
   const trialRunning = stage === "trial" && !finished;
   const confirmedDeployables = discovery?.deployables.filter((candidate) => candidate.confidence === "high") ?? [];
   const splitsDeployables = confirmedDeployables.length > 1 && draft?.component === discovery?.defaults.component;
+  const trialDiagnostics = trial?.diagnostics ?? [];
+  const trialActiveWarnings = trial
+    ? groupDiagnostics(trialDiagnostics).filter((group) => !group.suppressed).reduce((sum, group) => sum + group.count, 0)
+    : 0;
   const quality = trial && draft ? [
     { label: "Stable project identity", done: Boolean(draft.id.trim() && draft.name.trim()) },
     { label: "Architecture placement", done: Boolean(draft.group.trim() && (splitsDeployables || draft.component.trim())) },
     { label: "Catalog facts extracted", done: trial.facts.some((fact) => fact.count > 0) },
-    { label: "Extraction without warnings", done: trial.warnings.length === 0 },
+    { label: "Extraction without active warnings", done: trialActiveWarnings === 0 },
   ] : [];
   const totalSteps = pipeline?.stepCount ?? plan?.steps.length ?? 0;
   const percent = totalSteps ? Math.round((completedSteps.length / totalSteps) * 100) : 0;
@@ -877,7 +954,7 @@ function Wizard({ open, initialSource, onClose, onAdded, onRunStarted }: { open:
               {discovery.detections.length ? <div className="grid gap-2">{discovery.detections.map((item) => {
                 const checked = draft.plugins.includes(item.plugin);
                 const capability = CAPABILITIES[item.plugin] ?? { title: item.plugin, summary: "Catalog facts extracted from project files." };
-                return <label key={item.plugin} className={`flex cursor-pointer items-start gap-3 rounded-control border px-3 py-3 transition-colors ${checked ? "border-accent bg-surface" : "border-line hover:bg-surface"}`}><input className="mt-1" type="checkbox" checked={checked} onChange={() => setDraft({ ...draft, plugins: checked ? draft.plugins.filter((name) => name !== item.plugin) : [...draft.plugins, item.plugin] })} /><span className="min-w-0 flex-1"><span className="flex flex-wrap items-center gap-2"><span className="font-medium text-ink">{capability.title}</span><span className={`chip ${item.confidence === "high" ? "status-verified" : "status-declared"}`}>{item.confidence} confidence</span>{item.candidates.length > 1 ? <span className="chip status-declared">{item.candidates.length} candidates</span> : null}</span><span className="mt-0.5 block text-muted">{capability.summary}</span><span className="mono mt-1 block truncate text-faint" title={item.evidence}>evidence · {item.evidence}</span><span className="mono mt-0.5 block text-faint">extractor · {item.plugin}</span></span></label>;
+                return <label key={item.plugin} className={`flex cursor-pointer items-start gap-3 rounded-control border px-3 py-3 transition-colors ${checked ? "border-accent bg-surface" : "border-line hover:bg-surface"}`}><input aria-label={`Toggle ${capability.title}`} className="mt-1" type="checkbox" checked={checked} onChange={() => setDraft({ ...draft, plugins: checked ? draft.plugins.filter((name) => name !== item.plugin) : [...draft.plugins, item.plugin] })} /><span className="min-w-0 flex-1"><span className="flex flex-wrap items-center gap-2"><span className="font-medium text-ink">{capability.title}</span><span className={`chip ${item.confidence === "high" ? "status-verified" : "status-declared"}`}>{item.confidence} confidence</span>{item.candidates.length > 1 ? <span className="chip status-declared">{item.candidates.length} candidates</span> : null}</span><span className="mt-0.5 block text-muted">{capability.summary}</span><span className="mono mt-1 block truncate text-faint" title={item.evidence}>evidence · {item.evidence}</span>{item.preview?.length ? <span className="mt-2 grid gap-1.5">{item.preview.slice(0, 3).map((preview) => <span key={preview.file} className="block rounded-control border border-line bg-canvas px-2 py-1.5"><span className="mono block truncate text-faint" title={preview.file}>{preview.file}</span><span className="mt-1 flex flex-wrap gap-x-3 gap-y-1 text-muted">{Object.entries(preview.fields).map(([field, value]) => <span key={field}><span className="text-faint">{field}</span> · <span className="text-ink">{value}</span></span>)}</span></span>)}{item.preview.length > 3 ? <span className="text-faint">+ {item.preview.length - 3} more recognized records</span> : null}</span> : null}<span className="mono mt-0.5 block text-faint">extractor · {item.plugin}</span></span></label>;
               })}</div> : <Empty>no supported project signals found</Empty>}
             </div>
           </div>
@@ -895,7 +972,7 @@ function Wizard({ open, initialSource, onClose, onAdded, onRunStarted }: { open:
             {trial ? <section><div className="label mb-2">what Portolan found</div>{trial.facts.length ? <div className="grid grid-cols-2 gap-2 sm:grid-cols-3">{trial.facts.map((fact) => <div key={fact.key} className="rounded-control border border-line bg-canvas px-3 py-2"><div className="tnum text-lg font-semibold text-ink">{fact.count}</div><div className="text-muted">{fact.label}</div></div>)}</div> : <div className="rounded-control border border-line bg-surface px-3 py-3 text-muted">Only component metadata was found. You can add APIs, domain models and stores later without re-adding the project.</div>}</section> : null}
             {trial ? <section><div className="label mb-2">catalog readiness</div><div className="grid gap-2 sm:grid-cols-2">{quality.map((item) => <div key={item.label} className="flex items-center gap-2 rounded-control border border-line px-3 py-2"><span className={`flex size-5 items-center justify-center rounded-full ${item.done ? "bg-verified text-canvas" : "bg-surface text-declared"}`}>{item.done ? <Check size={12} aria-hidden /> : <CircleAlert size={12} aria-hidden />}</span><span className={item.done ? "text-ink" : "text-muted"}>{item.label}</span></div>)}</div></section> : null}
             <section><div className="label mb-2">extractor results</div><div className="divide-y divide-line rounded-control border border-line">{(trial?.steps ?? completedSteps).map((step) => <div key={`${step.plugin}:${"ordinal" in step ? step.ordinal : "trial"}`} className="grid gap-1 px-3 py-2 sm:grid-cols-[1fr_auto_auto]"><span><span className="font-medium text-ink">{CAPABILITIES[step.plugin]?.title ?? step.plugin}</span><span className="mono ml-2 text-faint">{step.plugin}</span>{step.message ? <span className="mt-1 block text-unresolved">{step.message}</span> : null}</span><span className="mono text-muted">{step.fileCount} {plural(step.fileCount, "file")}</span><span className={`chip ${step.status === "failed" ? "status-unresolved" : "status-verified"}`}>{step.status === "failed" ? "failed" : "read"}</span></div>)}</div></section>
-            {trial?.warnings.length ? <section><div className="label mb-2">warnings · {trial.warnings.length}</div><div className="space-y-2">{trial.warnings.map((warning, index) => <div key={`${warning.plugin}:${index}`} className="flex gap-2 rounded-control border border-declared px-3 py-2 text-muted"><CircleAlert size={15} className="mt-0.5 shrink-0 text-declared" /><span><span className="mono text-ink">{warning.plugin}</span> · {warning.message}</span></div>)}</div></section> : null}
+            {trialDiagnostics.length ? <section><div className="label mb-2">diagnostics · {trialDiagnostics.length}</div><WarningPanel diagnostics={trialDiagnostics} /></section> : null}
             {finished?.status === "failed" && logs.length ? <details><summary className="cursor-pointer text-muted">Generator log · {logs.length} lines</summary><pre className="mono mt-2 max-h-48 overflow-auto whitespace-pre-wrap rounded-control bg-surface p-3 text-muted">{logs.map((event) => event.message).join("\n")}</pre></details> : null}
             {trial ? <div><div className="label mb-2">changes after apply</div><dl className="mono grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-2 text-muted"><dt>project</dt><dd className="text-ink">{plan.project.id}</dd>{plan.fetch ? <><dt>pin</dt><dd className="truncate text-ink"><CommitLink commit={plan.fetch.commit} repository={plan.fetch.repo} length={12} /></dd></> : null}<dt>source</dt><dd className="truncate text-ink">{plan.source}</dd><dt>pipeline</dt><dd className="text-ink">{plan.steps.length + (plan.fetch ? 1 : 0)} {plural(plan.steps.length + (plan.fetch ? 1 : 0), "extract step")}</dd><dt>fragments</dt><dd className="text-ink">{trial.generatedFiles} generated</dd></dl></div> : null}
           </div>
@@ -955,11 +1032,23 @@ const SETTINGS_LINKS = [
   ["Projects", paths.settingsProjects()],
   ["Pipeline", paths.settingsPipeline()],
   ["Delivery", paths.settingsDelivery()],
+  ["Recordings", paths.settingsRecordings()],
+  ["Rules", paths.settingsRules()],
   ["Integrations", paths.settingsIntegrations()],
   ["Preferences", paths.settingsPreferences()],
   ["About", paths.settingsAbout()],
 ] as const;
 
+function RecordingsRoute({ local }: { local: boolean }) {
+  const setupInfo = useSetup();
+  return (
+    <section>
+      <SectionTitle right={local ? "reviewed before writing" : "local mode required"}>Recordings</SectionTitle>
+      <RecordingSettings local={local} projects={setupInfo.projects} />
+    </section>
+  );
+}
+
 function SettingsNav() {
   return (
     <nav className="mt-5 border-b border-line" aria-label="Settings sections">
@@ -1094,7 +1183,7 @@ function PipelineSettings() {
         ) : (
           <>
             <PluginsList />
-            <p className="mono mt-2 text-muted">WASM runs without network or environment access, and a generator without a filesystem. A host process runs with the permissions of the build; a plugin in the host is Portolan's own code doing what needs a socket, such as fetching another repository.</p>
+            <p className="mono mt-2 text-muted">WASM runs without network or environment access, and a generator without a filesystem. A host process runs with the permissions of the build; a plugin in the host is Portolan's own code doing what needs a socket, such as fetching another repository. Every plugin the package ships, with what it reads and the options it takes, is on the <Link to={paths.plugins()} className="text-accent hover:underline">plugin reference</Link>.</p>
           </>
         )}
       </section>
@@ -1136,6 +1225,8 @@ function SettingsContent({ local, onAdd, onRemove, onGenerate }: { local: boolea
             <Route path="projects" element={<ProjectsSettings local={local} onAdd={onAdd} onRemove={onRemove} />} />
             <Route path="pipeline" element={<PipelineSettings />} />
             <Route path="delivery" element={<section><SectionTitle right={local ? "preview before writing" : "local mode required"}>Delivery presets</SectionTitle><DeliverySettings local={local} /></section>} />
+            <Route path="recordings" element={<RecordingsRoute local={local} />} />
+            <Route path="rules" element={<RulesSettings local={local} />} />
             <Route path="integrations" element={<IntegrationsSettings />} />
             <Route path="preferences" element={<PreferencesSettings />} />
             <Route path="about" element={<AboutSettings />} />
@@ -1148,6 +1239,88 @@ function SettingsContent({ local, onAdd, onRemove, onGenerate }: { local: boolea
   );
 }
 
+function RemoveProjectDialog({
+  project,
+  busy,
+  onClose,
+  onConfirm,
+}: {
+  project: SetupProject | null;
+  busy: boolean;
+  onClose: () => void;
+  onConfirm: () => void;
+}) {
+  const name = project?.name ?? "project";
+  return (
+    <Modal
+      open={project !== null}
+      onClose={busy ? () => {} : onClose}
+      label={`Remove ${name}`}
+      width="min(520px,92vw)"
+    >
+      <div className="flex items-center gap-3 border-b border-line px-5 py-4">
+        <m.span
+          animate={busy ? { rotate: 360 } : { rotate: 0 }}
+          transition={busy ? { duration: 0.9, ease: "linear", repeat: Infinity } : undefined}
+          className="flex size-8 shrink-0 items-center justify-center rounded-full bg-unresolved/10 text-unresolved"
+        >
+          {busy ? <LoaderCircle size={17} aria-hidden /> : <Trash2 size={16} aria-hidden />}
+        </m.span>
+        <div className="min-w-0">
+          <div className="font-semibold text-ink">{busy ? `Removing ${name}` : `Remove ${name}?`}</div>
+          <div className="mono mt-0.5 truncate text-faint">{project?.id}</div>
+        </div>
+      </div>
+
+      <div className="min-h-40 p-5">
+        <AnimatePresence mode="wait" initial={false}>
+          {busy ? (
+            <m.div key="removing" {...rise} aria-live="polite">
+              <p className="font-medium text-ink">Updating project configuration…</p>
+              <p className="mt-2 text-muted">
+                Portolan is removing the project and its extraction steps. The source tree remains untouched.
+              </p>
+              <div
+                role="progressbar"
+                aria-label={`Removing ${name}`}
+                className="mt-5 h-1.5 overflow-hidden rounded-full bg-surface"
+              >
+                <m.div
+                  className="h-full w-2/5 rounded-full bg-unresolved"
+                  initial={{ x: "-100%" }}
+                  animate={{ x: ["-100%", "250%"] }}
+                  transition={{ duration: 1.1, ease: "easeInOut", repeat: Infinity }}
+                />
+              </div>
+            </m.div>
+          ) : (
+            <m.div key="confirm" {...rise}>
+              <p className="text-muted">
+                This removes the project, its extraction steps and its dedicated catalog configuration from <span className="mono text-ink">portolan.json</span>. Your source code stays untouched.
+              </p>
+              <p className="mt-3 text-muted">
+                You can undo immediately. Generated documentation changes remain pending until you preview and apply them.
+              </p>
+            </m.div>
+          )}
+        </AnimatePresence>
+      </div>
+
+      <div className="flex justify-end gap-2 border-t border-line px-5 py-4">
+        <button type="button" className="tbtn" onClick={onClose} disabled={busy}>Cancel</button>
+        <button type="button" className="product-primary product-danger min-w-36" onClick={onConfirm} disabled={busy}>
+          <AnimatePresence mode="wait" initial={false}>
+            <m.span key={busy ? "busy" : "ready"} {...rise} className="flex items-center justify-center gap-2">
+              {busy ? <LoaderCircle size={15} aria-hidden /> : <Trash2 size={15} aria-hidden />}
+              {busy ? "Removing…" : "Remove project"}
+            </m.span>
+          </AnimatePresence>
+        </button>
+      </div>
+    </Modal>
+  );
+}
+
 export function Settings() {
   useDocumentTitle("Settings");
   const queryClient = useQueryClient();
@@ -1210,11 +1383,12 @@ export function Settings() {
     <SetupContext.Provider value={setup}>
       <SettingsContent local={local} onAdd={setWizardSource} onRemove={setRemoveTarget} onGenerate={() => void generate()} />
       <Wizard open={wizardSource !== null} initialSource={wizardSource ?? "local"} onClose={() => setWizardSource(null)} onAdded={setSetup} onRunStarted={(id) => { setRunId(id); setRunOpen(true); }} />
-      <Modal open={removeTarget !== null} onClose={removeBusy ? () => {} : () => setRemoveTarget(null)} label={`Remove ${removeTarget?.name ?? "project"}`} width="min(520px,92vw)">
-        <div className="border-b border-line px-5 py-4"><div className="font-semibold text-ink">Remove {removeTarget?.name}?</div></div>
-        <div className="p-5"><p className="text-muted">This removes the project, its extraction steps and its dedicated catalog configuration from <span className="mono text-ink">portolan.json</span>. Your source code stays untouched.</p><p className="mt-3 text-muted">You can undo immediately. Generated documentation changes remain pending until you preview and apply them.</p></div>
-        <div className="flex justify-end gap-2 border-t border-line px-5 py-4"><button type="button" className="tbtn" onClick={() => setRemoveTarget(null)} disabled={removeBusy}>Cancel</button><button type="button" className="product-primary" onClick={() => void confirmRemove()} disabled={removeBusy}>{removeBusy ? <LoaderCircle size={15} className="animate-spin" /> : <Trash2 size={15} />} Remove project</button></div>
-      </Modal>
+      <RemoveProjectDialog
+        project={removeTarget}
+        busy={removeBusy}
+        onClose={() => setRemoveTarget(null)}
+        onConfirm={() => void confirmRemove()}
+      />
       <RunDialog runId={runId} open={runOpen} onClose={() => setRunOpen(false)} onFinished={refresh} onApply={(preview) => void generate(preview)} />
     </SetupContext.Provider>
   );

package/src/pages/settings/AboutSettings.tsx

@@ -1,4 +1,4 @@
-import { ArrowRight, BookOpen, CircleDot, GitBranch, ShieldCheck } from "lucide-react";
+import { ArrowRight, BookOpen, CircleDot, GitBranch, Puzzle, ShieldCheck } from "lucide-react";
 import type { Variants } from "motion/react";
 import { Link } from "react-router";
 
@@ -94,6 +94,13 @@ export function AboutSettings() {
         >
           <div className="label mb-2">resources</div>
           <div className="divide-y divide-line">
+            <Link
+              to={paths.plugins()}
+              className="flex items-center gap-2 py-2.5 text-muted transition-colors hover:text-ink"
+            >
+              <Puzzle size={15} aria-hidden className="shrink-0" />
+              Plugin reference
+            </Link>
             <a
               href={PRODUCT_README}
               target="_blank"