@shortlink-org/portolan 0.1.0

package/scripts/site-docs.test.mjs

@@ -0,0 +1,181 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { docsDirectory, docsRequest, generatedMount, generatedRequest, mountLinks, readDocsRequest, readGeneratedRequest, siteDocs } from "./site-docs.mjs";
+
+describe("mountLinks", () => {
+  it("points a relative link into the mount", () => {
+    expect(mountLinks("- [Auth](auth/README.md): who someone is", "docs/")).toBe(
+      "- [Auth](docs/auth/README.md): who someone is",
+    );
+  });
+
+  it("keeps a link with a title", () => {
+    expect(mountLinks('[full](llms-full.txt "all pages")', "docs/")).toBe(
+      '[full](docs/llms-full.txt "all pages")',
+    );
+  });
+
+  it("leaves absolute URLs, root paths and anchors alone", () => {
+    const text = "[a](https://example.com/x.md) [b](/root.md) [c](#top) [d](mailto:x@y.z)";
+    expect(mountLinks(text, "docs/")).toBe(text);
+  });
+
+  it("rewrites every link on a line, not only the first", () => {
+    expect(mountLinks("[a](x.md) and [b](y/z.md)", "docs/")).toBe(
+      "[a](docs/x.md) and [b](docs/y/z.md)",
+    );
+  });
+});
+
+describe("docsDirectory", () => {
+  it("is the markdown step's output", () => {
+    expect(docsDirectory({ generate: [{ plugin: "markdown", out: "docs" }] })).toBe("docs");
+  });
+
+  it("is null without a markdown step", () => {
+    expect(docsDirectory({})).toBeNull();
+    expect(docsDirectory({ generate: [{ plugin: "other", out: "x" }] })).toBeNull();
+  });
+});
+
+describe("siteDocs", () => {
+  it("copies the directory, mounts llms.txt at the root and skips the generator's file list", () => {
+    const root = mkdtempSync(join(tmpdir(), "site-docs-"));
+    const docs = join(root, "docs");
+    const dist = join(root, "dist");
+    mkdirSync(join(docs, "auth"), { recursive: true });
+    mkdirSync(dist);
+    writeFileSync(join(docs, "auth", "README.md"), "# Auth\n");
+    writeFileSync(join(docs, ".portolan-manifest"), "{}");
+    writeFileSync(join(docs, "llms.txt"), "# Estate\n\n- [Auth](auth/README.md)\n[full](llms-full.txt)\n");
+    writeFileSync(join(docs, "llms-full.txt"), "<!-- auth/README.md -->\n# Auth\n");
+
+    const written = siteDocs({ manifest: { generate: [{ plugin: "markdown", out: docs }] }, dist });
+
+    expect(written).toEqual(["docs/", "llms.txt", "llms-full.txt"]);
+    expect(readFileSync(join(dist, "docs", "auth", "README.md"), "utf8")).toBe("# Auth\n");
+    expect(existsSync(join(dist, "docs", ".portolan-manifest"))).toBe(false);
+    expect(readFileSync(join(dist, "llms.txt"), "utf8")).toBe(
+      "# Estate\n\n- [Auth](docs/auth/README.md)\n[full](docs/llms-full.txt)\n",
+    );
+    expect(readFileSync(join(dist, "llms-full.txt"), "utf8")).toBe("<!-- auth/README.md -->\n# Auth\n");
+  });
+
+  it("does nothing when the docs are not generated yet", () => {
+    const root = mkdtempSync(join(tmpdir(), "site-docs-"));
+    const dist = join(root, "dist");
+    mkdirSync(dist);
+
+    expect(siteDocs({ manifest: { generate: [{ plugin: "markdown", out: join(root, "missing") }] }, dist })).toEqual([]);
+    expect(existsSync(join(dist, "llms.txt"))).toBe(false);
+  });
+
+  it("places non-markdown generator outputs at their declared paths", () => {
+    const root = mkdtempSync(join(tmpdir(), "site-exports-"));
+    const previous = process.cwd();
+    const dist = join(root, "dist");
+    mkdirSync(join(root, "exports", "mermaid"), { recursive: true });
+    mkdirSync(dist);
+    writeFileSync(join(root, "exports", "mermaid", "checkout.mmd"), "sequenceDiagram\n");
+    process.chdir(root);
+    try {
+      expect(siteDocs({ manifest: { generate: [{ plugin: "mermaid", out: "exports/mermaid" }] }, dist })).toEqual(["exports/mermaid/"]);
+      expect(readFileSync(join(dist, "exports", "mermaid", "checkout.mmd"), "utf8")).toBe("sequenceDiagram\n");
+    } finally {
+      process.chdir(previous);
+    }
+  });
+
+  it("never copies a generator output outside the site root", () => {
+    const root = mkdtempSync(join(tmpdir(), "site-exports-"));
+    const previous = process.cwd();
+    const dist = join(root, "dist");
+    mkdirSync(join(root, "outside"));
+    mkdirSync(dist);
+    writeFileSync(join(root, "outside", "secret.txt"), "secret\n");
+    process.chdir(root);
+    try {
+      expect(siteDocs({ manifest: { generate: [{ plugin: "unsafe", out: "../outside" }] }, dist })).toEqual([]);
+      expect(existsSync(join(dist, "outside", "secret.txt"))).toBe(false);
+    } finally {
+      process.chdir(previous);
+    }
+  });
+});
+
+describe("generatedMount", () => {
+  it("normalizes safe paths and rejects absolute or escaping paths", () => {
+    expect(generatedMount({ plugin: "mermaid", out: "./exports/mermaid/" })).toBe("exports/mermaid");
+    expect(generatedMount({ plugin: "other", out: "../outside" })).toBeNull();
+    expect(generatedMount({ plugin: "other", out: "/tmp/outside" })).toBeNull();
+    expect(generatedMount({ plugin: "other", out: "exports\\outside" })).toBeNull();
+  });
+});
+
+describe("docsRequest", () => {
+  it("names the three files under the base", () => {
+    expect(docsRequest("/llms.txt")).toEqual({ kind: "index" });
+    expect(docsRequest("/portolan/llms-full.txt", "/portolan/")).toEqual({ kind: "full" });
+    expect(docsRequest("/portolan/docs/auth/README.md", "/portolan/")).toEqual({ kind: "page", path: "auth/README.md" });
+  });
+
+  it("sends a directory to its index and a bare docs to its slash", () => {
+    expect(docsRequest("/docs/")).toEqual({ kind: "page", path: "README.md" });
+    expect(docsRequest("/docs/auth/")).toEqual({ kind: "page", path: "auth/README.md" });
+    expect(docsRequest("/docs", "/")).toEqual({ kind: "redirect", to: "/docs/" });
+  });
+
+  it("is not for the app's routes, another base, or a path that climbs out", () => {
+    expect(docsRequest("/flows")).toBeNull();
+    expect(docsRequest("/llms.txt", "/portolan/")).toBeNull();
+    expect(docsRequest("/docs/../portolan.json")).toBeNull();
+    expect(docsRequest("/docs/%2e%2e/portolan.json")).toBeNull();
+    expect(docsRequest("/docs/.portolan-manifest")).toBeNull();
+  });
+});
+
+describe("readDocsRequest", () => {
+  const root = mkdtempSync(join(tmpdir(), "site-docs-"));
+  const docs = join(root, "docs");
+  mkdirSync(join(docs, "auth"), { recursive: true });
+  writeFileSync(join(docs, "auth", "README.md"), "# Auth\n");
+  writeFileSync(join(docs, ".portolan-manifest"), "{}");
+  writeFileSync(join(docs, "llms.txt"), "- [Auth](auth/README.md)\n");
+  writeFileSync(join(docs, "llms-full.txt"), "all\n");
+
+  it("mounts the index and passes the rest through with a type", () => {
+    expect(readDocsRequest(docs, { kind: "index" })).toEqual({ type: "text/plain; charset=utf-8", body: "- [Auth](docs/auth/README.md)\n" });
+    expect(readDocsRequest(docs, { kind: "full" })?.body.toString()).toBe("all\n");
+    const page = readDocsRequest(docs, { kind: "page", path: "auth/README.md" });
+    expect(page?.type).toBe("text/markdown; charset=utf-8");
+    expect(page?.body.toString()).toBe("# Auth\n");
+  });
+
+  it("answers a directory with its index, and nothing for what is not there", () => {
+    expect(readDocsRequest(docs, { kind: "page", path: "auth" })?.body.toString()).toBe("# Auth\n");
+    expect(readDocsRequest(docs, { kind: "page", path: "missing.md" })).toBeNull();
+    expect(readDocsRequest(docs, { kind: "page", path: ".portolan-manifest" })).toBeNull();
+    expect(readDocsRequest(docs, { kind: "redirect", to: "/docs/" })).toBeNull();
+  });
+});
+
+describe("generated outputs in development", () => {
+  const manifest = { generate: [{ plugin: "mermaid", out: "exports/mermaid" }] };
+
+  it("routes an index and a file without allowing traversal", () => {
+    expect(generatedRequest("/exports/mermaid/", manifest)).toEqual({ kind: "artifact", path: "exports/mermaid/README.md" });
+    expect(generatedRequest("/exports/mermaid/a.mmd", manifest)).toEqual({ kind: "artifact", path: "exports/mermaid/a.mmd" });
+    expect(generatedRequest("/exports/mermaid/%2e%2e/secret", manifest)).toBeNull();
+  });
+
+  it("reads only a generated file under the workspace", () => {
+    const root = mkdtempSync(join(tmpdir(), "generated-request-"));
+    mkdirSync(join(root, "exports", "mermaid"), { recursive: true });
+    writeFileSync(join(root, "exports", "mermaid", "a.mmd"), "sequenceDiagram\n");
+    const answer = readGeneratedRequest(root, { kind: "artifact", path: "exports/mermaid/a.mmd" });
+    expect(answer?.type).toBe("text/plain; charset=utf-8");
+    expect(answer?.body.toString()).toBe("sequenceDiagram\n");
+  });
+});

package/scripts/vendor-lock.mjs

@@ -0,0 +1,58 @@
+// 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

@@ -0,0 +1,69 @@
+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);
+  });
+});

package/src/README.md

@@ -0,0 +1,38 @@
+# Site
+
+The browser: a React single-page application that loads every source the
+manifest names, merges them, validates the union and renders the estate.
+Static end to end; there is no backend and no runtime query.
+
+## What it does
+
+- Decides the shape of a catalog. `catalog.ts` is the contract, with the
+  reasoning beside each field; `catalog/` in Go is a mirror of it, held by a
+  round-trip test (portolan.0003). The validator lives here too, and runs
+  before anything is drawn: a catalog that fails renders the failure.
+- Merges sources and derives what they imply. `merge.ts` and `enrich.ts` are
+  the same code the host runs, so the site and the generated documentation
+  cannot disagree about what the estate is.
+- Renders the entity pages, the flows with their step rail and chains, the
+  Problems page, the language page, the ER canvases, the C4 views the
+  LikeC4 bundle carries, and the navigation around them.
+
+## What it does not do
+
+- Draw a C4 view itself: `likec4/` is written from the catalog by the host,
+  and the site embeds the generated bundle.
+- Run a plugin, read a tree or stamp anything; the fragments arrive as JSON
+  through the build.
+- Persist anything but a reader's own conveniences, pins and the trail, in
+  the browser.
+
+## Layout
+
+- `catalog.ts`, `merge.ts`, `enrich.ts`, `data.ts`: the contract, the merge,
+  what the merge implies, and where the sources are found.
+- `pages/`, `components/`, `app/`: what a reader sees.
+- `flow/`, `graph/`, `map/`, `er/`, `language/`, `table/`, `selection/`,
+  `trail/`: one directory per kind of view.
+- `lib/`: what the views share, one concern per file.
+- `likec4/`: the generated bundle and the ids it is asked for.
+- `testing/`: the frozen estate the UI tests run against.