@shortlink-org/portolan 0.2.3 → 0.3.0

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
@@ -34,7 +35,7 @@ import { stepLabel } from "../flow/labels";
 import { KIND_LABEL } from "../lib/kinds";
 import { eventScope, resolveShape } from "../lib/shape";
 import { stepsInto } from "../lib/backlinks";
-import { treeHref } from "../lib/source-link";
+import { sourceLocation, treeHref } from "../lib/source-link";
 import { walkSteps } from "../catalog";
 import { methodCount } from "../lib/api";
 import {
@@ -49,6 +50,7 @@ import { upstreamOf } from "../er/lineage";
 import type { LineageMaps } from "../er/lineage";
 import { ctxStyle } from "../lib/context-color";
 import { Ident } from "../components/Ident";
+import { SourcePreviewLink } from "../components/SourcePreview";
 import { StatusChip } from "../components/primitives";
 import { StepDetailBody } from "../flow/StepDetail";
 import {
@@ -237,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>
@@ -343,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>
@@ -420,6 +427,50 @@ function TableBody({
         </>
       ) : null}
 
+      {(table.accesses ?? []).length > 0 ? (
+        <>
+          <Label>Reads / writes</Label>
+          {(table.accesses ?? []).map((access, accessIndex) => {
+            const location = access.source
+              ? sourceLocation(
+                  access.source,
+                  index.serviceById.get(store.owner),
+                  allRepos(catalog),
+                )
+              : null;
+            const tone =
+              access.operation === "read"
+                ? "text-accent"
+                : access.operation === "write"
+                  ? "text-verified"
+                  : "text-unresolved";
+            return (
+              <div
+                key={`${access.operation}:${access.method}:${access.source}:${accessIndex}`}
+                className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-2 gap-y-0.5 py-1"
+              >
+                <span className={`chip self-start uppercase ${tone}`}>
+                  {access.operation}
+                </span>
+                <div className="min-w-0">
+                  <div className="mono break-all text-ink">
+                    {access.method ?? "SQL client call"}
+                  </div>
+                  {access.source ? (
+                    <SourcePreviewLink
+                      location={location}
+                      className="mono block break-all text-muted hover:text-accent"
+                    >
+                      {access.source}
+                    </SourcePreviewLink>
+                  ) : null}
+                </div>
+              </div>
+            );
+          })}
+        </>
+      ) : null}
+
       <Label>Referenced by</Label>
       {into.length === 0 ? (
         <div className="mono text-muted">nothing points at this table</div>
@@ -489,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 ? (
@@ -1505,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);
-  });
-});