@shortlink-org/portolan 0.2.4 → 0.3.0

package/src/pages/Settings.tsx

@@ -48,7 +48,7 @@ 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 { bare, sourceHref, treeHref } from "../lib/source-link";
 import { paths } from "../routes";
 import { CapabilityEmpty, Empty, SectionTitle } from "../components/PageHeader";
 import { Modal } from "../components/Overlay";
@@ -57,8 +57,13 @@ import { DeliverySettings } from "./settings/DeliverySettings";
 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 +266,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 +357,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 +403,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">
@@ -829,11 +890,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 +942,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 +960,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>
@@ -1148,6 +1213,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 +1357,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/DjangoAggregateChoices.tsx

@@ -0,0 +1,79 @@
+import { useState } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { djangoAggregateCandidates, djangoAggregateMessage } from "../../lib/django-aggregates";
+import { djangoAggregateProposals, saveDjangoAggregates } from "../../lib/local-api";
+import { localKeys, localStatusQuery } from "../../lib/queries";
+import type { WarningDiagnostic } from "../../lib/warnings";
+import { useToastStore } from "../../app/toast";
+
+const CANDIDATE_KEY = ["local", "django-aggregates"];
+
+export function DjangoAggregateChoices({ warnings }: { warnings: WarningDiagnostic[] }) {
+  const status = useQuery(localStatusQuery());
+  const queryClient = useQueryClient();
+  const say = useToastStore((state) => state.say);
+  const proposals = useQuery({
+    queryKey: [...CANDIDATE_KEY, status.data?.setup.run?.finishedAt],
+    queryFn: djangoAggregateProposals,
+    enabled: status.isSuccess,
+    retry: false,
+  });
+  const [choices, setChoices] = useState<Record<string, string>>({});
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState("");
+  const [saved, setSaved] = useState(false);
+  const rows = warnings.flatMap((warning) => {
+    const candidates = warning.aggregateCandidates ?? djangoAggregateCandidates(warning.message);
+    if (!candidates) return [];
+    const matches = proposals.data?.proposals.filter((proposal) => proposal.plugin === warning.plugin && proposal.app === candidates.app
+      && djangoAggregateMessage(proposal.message).slice(0, 500) === djangoAggregateMessage(warning.message).slice(0, 500)) ?? [];
+    return [{ ...candidates, key: `${warning.plugin}:${warning.message}`, proposal: matches.length === 1 ? matches[0] : undefined }];
+  });
+  const selections = rows.flatMap((row) => row.proposal && choices[row.key] ? [{ id: row.proposal.id, model: choices[row.key]! }] : []);
+  const canSave = Boolean(proposals.data && !proposals.data.stale && !status.data?.activeRun && selections.length && !busy);
+
+  async function save() {
+    if (!canSave || !proposals.data) return;
+    setBusy(true); setError(""); setSaved(false);
+    try {
+      await saveDjangoAggregates(proposals.data.revision, selections);
+      setSaved(true);
+      // Refreshing the manifest hides the now-stale report and unmounts this
+      // picker; keep the next step visible outside that report.
+      say("Aggregate roots saved to portolan.json. Preview generated diff to update the catalog.");
+      await Promise.all([
+        queryClient.invalidateQueries({ queryKey: CANDIDATE_KEY }),
+        queryClient.invalidateQueries({ queryKey: localKeys.status }),
+      ]);
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : String(cause));
+    } finally { setBusy(false); }
+  }
+
+  return <div className="mt-3 space-y-3">
+    <p className="text-muted">Choose the model that owns each application’s aggregate. Other concrete models become its entities.</p>
+    {rows.map((row) => <div key={row.key} className="rounded-control border border-line p-3">
+      <label className="block font-medium text-ink">
+        Aggregate root for <span className="mono">{row.app}</span>
+        <select aria-label={`Aggregate root for ${row.app}`} className="mt-2 block w-full rounded-control border border-line bg-canvas px-3 py-2 text-ink" value={choices[row.key] ?? ""} onChange={(event) => { setChoices({ ...choices, [row.key]: event.target.value }); setSaved(false); }} disabled={busy}>
+          <option value="">Choose a model…</option>
+          {row.models.map((model) => <option key={model.name} value={model.name}>{model.name}</option>)}
+        </select>
+      </label>
+      <details className="mt-2 text-muted">
+        <summary className="cursor-pointer">{row.models.length} candidates · source locations</summary>
+        <ul className="mono mt-2 space-y-1">{row.models.map((model) => <li key={model.name} className="break-words">{model.name} · {model.path}:{model.line}</li>)}</ul>
+      </details>
+      {choices[row.key] ? <pre className="mono mt-2 overflow-auto rounded-control bg-canvas p-2 text-ink">{JSON.stringify({ aggregates: { [row.app]: choices[row.key] } }, null, 2)}</pre> : null}
+    </div>)}
+    {status.isSuccess ? <>
+      <button className="rounded-control border border-line bg-canvas px-3 py-2 font-medium text-accent hover:bg-surface disabled:cursor-not-allowed disabled:opacity-50" onClick={() => void save()} disabled={!canSave}>{busy ? "Saving…" : "Save selected roots"}</button>
+      <p className="text-muted">Saves to the matching extraction steps in portolan.json. Regenerate afterward to update the catalog and warnings.</p>
+      {proposals.data?.stale && !saved ? <p className="text-declared">Regenerate before saving: these candidates belong to an older manifest.</p> : null}
+      {proposals.isError ? <p role="alert" className="text-unresolved">Could not load the saved extraction report. Regenerate and reopen Settings.</p> : null}
+      {rows.some((row) => !row.proposal) && proposals.isSuccess ? <p className="text-muted">Candidates from a trial can be saved after applying the project and generating its catalog.</p> : null}
+    </> : <p className="text-muted">To save, open Portolan locally or copy the selected aggregates option into the matching extraction step in portolan.json.</p>}
+    {saved ? <p role="status" className="text-verified">Aggregate roots saved. Regenerate to apply the choices to the catalog.</p> : null}
+    {error ? <p role="alert" className="text-unresolved">{error}</p> : null}
+  </div>;
+}

package/src/selection/DetailPanel.tsx

@@ -1,3 +1,4 @@
+import { RelationEvidencePanel } from "../components/RelationEvidence";
 // The right rail. One panel, one selection, every page that draws a diagram.
 //
 // It renders by kind rather than by page, so an event opened from a flow reads
@@ -238,6 +239,10 @@ function ViewBody({
   return (
     <>
       {view.doc ? <p className="mt-2 text-muted">{view.doc}</p> : null}
+      <RelationEvidencePanel items={[
+        ...(view.source ? [{ kind: "contract" as const, rule: "sql-view-definition", source: view.source, symbol: view.name }] : []),
+        ...(view.persists?.evidence ?? []),
+      ]} renderSource={(source) => <SchemaEvidenceSource source={source} owner={store.owner} />} />
 
       <Label>Store</Label>
       <SelectLink id={store.id}>{store.id}</SelectLink>
@@ -344,6 +349,7 @@ function TableBody({
   return (
     <>
       {table.doc ? <p className="mt-2 text-muted">{table.doc}</p> : null}
+      <RelationEvidencePanel items={[...(table.evidence ?? []), ...(table.persists?.evidence ?? [])]} renderSource={(source) => <SchemaEvidenceSource source={source} owner={store.owner} />} />
 
       <Label>Store</Label>
       <SelectLink id={store.id}>{store.id}</SelectLink>
@@ -534,6 +540,11 @@ function ColumnBody({
   return (
     <>
       {column.doc ? <p className="mt-2 text-muted">{column.doc}</p> : null}
+      {(column.fk || column.from?.length || column.maps) ? <RelationEvidencePanel items={[
+        ...(table?.evidence ?? []),
+        ...(table?.persists?.evidence ?? []),
+        ...(view?.source ? [{ kind: "contract" as const, rule: "sql-view-definition", source: view.source, symbol: view.name }] : []),
+      ]} renderSource={(source) => <SchemaEvidenceSource source={source} owner={resolved.store.owner} />} /> : null}
 
       <Label>{view ? "View" : "Table"}</Label>
       {view ? (
@@ -1550,3 +1561,7 @@ export function WithDetail({
     </SavedGroup>
   );
 }
+
+function SchemaEvidenceSource({ source, owner }: { source: string; owner: string }) {
+  return <SourcePreviewLink location={sourceLocation(source, index.serviceById.get(owner), allRepos(catalog))} className="mono break-all text-muted hover:text-accent">{source}</SourcePreviewLink>;
+}

package/src/virtual-provenance.d.ts

@@ -0,0 +1,11 @@
+// The stamp of every catalog source, as the checkout's history says: served
+// by `scripts/provenance.mjs` at build time (portolan.0010). Keyed by the
+// path `src/data.ts` gives a source. A staged site imports its sources under
+// flattened names; `source` is then the path the file has in the workspace.
+declare module "virtual:portolan-provenance" {
+  const provenance: Record<
+    string,
+    { commit: string; generatedAt: string; source?: string }
+  >;
+  export default provenance;
+}

package/vite.config.ts

@@ -17,6 +17,10 @@ import { localApiPlugin } from "./scripts/local-api.mjs";
 // generator wrote them; the build copies the same files into dist.
 // @ts-expect-error plain JavaScript module intentionally has no browser types
 import { siteDocsPlugin } from "./scripts/site-docs.mjs";
+// When each catalog source last changed, read from git at build time and
+// served to the app as one virtual module (portolan.0010).
+// @ts-expect-error plain JavaScript module intentionally has no browser types
+import { provenancePlugin } from "./scripts/provenance.mjs";
 
 /** A git answer, or "" when there is nothing to answer with (no repo, no git). */
 function git(args: string): string {
@@ -160,6 +164,7 @@ export default defineConfig({
     // TypeScript below node_modules.
     localApiPlugin(workspace, publicSetupFrom),
     siteDocsPlugin(workspace),
+    provenancePlugin(workspace),
     react(),
     tailwindcss(),
     // The AsyncAPI reference brings a parser written for Node, and it calls

package/scripts/vendor-lock.mjs

@@ -1,58 +0,0 @@
-// The commit a vendored copy is of.
-//
-// `stampFor` dates a fragment from the last commit that touched the directory
-// it was read from, which is the right answer for code that lives here and the
-// wrong one for code that does not. A service fetched out of another
-// repository is stamped, without this, with the commit that VENDORED it: the
-// estate then reports the service as fresh because somebody re-ran the fetch,
-// and as unchanged when its own repository moved.
-//
-// The right answer is already on disk. `fetch-git` writes `git.lock.json`
-// beside each copy, naming the commit it fetched, and a copy re-fetched at the
-// same commit does not move it. Reading it here keeps the rule the host has
-// always kept - the host works out the stamp, never the plugin - while making
-// the subject of the stamp the code rather than the vendoring.
-
-import { readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-
-/** The file `fetch-git` writes beside every copy. Its name is that plugin's. */
-export const LOCK = "git.lock.json";
-
-/**
- * The commit `root` is a copy of, or null when it is not a copy of anything.
- *
- * Walks up from the directory the extractor was pointed at, because the lock
- * sits at the root of the repository's copy and the step reads a service some
- * way inside it: `vendor/repos/acme/shop/services/oms` is stamped by the lock
- * three levels above it. It stops at the repository root, so a run in a tree
- * with no vendored copies reads nothing and answers null.
- *
- * A lock naming other than exactly one repository is not one of these - the
- * fetcher writes one per directory - and is left to the fetcher to complain
- * about, which it does with the path and the count. Nothing here fails a run:
- * the caller has a git history to fall back on, and a stamp is not worth
- * refusing to describe an estate over.
- */
-export function vendoredCommit(root, read = readFileSync) {
-  for (let at = root; at && at !== "." && at !== "/"; at = dirname(at)) {
-    let raw;
-    try {
-      raw = read(join(at, LOCK), "utf8");
-    } catch {
-      continue; // No lock here; the copy's root may still be above.
-    }
-
-    try {
-      const lock = JSON.parse(raw);
-      const [only, ...rest] = lock.repos ?? [];
-      if (only?.commit && rest.length === 0) return only.commit;
-    } catch {
-      // Unreadable, which the fetcher reports against the copy itself.
-    }
-
-    return null;
-  }
-
-  return null;
-}

package/scripts/vendor-lock.test.mjs

@@ -1,69 +0,0 @@
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-import { tmpdir } from "node:os";
-import { afterEach, beforeEach, describe, expect, it } from "vitest";
-
-import { vendoredCommit } from "./vendor-lock.mjs";
-
-const COMMIT = "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0";
-
-describe("vendoredCommit", () => {
-  let root;
-
-  beforeEach(() => {
-    root = mkdtempSync(join(tmpdir(), "portolan-vendor-"));
-  });
-  afterEach(() => {
-    rmSync(root, { recursive: true, force: true });
-  });
-
-  const copy = (at, lock) => {
-    mkdirSync(join(root, at), { recursive: true });
-    writeFileSync(join(root, at, "git.lock.json"), JSON.stringify(lock));
-  };
-
-  // The case this exists for: the extractor is pointed at a service some way
-  // inside the copy, and the lock is at the copy's root.
-  it("reads the lock above the directory the extractor was given", () => {
-    copy("vendor/repos/acme/shop", { repos: [{ repo: "github.com/acme/shop", commit: COMMIT }] });
-    mkdirSync(join(root, "vendor/repos/acme/shop/services/oms"), { recursive: true });
-
-    expect(vendoredCommit(join(root, "vendor/repos/acme/shop/services/oms"))).toBe(COMMIT);
-  });
-
-  it("answers null for a directory that is nobody's copy", () => {
-    mkdirSync(join(root, "examples/shop/oms"), { recursive: true });
-
-    expect(vendoredCommit(join(root, "examples/shop/oms"))).toBeNull();
-  });
-
-  // The fetcher writes one repository per directory. Anything else is its
-  // problem to report, with the path and the count; a stamp is not worth
-  // failing a run over, so this stops rather than guessing which one won.
-  it("answers null for a lock naming more than one repository", () => {
-    copy("vendor/repos/acme/shop", {
-      repos: [
-        { repo: "github.com/acme/shop", commit: COMMIT },
-        { repo: "github.com/acme/pay", commit: "0000000" },
-      ],
-    });
-
-    expect(vendoredCommit(join(root, "vendor/repos/acme/shop"))).toBeNull();
-  });
-
-  it("answers null for a lock that cannot be read", () => {
-    mkdirSync(join(root, "vendor/repos/acme/shop"), { recursive: true });
-    writeFileSync(join(root, "vendor/repos/acme/shop/git.lock.json"), "{ not json");
-
-    expect(vendoredCommit(join(root, "vendor/repos/acme/shop"))).toBeNull();
-  });
-
-  // A copy nested inside another copy takes the innermost lock: it is the one
-  // that names the files the extractor is about to read.
-  it("takes the nearest lock", () => {
-    copy("vendor/repos/acme", { repos: [{ repo: "github.com/acme/outer", commit: "9999999" }] });
-    copy("vendor/repos/acme/shop", { repos: [{ repo: "github.com/acme/shop", commit: COMMIT }] });
-
-    expect(vendoredCommit(join(root, "vendor/repos/acme/shop"))).toBe(COMMIT);
-  });
-});