@simmalugnt-se/payload-content-health 0.9.0 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.10.0
+
+- Links in globals: `globals: { header: { links: true }, footer: { links: true } }` checks every
+  link field in those globals for `links.broken`. A finding in a global is marked `global: true`,
+  with the global's slug as `collection` and `id`; its work-list row shows the global's name and
+  opens the global with the link's field in view, and the assistant's `content-health.findings`
+  includes it.
+- New check `links.orphan` (Structure, "Nothing links here"): a published document that no
+  published page body or global with `links` links to, in any language, not counting links to
+  itself. A global counts as the site reads it, even one never published. Off by default; turn it on per collection with `orphans: true`, or
+  `orphans: { exclude: <where> }` to leave out the start page or other intentionally unlinked pages.
+- Opening a field inside an array row from a finding waits until the form has the row, so a footer
+  link in a collapsed row opens and is selected.
+
 ## 0.9.0
 
 - New check `media.video-description-missing` (Accessibility), turned on per collection with

package/README.md

@@ -2,7 +2,8 @@
 
 Deterministic content checks for Payload, shown as a dashboard widget and a work list: images
 without alt text, missing or badly sized meta titles and descriptions, pages without a share image,
-heading structure and thin content. No AI; every finding points at one field of one document, in one
+heading structure, thin content, broken internal links (in pages and in globals such as the header
+and footer) and published pages nothing links to. No AI; every finding points at one field of one document, in one
 locale when the field is localized, and opens that field in Admin.
 
 Requires Payload `>=3.90.2 <4`, Next 16 and React 19. The widget uses Payload's modular dashboard
@@ -54,7 +55,8 @@ Requires Payload `>=3.90.2 <4`, Next 16 and React 19. The widget uses Payload's
 | `content.h1-multiple`       | `content.headings` | More than one H1                               |
 | `content.heading-skip`      | `content.headings` | A heading level skipped, e.g. H2 → H4          |
 | `content.thin`              | `content`          | Fewer than 300 words on the page               |
-| `links.broken`              | `content`          | Internal links to deleted or unpublished pages |
+| `links.broken`              | `content`, `globals` | Internal links to deleted or unpublished pages |
+| `links.orphan`              | `orphans`          | Published pages nothing links to               |
 | `content.untranslated`      | `translations`     | Localized text empty here, filled in default   |
 
 `seo: true` reads the fields `@payloadcms/plugin-seo` adds (`meta.title`, `meta.description`,
@@ -107,6 +109,56 @@ published pages. Targets are looked up without access control; only their title
 are published reach the list. Each page gets one finding per language, at the first broken link,
 with how many there are.
 
+### Header, footer and other globals
+
+A menu link to an unpublished page is the broken link most readers meet, but it lives in a global,
+not in a page body. `globals` turns on `links.broken` for globals by slug:
+
+```ts
+contentHealthPlugin({
+  collections: { pages: { content: { field: "layout" } } },
+  globals: { header: { links: true }, footer: { links: true } },
+}),
+```
+
+Every link field in the global is read: relationship fields (such as a link group's reference,
+skipped when the group is an outside link) and rich text, also inside arrays, groups and tabs.
+Blocks fields in a global are not read. A global gets one finding per language like a page; the row
+is labeled with the global's name and opens the global with the link's field in view
+(`/admin/globals/footer?field=navItems.2.link.reference`). The assistant's `content-health.findings`
+takes a global's slug as `collection`. Only links are checked in globals.
+
+### Pages nothing links to
+
+`orphans: true` reports published documents of the collection that nothing links to
+(`links.orphan`, "Nothing links here", under Structure): a reader cannot reach them by following
+links on the site. One finding per document; it opens the document, and the row says where a link
+usually comes from (the menu or a related page). Off by default, since a site with a search page or
+campaign landing pages may want pages without links.
+
+```ts
+collections: {
+  pages: {
+    content: { field: "layout" },
+    orphans: { exclude: { slug: { equals: "home" } } },
+  },
+},
+globals: { header: { links: true }, footer: { links: true } },
+```
+
+A link counts when a reader can follow it today:
+
+- it is in the published version of a page body (`content`), so a link only in a page's draft does
+  not count yet, or in a global with `links` as the site reads it (`draft: false`): a global saved
+  as a draft but never published is still shown, so its links count;
+- in any language;
+- from another document: a page linking to itself does not count.
+
+Redirects are not links. The plugin cannot tell which page is the start page, so leave it out with
+`exclude`, a Payload `where` query; any other intentionally unlinked page can go there too. Drafts
+are never reported. Without `globals`, every page reached only from the menu looks unlinked, so turn
+on the globals that hold the site's navigation first.
+
 ### Translations
 
 `translations: true` compares every language with the default one (Payload's
@@ -133,7 +185,7 @@ the widget from the dashboard's edit mode, and can limit it to some checks in it
 
 The widget is a summary: the share of checked values in order, and one row per category with a bar
 and how much there is to fix. Categories group the checks: SEO (meta titles and descriptions, their
-lengths, share images), Structure (headings, page length), Translations and Accessibility (alt
+lengths, share images), Structure (headings, page length, links), Translations and Accessibility (alt
 texts). A category none of the configured checks belong to is left out. Each row opens the work list
 on that category, and "Open details" opens the list itself.
 
@@ -197,7 +249,7 @@ const { findings, problems } = await scanContentHealth({ payload, user: req.user
 ```
 
 Each finding is
-`{ check, collection, id, title, path, locale?, length?, range?, heading?, words?, status? }`, where
-`path` is the form path with row indexes (`layout.1.items.0.title`) and `range` is the length a
+`{ check, collection, id, title, path, locale?, length?, range?, heading?, words?, status?, global? }`,
+where `global: true` marks a finding in a global (its slug is both `collection` and `id`) and `path` is the form path with row indexes (`layout.1.items.0.title`) and `range` is the length a
 missing meta title or description should have. `problems` lists configured checks that could not
 run, such as a field path that does not exist.

package/dist/admin/ContentHealthFieldBridge.d.ts

@@ -1,6 +1,6 @@
 import "../styles/admin.css";
 /**
- * Mounted in the edit view of each checked collection. When the address carries `?field=<path>`
+ * Mounted in the edit view of each checked collection and global. When the address carries `?field=<path>`
  * (a link from the work list or the widget), it opens the tabs and rows around that field, scrolls
  * to it, focuses and highlights it, then announces it with `content-health:select` so the editor
  * assistant takes it as the selection. The parameter is removed from the address once read.

package/dist/admin/ContentHealthFieldBridge.js

@@ -21,7 +21,7 @@ const STABLE_FRAMES = 3;
 /** Roughly how long a smooth scroll takes. */
 const SCROLL_MS = 600;
 /**
- * Mounted in the edit view of each checked collection. When the address carries `?field=<path>`
+ * Mounted in the edit view of each checked collection and global. When the address carries `?field=<path>`
  * (a link from the work list or the widget), it opens the tabs and rows around that field, scrolls
  * to it, focuses and highlights it, then announces it with `content-health:select` so the editor
  * assistant takes it as the selection. The parameter is removed from the address once read.
@@ -29,13 +29,14 @@ const SCROLL_MS = 600;
 export function ContentHealthFieldBridge() {
     const form = useDocumentForm();
     const { config, getEntityConfig } = useConfig();
-    const { collectionSlug } = useDocumentInfo();
+    const { collectionSlug, globalSlug } = useDocumentInfo();
+    const entity = { collectionSlug, globalSlug };
     const anchorRef = useRef(null);
-    const latest = useRef({ form, config, getEntityConfig, collectionSlug });
+    const latest = useRef({ form, config, getEntityConfig, entity });
     // Kept across effect re-runs: the parameter is gone from the address after the first read.
     const requested = useRef(undefined);
     useEffect(() => {
-        latest.current = { form, config, getEntityConfig, collectionSlug };
+        latest.current = { form, config, getEntityConfig, entity };
     });
     useEffect(() => {
         if (requested.current === undefined) {
@@ -49,12 +50,9 @@ export function ContentHealthFieldBridge() {
         const current = () => !cancelled;
         void (async () => {
             const plan = () => {
-                const { form, config, getEntityConfig, collectionSlug } = latest.current;
+                const { form, config, getEntityConfig, entity } = latest.current;
                 const fields = form.getFields();
-                const rootFields = collectionSlug
-                    ? (getEntityConfig({ collectionSlug })
-                        ?.fields ?? [])
-                    : [];
+                const rootFields = rootFieldsOf(getEntityConfig, entity);
                 const lookup = {
                     blockTypeAt: (rowPath) => rowAt(fields, rowPath)?.blockType,
                     blocksBySlug: config.blocksMap,
@@ -63,10 +61,13 @@ export function ContentHealthFieldBridge() {
                 return { form, fields, target };
             };
             // The form's rows can arrive just after the page loads; until they do, a path in a block
-            // only plans as far as its blocks field. Wait for the whole path before settling for less.
+            // only plans as far as its blocks field, and an array row plans but cannot be expanded.
+            // Wait for the whole path and its rows before settling for less.
             const planned = (await waitFor(() => {
                 const attempt = plan();
-                return attempt.target?.path === path ? attempt : null;
+                return attempt.target?.path === path && rowsLoaded(attempt.target.steps, attempt.fields)
+                    ? attempt
+                    : null;
             })) ?? plan();
             const { target } = planned;
             if (!target || !current()) {
@@ -120,6 +121,10 @@ function expandRows(steps, fields, dispatchFields) {
         });
     }
 }
+/** Whether the form state has every row the steps enter, so collapsed ones can be expanded. */
+function rowsLoaded(steps, fields) {
+    return steps.every((step) => step.kind !== "row" || rowAt(fields, `${step.parentPath}.${step.index}`) !== undefined);
+}
 function rowAt(fields, rowPath) {
     const cut = rowPath.lastIndexOf(".");
     return fields[rowPath.slice(0, cut)]?.rows?.[Number(rowPath.slice(cut + 1))];
@@ -323,3 +328,12 @@ function isFocusable(element) {
         element instanceof HTMLSelectElement ||
         element.isContentEditable);
 }
+/** The edited collection's or global's fields, as `VisualEditingAdminBridge` reads them. */
+function rootFieldsOf(getEntityConfig, { collectionSlug, globalSlug }) {
+    const entity = collectionSlug
+        ? getEntityConfig({ collectionSlug })
+        : globalSlug
+            ? getEntityConfig({ globalSlug })
+            : undefined;
+    return entity?.fields ?? [];
+}

package/dist/assistant.js

@@ -1,5 +1,5 @@
 import { CATEGORY_IDS, categoryOf, categoryStats } from "./categories.js";
-import { BATCH_ASK, CATEGORY_LABELS, CHECK_LABELS, findingDetail, uiLanguage } from "./copy.js";
+import { ASK, BATCH_ASK, CATEGORY_LABELS, CHECK_LABELS, findingDetail, uiLanguage, } from "./copy.js";
 import { checkStats, countDocuments, sortFindings } from "./group.js";
 import { assistantCollections, BATCH_CHECKS, batchCollections, batchTarget, batchURL, listURL, MAX_BATCH_TARGETS, matchesFilters, VIEW_PATH, } from "./links.js";
 import { scanContentHealth } from "./scan.js";
@@ -34,7 +34,10 @@ const filterInput = {
         description: "seo, structure, translations or accessibility.",
     },
     check: { type: "string", enum: [...CHECK_IDS], description: "One check, by id." },
-    collection: { type: "string", description: "Collection slug, such as pages or images." },
+    collection: {
+        type: "string",
+        description: "Collection or global slug, such as pages, images or footer.",
+    },
     locale: { type: "string", description: "Only findings in this content language." },
 };
 /** `scan` is replaceable for tests. */
@@ -43,7 +46,7 @@ export function assistantExtension({ scan: run = scanContentHealth, } = {}) {
     return {
         id: EXTENSION_ID,
         instructions: [
-            "Content health checks the site's content: SEO (meta titles, descriptions, share images, duplicates), structure (H1, heading levels, thin content, broken internal links), translations (fields empty in a language) and accessibility (image alt texts).",
+            "Content health checks the site's content: SEO (meta titles, descriptions, share images, duplicates), structure (H1, heading levels, thin content, broken internal links, also in the header and footer, and pages nothing links to), translations (fields empty in a language) and accessibility (image alt texts).",
             "When the editor asks what needs work, how the site or a page is doing, or what to fix first, call content-health.findings and answer from it, naming pages and problems. Never ask for a screenshot of content health.",
             'Each finding says how it is fixed: "batch" (many documents at once from the work list), "assistant" (on the document, with you) or "by hand". To start fixing, call content-health.open: with batch true for a batch check, else the work list. It takes the editor there; they start the fix and review each change themselves. Say where they are now ("The 9 missing alt texts are open; Fix 9 with the assistant starts them."); never say anything is fixed or started, and do not propose changes yourself for findings outside the open document. Do not mention findings the tool left out unless the editor asks for more.',
         ].join(" "),
@@ -105,7 +108,9 @@ async function findings(input, { req, open }, result) {
         ? { collection: filters.collection, id: String(input.documentId) }
         : !filtered && open?.collection && open.id !== undefined
             ? { collection: open.collection, id: String(open.id) }
-            : undefined;
+            : !filtered && open?.global
+                ? { collection: open.global, id: open.global }
+                : undefined;
     const matching = sortFindings(result.findings).filter((finding) => matchesFilters(finding, filters) &&
         (!document ||
             ((!document.collection || finding.collection === document.collection) &&
@@ -133,6 +138,7 @@ async function findings(input, { req, open }, result) {
                 detail: findingDetail("en", finding),
                 collection: finding.collection,
                 id: finding.id,
+                ...(finding.global ? { global: true } : {}),
                 title: finding.title,
                 field: finding.path,
                 ...(finding.locale ? { locale: finding.locale } : {}),
@@ -187,7 +193,9 @@ async function open(input, { req }, scan) {
 function fixFor(finding, inBatches, withAssistant) {
     if (BATCH_CHECKS[finding.check] && inBatches.has(finding.collection))
         return "batch";
-    return withAssistant.has(finding.collection) ? "assistant" : "by hand";
+    return !finding.global && ASK.en[finding.check] && withAssistant.has(finding.collection)
+        ? "assistant"
+        : "by hand";
 }
 function readInput(input) {
     const text = (value) => (typeof value === "string" && value ? value : undefined);

package/dist/categories.js

@@ -16,6 +16,7 @@ export const CATEGORY_CHECKS = {
         "content.heading-skip",
         "content.thin",
         "links.broken",
+        "links.orphan",
     ],
     translations: ["content.untranslated"],
     accessibility: ["media.alt-missing", "media.video-description-missing"],

package/dist/copy.d.ts

@@ -24,6 +24,7 @@ export declare const COPY: {
         readonly duplicate: (titles: string[], more: number) => string;
         readonly linkMissing: (count: number) => string;
         readonly linkUnpublished: (target: string, count: number) => string;
+        readonly orphan: "No published page, header or footer links here. Link to it from the menu or a related page.";
         readonly problems: "Some checks could not run:";
     };
     readonly sv: {
@@ -44,15 +45,17 @@ export declare const COPY: {
         readonly duplicate: (titles: string[], more: number) => string;
         readonly linkMissing: (count: number) => string;
         readonly linkUnpublished: (target: string, count: number) => string;
+        readonly orphan: "Ingen publicerad sida, sidhuvud eller sidfot länkar hit. Länka hit från menyn eller en närliggande sida.";
         readonly problems: "Några kontroller kunde inte köras:";
     };
 };
 type Ask = (finding: Finding) => string;
 /**
  * The ready prompt behind "Fix with the assistant", written as the editor would ask. The document is
- * open in the finding's locale with the field selected, so the prompt does not name either.
+ * open in the finding's locale with the field selected, so the prompt does not name either. A check
+ * without one is fixed elsewhere: nothing on an unlinked page needs changing.
  */
-export declare const ASK: Record<UiLanguage, Record<CheckId, Ask>>;
+export declare const ASK: Record<UiLanguage, Partial<Record<CheckId, Ask>>>;
 type BatchAsk = (finding: Finding) => string;
 /**
  * The prompt behind "Fix N with the assistant", once for every document of a check. The assistant

package/dist/copy.js

@@ -17,6 +17,7 @@ export const CHECK_LABELS = {
         "content.heading-skip": "Skipped heading levels",
         "content.thin": "Thin content",
         "links.broken": "Broken internal links",
+        "links.orphan": "Nothing links here",
         "content.untranslated": "Not translated",
     },
     sv: {
@@ -34,6 +35,7 @@ export const CHECK_LABELS = {
         "content.heading-skip": "Överhoppade rubriknivåer",
         "content.thin": "Tunt innehåll",
         "links.broken": "Trasiga interna länkar",
+        "links.orphan": "Inget länkar hit",
         "content.untranslated": "Saknar översättning",
     },
 };
@@ -70,6 +72,7 @@ export const COPY = {
         duplicate: (titles, more) => `Also on ${list("en", titles)}${more ? ` and ${more} more` : ""}`,
         linkMissing: (count) => `Links to a deleted document${count > 1 ? `, and ${count - 1} more` : ""}`,
         linkUnpublished: (target, count) => `Links to “${target}”, not published${count > 1 ? `, and ${count - 1} more` : ""}`,
+        orphan: "No published page, header or footer links here. Link to it from the menu or a related page.",
         problems: "Some checks could not run:",
     },
     sv: {
@@ -90,12 +93,14 @@ export const COPY = {
         duplicate: (titles, more) => `Även på ${list("sv", titles)}${more ? ` och ${more} till` : ""}`,
         linkMissing: (count) => `Länkar till ett borttaget dokument${count > 1 ? `, och ${count - 1} till` : ""}`,
         linkUnpublished: (target, count) => `Länkar till ”${target}”, som inte är publicerad${count > 1 ? `, och ${count - 1} till` : ""}`,
+        orphan: "Ingen publicerad sida, sidhuvud eller sidfot länkar hit. Länka hit från menyn eller en närliggande sida.",
         problems: "Några kontroller kunde inte köras:",
     },
 };
 /**
  * The ready prompt behind "Fix with the assistant", written as the editor would ask. The document is
- * open in the finding's locale with the field selected, so the prompt does not name either.
+ * open in the finding's locale with the field selected, so the prompt does not name either. A check
+ * without one is fixed elsewhere: nothing on an unlinked page needs changing.
  */
 export const ASK = {
     en: {
@@ -291,6 +296,9 @@ export const LIST_COPY = {
 export function findingDetail(language, finding) {
     const copy = COPY[language];
     const { duplicate, heading, length, links, untranslated, words } = finding;
+    if (finding.check === "links.orphan") {
+        return copy.orphan;
+    }
     if (untranslated) {
         return copy.untranslated(untranslated.count);
     }

package/dist/fields.d.ts

@@ -56,3 +56,12 @@ export declare function contentSchema(field: FieldLike, resolveBlock: (slug: str
     schema: ContentSchema;
     localized: boolean;
 } | undefined;
+/**
+ * The fields of a whole document that can hold an internal link, such as a global's menu: rich text
+ * and relationships, in link groups and arrays too. `localized` is set when any of them is, so a
+ * label that is localized does not make the links be read once per locale.
+ */
+export declare function linkFields(fields: FieldLike[]): {
+    fields: TextField[];
+    localized: boolean;
+};

package/dist/fields.js

@@ -86,12 +86,27 @@ export function contentSchema(field, resolveBlock) {
     }
     return { schema: { kind: "blocks", blocks }, localized };
 }
-/** Collects the fields in config order; returns whether any of them is localized. */
-function collectTextFields(fields, prefix, out) {
+/**
+ * The fields of a whole document that can hold an internal link, such as a global's menu: rich text
+ * and relationships, in link groups and arrays too. `localized` is set when any of them is, so a
+ * label that is localized does not make the links be read once per locale.
+ */
+export function linkFields(fields) {
+    const found = [];
+    const localized = collectTextFields(fields, "", found, true);
+    return { fields: found, localized };
+}
+/**
+ * Collects the fields in config order; returns whether any of them is localized. `linksOnly`
+ * leaves out plain text.
+ */
+function collectTextFields(fields, prefix, out, linksOnly = false) {
     let localized = false;
     for (const field of fields) {
         const path = field.name ? `${prefix}${field.name}` : undefined;
         if (path && (field.type === "text" || field.type === "textarea")) {
+            if (linksOnly)
+                continue;
             out.push({ path, kind: "text" });
             localized ||= Boolean(field.localized);
         }
@@ -104,13 +119,13 @@ function collectTextFields(fields, prefix, out) {
             localized ||= Boolean(field.localized);
         }
         else if (field.type === "tabs") {
-            localized = collectTextFields(field.tabs ?? [], prefix, out) || localized;
+            localized = collectTextFields(field.tabs ?? [], prefix, out, linksOnly) || localized;
         }
         else if (field.fields && field.type !== "blocks") {
             // Groups, arrays and named tabs add a segment; rows, collapsibles and unnamed tabs do not.
             // A localized group or array localizes the text fields inside it.
             const before = out.length;
-            const nested = collectTextFields(field.fields, path ? `${path}.` : prefix, out);
+            const nested = collectTextFields(field.fields, path ? `${path}.` : prefix, out, linksOnly);
             localized ||= nested || (Boolean(field.localized) && out.length > before);
         }
     }

package/dist/links.d.ts

@@ -61,7 +61,10 @@ export declare function batchTarget(finding: Finding): string;
  * `targets` with `ask`. The check filter says how far each fix may reach.
  */
 export declare function batchURL(adminRoute: string, filters: ListFilters, targets: string[], ask: string): string;
-/** The document in the finding's locale with its field brought into view, and a prompt when given. */
+/**
+ * The document or global in the finding's locale with its field brought into view, and a prompt
+ * when given.
+ */
 export declare function editURL(adminRoute: string, finding: Finding, ask?: string): string;
 /**
  * The work list's filters. `category` picks the tab. `check` is only an entry point (an older link,

package/dist/links.js

@@ -110,18 +110,28 @@ export function batchURL(adminRoute, filters, targets, ask) {
     params.set(ASK_PARAM, ask);
     return `${formatAdminURL({ adminRoute, path: VIEW_PATH })}?${params}`;
 }
-/** The document in the finding's locale with its field brought into view, and a prompt when given. */
+/**
+ * The document or global in the finding's locale with its field brought into view, and a prompt
+ * when given.
+ */
 export function editURL(adminRoute, finding, ask) {
-    const path = `/collections/${finding.collection}/${encodeURIComponent(String(finding.id))}`;
+    const path = finding.global
+        ? `/globals/${finding.collection}`
+        : `/collections/${finding.collection}/${encodeURIComponent(String(finding.id))}`;
     const params = new URLSearchParams();
     if (finding.locale) {
         params.set("locale", finding.locale);
     }
-    params.set(FIELD_PARAM, finding.path);
+    if (finding.path) {
+        params.set(FIELD_PARAM, finding.path);
+    }
     if (ask) {
         params.set(ASK_PARAM, ask);
     }
-    return `${formatAdminURL({ adminRoute, path })}?${params}`;
+    const query = params.toString();
+    return query
+        ? `${formatAdminURL({ adminRoute, path })}?${query}`
+        : formatAdminURL({ adminRoute, path });
 }
 /** The work list, filtered. */
 export function listURL(adminRoute, filters = {}) {

package/dist/plugin.js

@@ -43,6 +43,7 @@ export function contentHealthPlugin(options) {
         return {
             ...config,
             collections: (config.collections ?? []).map((collection) => options.collections[collection.slug] ? withFieldBridge(collection) : collection),
+            globals: (config.globals ?? []).map((global) => options.globals?.[global.slug] ? withGlobalFieldBridge(global) : global),
             admin: {
                 ...config.admin,
                 components: {
@@ -98,3 +99,23 @@ function withFieldBridge(collection) {
         },
     };
 }
+/** The same for a global, whose edit view takes its components under `elements`. */
+function withGlobalFieldBridge(global) {
+    const elements = global.admin?.components?.elements;
+    return {
+        ...global,
+        admin: {
+            ...global.admin,
+            components: {
+                ...global.admin?.components,
+                elements: {
+                    ...elements,
+                    beforeDocumentControls: [
+                        ...(elements?.beforeDocumentControls ?? []),
+                        `${CLIENT_ENTRY}#ContentHealthFieldBridge`,
+                    ],
+                },
+            },
+        },
+    };
+}

package/dist/references.d.ts

@@ -1,4 +1,4 @@
-import type { ContentSchema } from "./fields.ts";
+import type { ContentSchema, TextField } from "./fields.ts";
 export type Reference = {
     /** Form path of the field holding the link, e.g. `layout.2.content` or `layout.1.link.reference`. */
     path: string;
@@ -6,3 +6,5 @@ export type Reference = {
     id: string | number;
 };
 export declare function readReferences(value: unknown, root: string, schema: ContentSchema): Reference[];
+/** Internal links in a whole document, such as a global, from the fields `linkFields` found. */
+export declare function readDocumentReferences(doc: unknown, fields: TextField[]): Reference[];

package/dist/references.js

@@ -1,6 +1,6 @@
 /**
- * Internal links in a page body: link nodes in rich text and relationship fields in blocks. Plain
- * functions over the body as the Local API returns it at depth 0, like `content.ts`.
+ * Internal links in a page body or a whole document: link nodes in rich text and relationship
+ * fields. Plain functions over values as the Local API returns them at depth 0, like `content.ts`.
  */
 import { fanOut } from "./content.js";
 /**
@@ -22,22 +22,31 @@ export function readReferences(value, root, schema) {
         if (typeof blockType !== "string") {
             continue;
         }
-        for (const field of schema.blocks[blockType] ?? []) {
-            if (field.kind === "text") {
-                continue;
+        readFields(block, schema.blocks[blockType] ?? [], `${root}.${index}`, references);
+    }
+    return references;
+}
+/** Internal links in a whole document, such as a global, from the fields `linkFields` found. */
+export function readDocumentReferences(doc, fields) {
+    const references = [];
+    readFields(doc, fields, "", references);
+    return references;
+}
+function readFields(container, fields, root, out) {
+    for (const field of fields) {
+        if (field.kind === "text") {
+            continue;
+        }
+        for (const { path, value, parent } of withParents(container, field.path)) {
+            const fullPath = join(root, path);
+            if (field.kind === "richText") {
+                readLexical(value, fullPath, out);
             }
-            for (const { path, value: fieldValue, parent } of withParents(block, field.path)) {
-                const fullPath = `${root}.${index}.${path}`;
-                if (field.kind === "richText") {
-                    readLexical(fieldValue, fullPath, references);
-                }
-                else if (field.kind === "relationship" && !isExternal(parent)) {
-                    references.push(...relationValues(fieldValue, field.relationTo, fullPath));
-                }
+            else if (field.kind === "relationship" && !isExternal(parent)) {
+                out.push(...relationValues(value, field.relationTo, fullPath));
             }
         }
     }
-    return references;
 }
 /** `fanOut` with the object each value sits in, so a link field's siblings can be read. */
 function withParents(block, path) {

package/dist/scan.js

@@ -1,8 +1,9 @@
-import { checkDocument, documentTitle, rulesFor } from "./checks.js";
-import { contentSchema, lookupPath, mergeSelect, } from "./fields.js";
-import { duplicateFindings, linkFindings, targetKey, } from "./site.js";
+import { checkDocument, documentTitle, rulesFor, valueAt } from "./checks.js";
+import { contentSchema, linkFields, lookupPath, mergeSelect, } from "./fields.js";
+import { readDocumentReferences, readReferences } from "./references.js";
+import { duplicateFindings, linkedKeys, linkFindings, orphanFindings, targetKey, } from "./site.js";
 import { checkTranslation } from "./translations.js";
-import { CHECK_IDS } from "./types.js";
+import { CHECK_IDS, } from "./types.js";
 /** Where the plugin keeps its options in the (server-only) `config.custom`. */
 export const CUSTOM_KEY = "contentHealth";
 export function contentHealthOptions(config) {
@@ -160,6 +161,52 @@ export async function scanContentHealth({ payload, user, checks }) {
     }
     result.findings.push(...duplicateFindings(unique));
     countChecked(result, unique.map((entry) => entry.base.check));
+    // A global's links, such as the menu, are followed with the collections'.
+    if (!checks?.length || checks.includes("links.broken")) {
+        for (const slug of linkGlobals(options)) {
+            const source = globalSource(payload, slug);
+            if (!source) {
+                result.problems.push(`Global "${slug}" does not exist.`);
+                continue;
+            }
+            ran.add("links.broken");
+            result.documents[slug] = 1;
+            for (const [index, locale] of locales.entries()) {
+                if (index > 0 && !source.localized) {
+                    break;
+                }
+                try {
+                    const doc = await payload.findGlobal({
+                        slug: slug,
+                        depth: 0,
+                        draft: source.drafts,
+                        fallbackLocale: false,
+                        ...(locale ? { locale: locale } : {}),
+                        overrideAccess: false,
+                        user,
+                    });
+                    const status = doc._status;
+                    links.push({
+                        base: {
+                            check: "links.broken",
+                            collection: slug,
+                            id: slug,
+                            global: true,
+                            title: source.title,
+                            path: "",
+                            ...(source.localized && locale ? { locale } : {}),
+                            ...(status === "draft" || status === "published" ? { status } : {}),
+                        },
+                        references: readDocumentReferences(doc, source.fields),
+                    });
+                }
+                catch (error) {
+                    result.problems.push(`${slug}: ${error instanceof Error ? error.message : String(error)}`);
+                    break;
+                }
+            }
+        }
+    }
     if (links.length) {
         try {
             const targets = await linkTargets(payload, links.flatMap((entry) => entry.references));
@@ -171,9 +218,168 @@ export async function scanContentHealth({ payload, user, checks }) {
             result.problems.push(`links: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    const orphans = Object.entries(options.collections).filter(([, own]) => own.orphans);
+    if (orphans.length && (!checks?.length || checks.includes("links.orphan"))) {
+        ran.add("links.orphan");
+        try {
+            const linked = linkedKeys(await publishedLinks({ payload, user, options, locales, resolveBlock }));
+            for (const [slug, own] of orphans) {
+                const candidates = await orphanCandidates(payload, user, slug, own.orphans);
+                const followed = orphanFindings(candidates, linked);
+                result.findings.push(...followed.findings);
+                countChecked(result, followed.checked);
+            }
+        }
+        catch (error) {
+            result.problems.push(`orphans: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
     result.checks = CHECK_IDS.filter((check) => ran.has(check));
     return result;
 }
+/** Globals whose links content health reads. */
+function linkGlobals(options) {
+    return Object.entries(options.globals ?? {})
+        .filter(([, own]) => own.links)
+        .map(([slug]) => slug);
+}
+/** A global's link fields, its name in Admin and whether it has drafts; undefined if missing. */
+function globalSource(payload, slug) {
+    const global = payload.config.globals.find((entry) => entry.slug === slug);
+    if (!global) {
+        return undefined;
+    }
+    return {
+        ...linkFields(global.fields),
+        drafts: Boolean(global.versions && global.versions.drafts),
+        title: labelText(global.label) ?? slug,
+    };
+}
+/** A config label as one string: English when it has several. Functions are left out. */
+function labelText(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (value && typeof value === "object") {
+        const labels = value;
+        const text = labels.en ?? Object.values(labels)[0];
+        return typeof text === "string" ? text : undefined;
+    }
+    return undefined;
+}
+const PUBLISHED = { _status: { equals: "published" } };
+/**
+ * The links a reader can follow today: the published version of every collection body content
+ * health reads and every global with `links` as the site reads it (`draft: false`), in every
+ * language.
+ */
+async function publishedLinks(input) {
+    const { payload, user, options, locales, resolveBlock } = input;
+    const sources = [];
+    for (const [slug, own] of Object.entries(options.collections)) {
+        const collection = payload.config.collections.find((entry) => entry.slug === slug);
+        const field = own.content?.field;
+        const info = collection && field && lookupPath(collection.fields, field);
+        const body = info && contentSchema(info.field, resolveBlock);
+        if (!field || !info || !body) {
+            continue;
+        }
+        const drafts = Boolean(collection.versions && collection.versions.drafts);
+        const localized = Boolean(payload.config.localization) && (info.localized || body.localized);
+        for (const [index, locale] of locales.entries()) {
+            if (index > 0 && !localized) {
+                break;
+            }
+            const { docs } = await payload.find({
+                collection: slug,
+                depth: 0,
+                draft: false,
+                fallbackLocale: false,
+                ...(locale ? { locale: locale } : {}),
+                overrideAccess: false,
+                pagination: false,
+                select: info.select,
+                user,
+                ...(drafts ? { where: PUBLISHED } : {}),
+            });
+            for (const doc of docs) {
+                sources.push({
+                    collection: slug,
+                    id: doc.id,
+                    references: readReferences(valueAt(doc, field), field, body.schema),
+                });
+            }
+        }
+    }
+    for (const slug of linkGlobals(options)) {
+        const source = globalSource(payload, slug);
+        if (!source) {
+            continue;
+        }
+        for (const [index, locale] of locales.entries()) {
+            if (index > 0 && !source.localized) {
+                break;
+            }
+            const doc = (await payload.findGlobal({
+                slug: slug,
+                depth: 0,
+                draft: false,
+                fallbackLocale: false,
+                ...(locale ? { locale: locale } : {}),
+                overrideAccess: false,
+                user,
+            }));
+            // No status check: a global saved as a draft but never published still has `_status: "draft"`,
+            // and Payload returns it here, so the site shows its links.
+            sources.push({
+                collection: slug,
+                id: slug,
+                references: readDocumentReferences(doc, source.fields),
+            });
+        }
+    }
+    return sources;
+}
+/** A collection's published documents, less the excluded ones, as `links.orphan` findings to be. */
+async function orphanCandidates(payload, user, slug, orphans) {
+    const collection = payload.config.collections.find((entry) => entry.slug === slug);
+    if (!collection) {
+        return [];
+    }
+    const drafts = Boolean(collection.versions && collection.versions.drafts);
+    const useAsTitle = collection.admin?.useAsTitle;
+    const select = {};
+    if (useAsTitle && useAsTitle !== "id")
+        mergeSelect(select, { [useAsTitle]: true });
+    if (collection.upload)
+        mergeSelect(select, { filename: true });
+    const read = (where) => payload.find({
+        collection: slug,
+        depth: 0,
+        draft: false,
+        overrideAccess: false,
+        pagination: false,
+        select: select,
+        user,
+        ...(where ? { where } : {}),
+    });
+    const published = drafts ? PUBLISHED : undefined;
+    const exclude = typeof orphans === "object" ? orphans.exclude : undefined;
+    const excluded = exclude
+        ? new Set((await read(published ? { and: [published, exclude] } : exclude)).docs.map((doc) => String(doc.id)))
+        : new Set();
+    const { docs } = await read(published);
+    return docs
+        .filter((doc) => !excluded.has(String(doc.id)))
+        .map((doc) => ({
+        check: "links.orphan",
+        collection: slug,
+        id: doc.id,
+        title: documentTitle(doc, useAsTitle),
+        path: "",
+        ...(drafts ? { status: "published" } : {}),
+    }));
+}
 function countChecked(result, checked) {
     for (const check of checked) {
         result.checked[check] = (result.checked[check] ?? 0) + 1;

package/dist/site.d.ts

@@ -33,3 +33,16 @@ export declare function linkFindings(entries: LinksEntry[], targets: Map<string,
     findings: Finding[];
     checked: CheckId[];
 };
+/** The links of one published document, page or global, as a reader can follow them. */
+export type LinkSource = {
+    collection: string;
+    id: string | number;
+    references: Reference[];
+};
+/** Every document some other published document links to, by `targetKey`. */
+export declare function linkedKeys(sources: LinkSource[]): Set<string>;
+/** The published documents nothing links to; every candidate counts as checked. */
+export declare function orphanFindings(candidates: Finding[], linked: Set<string>): {
+    findings: Finding[];
+    checked: CheckId[];
+};

package/dist/site.js

@@ -65,3 +65,22 @@ export function linkFindings(entries, targets) {
     }
     return { findings, checked };
 }
+/** Every document some other published document links to, by `targetKey`. */
+export function linkedKeys(sources) {
+    const linked = new Set();
+    for (const source of sources) {
+        for (const { relationTo, id } of source.references) {
+            if (relationTo === source.collection && String(id) === String(source.id))
+                continue;
+            linked.add(targetKey(relationTo, id));
+        }
+    }
+    return linked;
+}
+/** The published documents nothing links to; every candidate counts as checked. */
+export function orphanFindings(candidates, linked) {
+    return {
+        findings: candidates.filter((candidate) => !linked.has(targetKey(candidate.collection, candidate.id))),
+        checked: candidates.map((candidate) => candidate.check),
+    };
+}

package/dist/types.d.ts

@@ -1,17 +1,23 @@
-export declare const CHECK_IDS: readonly ["media.alt-missing", "media.video-description-missing", "seo.title-missing", "seo.title-length", "seo.title-duplicate", "seo.description-missing", "seo.description-length", "seo.description-duplicate", "seo.image-missing", "content.h1-missing", "content.h1-multiple", "content.heading-skip", "content.thin", "links.broken", "content.untranslated"];
+import type { Where } from "payload";
+export declare const CHECK_IDS: readonly ["media.alt-missing", "media.video-description-missing", "seo.title-missing", "seo.title-length", "seo.title-duplicate", "seo.description-missing", "seo.description-length", "seo.description-duplicate", "seo.image-missing", "content.h1-missing", "content.h1-multiple", "content.heading-skip", "content.thin", "links.broken", "links.orphan", "content.untranslated"];
 export type CheckId = (typeof CHECK_IDS)[number];
 export type LengthRange = {
     min: number;
     max: number;
 };
-/** One problem in one field of one document, in one locale when the field is localized. */
+/**
+ * One problem in one field of one document, in one locale when the field is localized. A global's
+ * finding has `global` set and the global's slug as both `collection` and `id`.
+ */
 export type Finding = {
     check: CheckId;
     collection: string;
     id: string | number;
+    /** Set when the document is a global, such as a header. */
+    global?: true;
     /** The document's title (`useAsTitle`), falling back to the filename and then the id. */
     title: string;
-    /** Dot path of the field in the document, e.g. `meta.description`. */
+    /** Dot path of the field in the document, e.g. `meta.description`; empty for the whole document. */
     path: string;
     /** Set when the field is localized. */
     locale?: string;
@@ -115,10 +121,29 @@ export type CollectionHealthOptions = {
      * default one. One finding per document and language. Needs Payload's `localization`.
      */
     translations?: boolean;
+    /**
+     * Published documents that no published page or global links to (`links.orphan`). Links are read
+     * where content health reads them: the `content` field of each collection and the `globals` with
+     * `links`. `exclude` leaves out documents matching a Payload query, such as the start page:
+     * `{ slug: { equals: "home" } }`. Off by default.
+     */
+    orphans?: boolean | {
+        exclude?: Where;
+    };
+};
+export type GlobalHealthOptions = {
+    /**
+     * Internal links anywhere in the global (link groups, relationships, rich text) to documents that
+     * are deleted or not published, as `links.broken`. Also makes the global a link source for
+     * `orphans`.
+     */
+    links?: boolean;
 };
 export type ContentHealthPluginOptions = {
     /** Collection slugs and the checks to run on each. */
     collections: Record<string, CollectionHealthOptions>;
+    /** Global slugs and the checks to run on each, such as a header's menu links. */
+    globals?: Record<string, GlobalHealthOptions>;
     disabled?: boolean;
     /**
      * Put the widget on the default dashboard, below the collection cards, when the project sets no

package/dist/types.js

@@ -13,5 +13,6 @@ export const CHECK_IDS = [
     "content.heading-skip",
     "content.thin",
     "links.broken",
+    "links.orphan",
     "content.untranslated",
 ];

package/dist/view/ContentHealthView.js

@@ -40,6 +40,7 @@ export async function ContentHealthView({ initPageResult, params, searchParams,
     const batchAsk = {};
     const rows = sortFindings(result.findings).map((finding, index) => {
         const detail = findingDetail(language, finding);
+        const ask = ASK[language][finding.check];
         const batchable = Boolean(BATCH_CHECKS[finding.check]) && inBatches.has(finding.collection);
         if (batchable && !batchAsk[finding.check]) {
             batchAsk[finding.check] = BATCH_ASK[language][finding.check]?.(finding);
@@ -54,8 +55,8 @@ export async function ContentHealthView({ initPageResult, params, searchParams,
             href: editURL(adminRoute, finding),
             ...(finding.locale ? { locale: finding.locale } : {}),
             ...(detail ? { detail } : {}),
-            ...(withAssistant.has(finding.collection)
-                ? { askHref: editURL(adminRoute, finding, ASK[language][finding.check](finding)) }
+            ...(ask && !finding.global && withAssistant.has(finding.collection)
+                ? { askHref: editURL(adminRoute, finding, ask(finding)) }
                 : {}),
             ...(batchable ? { batchTarget: batchTarget(finding) } : {}),
         };
@@ -82,7 +83,8 @@ export async function ContentHealthView({ initPageResult, params, searchParams,
     const failing = stats.reduce((sum, stat) => sum + stat.failing, 0);
     const collections = Object.keys(result.documents).map((slug) => ({
         value: slug,
-        label: label(config.collections.find((collection) => collection.slug === slug)?.labels?.plural, language) ?? slug,
+        label: label(config.collections.find((collection) => collection.slug === slug)?.labels?.plural ??
+            config.globals.find((global) => global.slug === slug)?.label, language) ?? slug,
     }));
     const locales = config.localization
         ? config.localization.locales.map((locale) => ({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simmalugnt-se/payload-content-health",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Content health checks and dashboard widgets for Payload Admin: alt texts, SEO fields and more",
   "keywords": [
     "payload",