@rocksoliddigital/payload-lineage 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rock Solid Digital
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,151 @@
-# Temporary Holding Version
+# 🧬 @rocksoliddigital/payload-lineage
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The content side of lineage, from a Payload config, as two pages in the admin:
+
+- **Lineage** (`/admin/lineage`): collections, globals and blocks, and the fields that link them,
+  read left to right from what each is built from to where it is used: `media` →
+  `block:mediaBlock` → `pages`. Hover a node to trace everything upstream and downstream; click it
+  for the fields behind each link.
+- **Data model** (`/admin/lineage/schema`): an ERD, with a table per collection and global listing
+  its fields, and a line from each field that references another collection, labelled with its
+  cardinality:
+
+| Label          | Means                                                                     |
+| -------------- | ------------------------------------------------------------------------- |
+| `many-to-one`  | One reference per document, which many documents can share                |
+| `many-to-many` | A list of references: `hasMany`, or inside an array or blocks field       |
+| `one-to-one`   | A `unique` reference, or a global's single one (a global is one document) |
+| `one-to-many`  | A global's list of references                                             |
+
+Both are built from the running config on each visit (well under a millisecond), so they are never
+out of date. A "Lineage" link in the nav opens them. To try them, run the
+[example](https://github.com/rock-solid/lineage-kit/tree/main/examples/payload).
+
+**Copy Mermaid**, on both pages, copies what the page shows, with its filters, as a Mermaid diagram:
+the lineage as a flowchart, the data model as an `erDiagram` in crow's-foot notation. Paste it into
+a PR, a doc or a ticket, and GitHub, GitLab and most docs tools draw it.
+
+Works with Payload 3 on Next.js 15 or 16, with React 19.
+
+> **Status:** early. Both pages come from the config only. Which pages use which blocks (from the
+> documents), shared field configs (by import scan) and merging into the Storybook page are next;
+> see the [roadmap](https://github.com/rock-solid/lineage-kit/blob/main/ROADMAP.md#-payload-plugin).
+
+## 📥 Install
+
+```sh
+pnpm add @rocksoliddigital/payload-lineage
+```
+
+## ⚙️ Set up
+
+Add the plugin to `payload.config.ts`:
+
+```ts
+import { lineagePlugin } from '@rocksoliddigital/payload-lineage';
+
+export default buildConfig({
+  // ...
+  plugins: [lineagePlugin()],
+});
+```
+
+Then update the import map, so the admin can find the pages. `next dev` does this on its own; for a
+build, run:
+
+```sh
+pnpm payload generate:importmap
+```
+
+| Option       | Default |                                                                                   |
+| ------------ | ------- | --------------------------------------------------------------------------------- |
+| `adminView`  | `true`  | The two admin pages and the nav link                                              |
+| `access`     | none    | `({ user, payload }) => boolean`, on top of admin access; see [Access](#-access)  |
+| `outputFile` | none    | Where to write the lineage graph as JSON on each start, outside production only   |
+| `exclude`    | `[]`    | Slugs to leave out of both pages and the file; `block:text` names only that block |
+| `enabled`    | `true`  | Set to `false` to turn the plugin off                                             |
+
+Payload's own collections (`payload-preferences`, `payload-migrations`, ...) are always left out. If
+the file can't be written (e.g. a read-only filesystem), Payload logs a warning and starts anyway.
+
+To leave out form-builder's field blocks, which crowd the lineage graph:
+
+```ts
+lineagePlugin({
+  exclude: [
+    'checkbox',
+    'country',
+    'email',
+    'message',
+    'number',
+    'select',
+    'state',
+    'text',
+    'textarea',
+  ].map((s) => `block:${s}`),
+});
+```
+
+Or build either yourself, e.g. in a script, and keep a diagram in your docs up to date:
+
+```ts
+import {
+  buildContentGraph,
+  buildSchema,
+  contentGraphToMermaid,
+  schemaToMermaid,
+} from '@rocksoliddigital/payload-lineage';
+import config from '@payload-config';
+
+const graph = buildContentGraph(await config);
+const schema = buildSchema(await config);
+const diagram = schemaToMermaid(schema); // or contentGraphToMermaid(graph)
+```
+
+## 🔒 Access
+
+The pages and their nav link are for users who can use the admin (Payload's `access.admin` on the
+users collection, which Payload itself doesn't check on custom pages), and who pass the plugin's
+`access`, if set:
+
+```ts
+lineagePlugin({ access: ({ user }) => user.role === 'admin' });
+```
+
+Anyone else is sent where Payload sends them for its own pages: the login page when logged out, the
+unauthorized page when logged in, each with a `redirect` back. The pages show only the collections
+and globals the user can read, along with every link to or from them; blocks have no access control
+of their own, so they're all shown. Everything is checked and built on the server, so nothing a user
+can't see reaches the browser.
+
+## 📄 The lineage file
+
+```json
+{
+  "nodes": [
+    { "id": "collection:media", "kind": "collection", "slug": "media", "label": "Media" },
+    { "id": "block:mediaBlock", "kind": "block", "slug": "mediaBlock", "label": "Media Block" }
+  ],
+  "edges": [
+    {
+      "source": "collection:media",
+      "target": "block:mediaBlock",
+      "kind": "upload",
+      "fields": ["media"]
+    }
+  ]
+}
+```
+
+Node ids are `<kind>:<slug>`, so they can't clash with the file paths the Storybook addon uses as
+ids. `source` is the dependency and `target` what uses it, as in the Storybook addon. Join fields are
+left out, since each is the reverse of a relationship that is already an edge. A collection that
+links to itself, like nested-docs' `parent`, keeps the edge to itself.
+
+## 🗂️ The data model
+
+`buildSchema` flattens groups, rows, collapsibles and tabs into dotted rows (`hero.media`), and keeps
+each array and blocks field as one row (`gallery[]`, `layout`). A reference inside one of those
+attaches to that row, with its full path: `layout[mediaBlock].media`. Hidden fields (an auth
+collection's `salt` and `hash`) and UI fields are left out. A join field is a row but not a line,
+since it reverses a relationship that already is one.

package/dist/chunk-GL5UMO2C.js

@@ -0,0 +1,203 @@
+// src/graph.ts
+var INTERNAL_COLLECTION = /^payload-/;
+function buildContentGraph(config, { exclude = [] } = {}) {
+  const excluded = (kind, slug) => kind === "collection" && INTERNAL_COLLECTION.test(slug) || exclude.includes(slug) || exclude.includes(`${kind}:${slug}`);
+  const collections = (config.collections ?? []).filter((c) => !excluded("collection", c.slug));
+  const globals = (config.globals ?? []).filter((g) => !excluded("global", g.slug));
+  const sharedBlocks = new Map((config.blocks ?? []).map((b) => [b.slug, b]));
+  const nodes = /* @__PURE__ */ new Map();
+  const addNode = (kind, slug, label) => {
+    const id = `${kind}:${slug}`;
+    if (!nodes.has(id)) nodes.set(id, { id, kind, slug, label });
+    return id;
+  };
+  for (const c of collections) addNode("collection", c.slug, labelOf(c, c.labels?.plural));
+  for (const g of globals) addNode("global", g.slug, labelOf(g, g.label));
+  const collectionIds = new Set(collections.map((c) => `collection:${c.slug}`));
+  const edges = /* @__PURE__ */ new Map();
+  const addEdge = (source, target, kind, field) => {
+    const key = `${source}\u2192${target}\u2192${kind}`;
+    const edge = edges.get(key) ?? { source, target, kind, fields: [] };
+    if (!edge.fields.includes(field)) edge.fields.push(field);
+    edges.set(key, edge);
+  };
+  const walkedBlocks = /* @__PURE__ */ new Set();
+  const walkBlock = (block) => {
+    const id = addNode("block", block.slug, labelOf(block, block.labels?.singular));
+    if (walkedBlocks.has(block)) return id;
+    walkedBlocks.add(block);
+    walkFields(block.fields, id, []);
+    return id;
+  };
+  const walkFields = (fields, owner, path) => {
+    for (const field of fields) {
+      const fieldPath = field.name ? [...path, field.name] : path;
+      const dotted = fieldPath.join(".");
+      if (field.type === "relationship" || field.type === "upload") {
+        for (const slug of toArray(field.relationTo)) {
+          const source = `collection:${slug}`;
+          if (collectionIds.has(source)) addEdge(source, owner, field.type, dotted);
+        }
+      }
+      if (field.type === "blocks") {
+        const blocks = [
+          ...field.blocks ?? [],
+          ...(field.blockReferences ?? []).map(
+            (b) => typeof b === "string" ? sharedBlocks.get(b) : b
+          )
+        ];
+        for (const block of blocks) {
+          if (block && !excluded("block", block.slug)) {
+            addEdge(walkBlock(block), owner, "blocks", dotted);
+          }
+        }
+      }
+      if (field.fields) walkFields(field.fields, owner, fieldPath);
+      for (const tab of field.tabs ?? []) {
+        walkFields(tab.fields, owner, tab.name ? [...fieldPath, tab.name] : fieldPath);
+      }
+    }
+  };
+  for (const c of collections) walkFields(c.fields, `collection:${c.slug}`, []);
+  for (const g of globals) walkFields(g.fields, `global:${g.slug}`, []);
+  return { nodes: [...nodes.values()], edges: [...edges.values()] };
+}
+function labelOf(entity, label) {
+  return typeof label === "string" ? label : entity.slug;
+}
+function toArray(value) {
+  if (value === void 0) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+// src/schema.ts
+var INTERNAL_COLLECTION2 = /^payload-/;
+var LAYOUT = /* @__PURE__ */ new Set(["row", "collapsible"]);
+function buildSchema(config, { exclude = [] } = {}) {
+  const { collections = [], globals = [], blocks = [] } = config;
+  const excluded = (kind, slug) => kind === "collection" && INTERNAL_COLLECTION2.test(slug) || exclude.includes(slug) || exclude.includes(`${kind}:${slug}`);
+  const shownCollections = collections.filter((c) => !excluded("collection", c.slug));
+  const shownGlobals = globals.filter((g) => !excluded("global", g.slug));
+  const targets = new Set(shownCollections.map((c) => c.slug));
+  const sharedBlocks = new Map(blocks.map((b) => [b.slug, b]));
+  const relations = [];
+  const entity = (kind, e) => {
+    const id = `${kind}:${e.slug}`;
+    const fields = [];
+    const onPath = /* @__PURE__ */ new Set();
+    const walk = (list, path, row, many) => {
+      for (const field of list) {
+        if (field.type === "ui" || field.hidden) continue;
+        if (LAYOUT.has(field.type) || field.type === "group" && !field.name) {
+          walk(field.fields ?? [], path, row, many);
+          continue;
+        }
+        if (field.type === "tabs") {
+          for (const tab of field.tabs ?? []) {
+            walk(tab.fields, tab.name ? join(path, tab.name) : path, row, many);
+          }
+          continue;
+        }
+        const name = join(path, field.name ?? field.type);
+        if (field.type === "group") {
+          walk(field.fields ?? [], name, row, many);
+          continue;
+        }
+        if (field.type === "array") {
+          const own2 = row ?? add({ name: `${name}[]`, type: "array", required: field.required });
+          walk(field.fields ?? [], `${name}[]`, own2, true);
+          continue;
+        }
+        if (field.type === "blocks") {
+          const allowed = [
+            ...field.blocks ?? [],
+            ...(field.blockReferences ?? []).map(
+              (b) => typeof b === "string" ? sharedBlocks.get(b) : b
+            )
+          ].filter((b) => b !== void 0 && !excluded("block", b.slug));
+          const own2 = row ?? add({
+            name,
+            type: "blocks",
+            required: field.required,
+            blocks: allowed.map((b) => b.slug)
+          });
+          for (const block of allowed) {
+            if (onPath.has(block)) continue;
+            onPath.add(block);
+            walk(block.fields, `${name}[${block.slug}]`, own2, true);
+            onPath.delete(block);
+          }
+          continue;
+        }
+        const own = row ?? add({
+          name,
+          type: field.type,
+          required: field.required,
+          hasMany: field.hasMany,
+          localized: field.localized,
+          unique: field.unique,
+          ...(field.relationTo || field.collection) && {
+            relationTo: toArray2(field.relationTo ?? field.collection)
+          }
+        });
+        if (field.type === "relationship" || field.type === "upload") {
+          const to = toArray2(field.relationTo);
+          for (const slug of to) {
+            if (!targets.has(slug)) continue;
+            relations.push({
+              from: id,
+              field: own.name,
+              path: name,
+              to: `collection:${slug}`,
+              kind: field.type,
+              many: many || !!field.hasMany,
+              polymorphic: to.length > 1,
+              unique: !!field.unique
+            });
+          }
+        }
+      }
+    };
+    const add = (field) => {
+      const clean = Object.fromEntries(
+        Object.entries(field).filter(([, v]) => v !== void 0 && v !== false)
+      );
+      fields.push(clean);
+      return clean;
+    };
+    walk(e.fields, "", null, false);
+    if (kind === "collection" && !fields.some((f) => f.name === "id")) {
+      fields.unshift({ name: "id", type: "id", required: true });
+    }
+    return {
+      id,
+      kind,
+      slug: e.slug,
+      label: labelOf2(e, kind === "collection" ? e.labels?.plural : e.label),
+      singular: labelOf2(e, kind === "collection" ? e.labels?.singular : e.label),
+      ...kind === "collection" && e.auth ? { auth: true } : {},
+      ...kind === "collection" && e.upload ? { upload: true } : {},
+      fields
+    };
+  };
+  const entities = [
+    ...shownCollections.map((c) => entity("collection", c)),
+    ...shownGlobals.map((g) => entity("global", g))
+  ];
+  return { entities, relations };
+}
+function join(path, name) {
+  return path ? `${path}.${name}` : name;
+}
+function labelOf2(entity, label) {
+  return typeof label === "string" ? label : entity.slug;
+}
+function toArray2(value) {
+  if (value === void 0) return [];
+  return Array.isArray(value) ? value : [value];
+}
+
+export {
+  buildContentGraph,
+  buildSchema
+};

package/dist/client.d.ts

@@ -0,0 +1,104 @@
+import React from 'react';
+
+type ContentKind = 'collection' | 'global' | 'block';
+type ContentNode = {
+    /** `<kind>:<slug>`, e.g. `collection:pages` or `block:hero`. */
+    id: string;
+    kind: ContentKind;
+    slug: string;
+    label: string;
+};
+/** What makes one node depend on another. */
+type ContentEdgeKind = 'relationship' | 'upload' | 'blocks';
+/**
+ * `source` is the dependency, `target` the collection, global or block whose fields point at it,
+ * so the graph reads left to right like the Storybook addon's: `media` → `pages`.
+ */
+type ContentEdge = {
+    source: string;
+    target: string;
+    kind: ContentEdgeKind;
+    /** Dotted paths of the fields that make the link, e.g. `layout` or `hero.image`. */
+    fields: string[];
+};
+type ContentGraph = {
+    nodes: ContentNode[];
+    edges: ContentEdge[];
+};
+
+type SchemaField = {
+    /** Dotted from the top level; arrays end in `[]`, e.g. `hero.media` or `gallery[]`. */
+    name: string;
+    type: string;
+    required?: boolean;
+    /** A relationship, upload, select, text or number field holding a list. */
+    hasMany?: boolean;
+    localized?: boolean;
+    unique?: boolean;
+    /** Collections a relationship, upload or join field points at. */
+    relationTo?: string[];
+    /** Block slugs a blocks field allows. */
+    blocks?: string[];
+};
+type SchemaEntity = {
+    /** `collection:<slug>` or `global:<slug>`, as in the content graph. */
+    id: string;
+    kind: 'collection' | 'global';
+    slug: string;
+    /** Plural for a collection (`Pages`), the global's name for a global. */
+    label: string;
+    /** One document: `Page`. A global's name, since it is one already. */
+    singular: string;
+    /** An auth collection (users) or an upload collection (media). */
+    auth?: boolean;
+    upload?: boolean;
+    fields: SchemaField[];
+};
+type SchemaRelation = {
+    /** The entity holding the reference. */
+    from: string;
+    /** The row in `from` it belongs to: the field itself, or the array or blocks field around it. */
+    field: string;
+    /** The full path of the referencing field, e.g. `layout[mediaBlock].media`. */
+    path: string;
+    /** The collection referenced. */
+    to: string;
+    kind: 'relationship' | 'upload';
+    /** Many references per document: `hasMany`, or inside an array or blocks field. */
+    many: boolean;
+    /** The field can point at more than one collection. */
+    polymorphic: boolean;
+    /** No two documents may reference the same one: a `unique` field. */
+    unique: boolean;
+};
+type Schema = {
+    entities: SchemaEntity[];
+    relations: SchemaRelation[];
+};
+
+type ErdCanvasProps = {
+    schema: Schema;
+    /** Admin URLs of the collections and globals, by entity id, for the "Open" links. */
+    adminURLs: Record<string, string>;
+};
+/** The data model as an ERD: a table per collection and global, a line per reference. */
+declare const ErdCanvas: React.FC<ErdCanvasProps>;
+
+type LineageCanvasProps = {
+    graph: ContentGraph;
+    /** Admin URLs of the collections and globals, by node id, for the "Open" links. */
+    adminURLs: Record<string, string>;
+};
+/**
+ * The content graph, left to right from what an entity is built from to where it is used. Hover to
+ * trace, click for the fields behind each link.
+ */
+declare const LineageCanvas: React.FC<LineageCanvasProps>;
+
+/**
+ * "Lineage" in the admin's nav, after the collections and globals, marked like theirs on either
+ * lineage page. Rendered by the server component `LineageNavLink`, which checks access first.
+ */
+declare const LineageNavLinkClient: React.FC;
+
+export { ErdCanvas, type ErdCanvasProps, LineageCanvas, type LineageCanvasProps, LineageNavLinkClient };