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

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.9.0
+
+- New check `media.video-description-missing` (Accessibility), turned on per collection with
+  `videoDescription`: a video without a description, its text alternative, in a language. Reads
+  `description` by default, as in `@simmalugnt-se/payload-mux`.
+
+## 0.8.0
+
+- The editor assistant (0.15.0 or later, with `extensions: { "content-health": true }`) reads the
+  findings itself: `content-health.findings` and `content-health.open`. Editors can ask what to fix
+  first or what is wrong with a page, and be taken to the work list or a batch.
+
 ## 0.7.1
 
 - npm links to simmalugnt.se instead of the private source repository.

package/README.md

@@ -22,11 +22,12 @@ Requires Payload `>=3.90.2 <4`, Next 16 and React 19. The widget uses Payload's
    import { contentHealthPlugin } from "@simmalugnt-se/payload-content-health";
 
    plugins: [
-     seoPlugin({ collections: ["pages"], uploadsCollection: "media" }),
+     seoPlugin({ collections: ["pages"], uploadsCollection: "images" }),
      contentHealthPlugin({
        collections: {
          pages: { seo: true },
-         media: { altText: true },
+         images: { altText: true },
+         videos: { videoDescription: true },
        },
      }),
    ];
@@ -41,6 +42,7 @@ Requires Payload `>=3.90.2 <4`, Next 16 and React 19. The widget uses Payload's
 | Check                       | Option             | Finds                                          |
 | --------------------------- | ------------------ | ---------------------------------------------- |
 | `media.alt-missing`         | `altText`          | Images (`image/*`) with an empty alt field     |
+| `media.video-description-missing` | `videoDescription` | Videos with an empty description (`description`, as in `@simmalugnt-se/payload-mux`) |
 | `seo.title-missing`         | `seo`              | Empty meta title                               |
 | `seo.title-length`          | `seo`              | Meta title outside 50–60 characters            |
 | `seo.title-duplicate`       | `seo`              | Meta title another document also uses          |
@@ -71,7 +73,7 @@ pages: {
     duplicates: false,
   },
 },
-media: { altText: { field: "altText" } },
+images: { altText: { field: "altText" } },
 ```
 
 ### Page body
@@ -167,6 +169,13 @@ other; they share these names:
 | `config.admin.custom.editorAssistant`        | assistant → this plugin | `{ collections, batchCollections }`      |
 | `?batch=…&batchScope=…&ask=…`                | link → assistant        | Documents to fix at once, and the prompt |
 
+With the assistant's `extensions: { "content-health": true }` (editor-assistant 0.15.0 or later),
+the assistant also reads the findings itself, through the extension this plugin registers in
+`config.custom.editorAssistantExtensions`: `content-health.findings` (a summary per category, then
+findings filtered by category, check, collection, document or locale, at most 30) and
+`content-health.open` (the work list, or the batch for one check). Editors can ask "what should I
+fix first?" on the dashboard or "what is wrong with this page?" on a document.
+
 Both parameters are removed from the address once read. `editURL(adminRoute, finding, prompt?)` and
 `listURL(adminRoute, filters)` build these links.
 

package/dist/assistant.d.ts

@@ -0,0 +1,56 @@
+import type { PayloadRequest } from "payload";
+import { type ScanResult, scanContentHealth } from "./scan.ts";
+/**
+ * How content health gives `@simmalugnt-se/payload-editor-assistant` its findings, without an
+ * import: an extension in `config.custom[EXTENSIONS_CUSTOM_KEY]`, which the assistant uses once the
+ * host turns it on (`extensions: { "content-health": true }`). The key and types are copies of the
+ * assistant's (`extensions/contract.ts`); the assistant's contract tests compare them.
+ */
+export declare const EXTENSIONS_CUSTOM_KEY = "editorAssistantExtensions";
+export type AssistantExtension = {
+    id: string;
+    instructions?: string;
+    views?: Array<{
+        path: string;
+        description: string;
+    }>;
+    tools?: AssistantExtensionTool[];
+};
+export type AssistantExtensionTool = {
+    name: string;
+    description: string;
+    input: Record<string, unknown>;
+    risk: "auto";
+    run: (input: Record<string, unknown>, context: AssistantExtensionContext) => Promise<AssistantExtensionResult>;
+};
+export type AssistantExtensionContext = {
+    req: PayloadRequest;
+    path?: string;
+    open?: {
+        collection?: string;
+        global?: string;
+        id?: string | number;
+        locale: string;
+    };
+};
+export type AssistantExtensionResult = {
+    ok: true;
+    data: unknown;
+    navigate?: {
+        href: string;
+        label: string;
+    };
+} | {
+    ok: false;
+    error: string;
+    message: string;
+};
+export declare const EXTENSION_ID = "content-health";
+/** Findings one call returns at most; `more` says how many the filters left out. */
+export declare const MAX_FINDINGS = 30;
+type Scan = (args: Parameters<typeof scanContentHealth>[0]) => Promise<ScanResult>;
+/** `scan` is replaceable for tests. */
+export declare function assistantExtension({ scan: run, }?: {
+    scan?: Scan;
+}): AssistantExtension;
+export {};

package/dist/assistant.js

@@ -0,0 +1,204 @@
+import { CATEGORY_IDS, categoryOf, categoryStats } from "./categories.js";
+import { 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";
+import { CHECK_IDS } from "./types.js";
+/**
+ * How content health gives `@simmalugnt-se/payload-editor-assistant` its findings, without an
+ * import: an extension in `config.custom[EXTENSIONS_CUSTOM_KEY]`, which the assistant uses once the
+ * host turns it on (`extensions: { "content-health": true }`). The key and types are copies of the
+ * assistant's (`extensions/contract.ts`); the assistant's contract tests compare them.
+ */
+export const EXTENSIONS_CUSTOM_KEY = "editorAssistantExtensions";
+export const EXTENSION_ID = "content-health";
+/** Findings one call returns at most; `more` says how many the filters left out. */
+export const MAX_FINDINGS = 30;
+const DEFAULT_FINDINGS = 20;
+/** One scan per turn: the turn's tool calls share the editor's request. */
+function scanOncePerRequest(run) {
+    const scans = new WeakMap();
+    return (req) => {
+        let pending = scans.get(req);
+        if (!pending) {
+            pending = run({ payload: req.payload, user: req.user ?? null });
+            scans.set(req, pending);
+        }
+        return pending;
+    };
+}
+const filterInput = {
+    category: {
+        type: "string",
+        enum: [...CATEGORY_IDS],
+        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." },
+    locale: { type: "string", description: "Only findings in this content language." },
+};
+/** `scan` is replaceable for tests. */
+export function assistantExtension({ scan: run = scanContentHealth, } = {}) {
+    const scan = scanOncePerRequest(run);
+    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).",
+            "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(" "),
+        views: [
+            {
+                path: VIEW_PATH,
+                description: "The editor is on the content health work list: issues by category and check, each with a link to the document, and buttons to fix one with the assistant or several at once.",
+            },
+            {
+                path: "/",
+                description: "The dashboard shows a content health widget: the share of checked fields in order, per category.",
+            },
+        ],
+        tools: [
+            {
+                name: `${EXTENSION_ID}.findings`,
+                description: `Content health's findings: first a summary per category (issues, fields checked, documents needing attention), then the findings that match the filters, at most ${MAX_FINDINGS}, each with the document, the problem, the field, the language and how to fix it. Without filters and with a document open: that document's findings; on other views: the whole site's. Read with the editor's access.`,
+                input: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: {
+                        ...filterInput,
+                        documentId: {
+                            type: ["string", "number"],
+                            description: "Only this document (with collection).",
+                        },
+                        site: {
+                            type: "boolean",
+                            description: "The whole site even when a document is open.",
+                        },
+                        limit: { type: "integer", minimum: 1, maximum: MAX_FINDINGS },
+                    },
+                },
+                risk: "auto",
+                run: async (input, context) => findings(input, context, await scan(context.req)),
+            },
+            {
+                name: `${EXTENSION_ID}.open`,
+                description: `Takes the editor to the content health work list, filtered, or with batch true to the batch that fixes up to ${MAX_BATCH_TARGETS} documents of one check at once (the editor starts it and reviews each). Needs check for a batch.`,
+                input: {
+                    type: "object",
+                    additionalProperties: false,
+                    properties: { ...filterInput, batch: { type: "boolean" } },
+                },
+                risk: "auto",
+                run: async (input, context) => open(input, context, () => scan(context.req)),
+            },
+        ],
+    };
+}
+async function findings(input, { req, open }, result) {
+    const custom = req.payload.config.admin?.custom;
+    const withAssistant = new Set(assistantCollections(custom));
+    const inBatches = new Set(batchCollections(custom));
+    const filters = readInput(input);
+    const filtered = Boolean(filters.category || filters.check || filters.collection || input.documentId || input.site);
+    // With a document open and nothing asked for, its own findings.
+    const document = input.documentId !== undefined
+        ? { collection: filters.collection, id: String(input.documentId) }
+        : !filtered && open?.collection && open.id !== undefined
+            ? { collection: open.collection, id: String(open.id) }
+            : undefined;
+    const matching = sortFindings(result.findings).filter((finding) => matchesFilters(finding, filters) &&
+        (!document ||
+            ((!document.collection || finding.collection === document.collection) &&
+                String(finding.id) === document.id)));
+    const limit = typeof input.limit === "number" ? input.limit : DEFAULT_FINDINGS;
+    const stats = checkStats(result.checks, result.checked, result.findings);
+    const documents = Object.values(result.documents).reduce((sum, count) => sum + count, 0);
+    return {
+        ok: true,
+        data: {
+            summary: {
+                documentsChecked: documents,
+                documentsNeedingAttention: countDocuments(result.findings),
+                categories: categoryStats(stats).map((stat) => ({
+                    category: stat.category,
+                    label: CATEGORY_LABELS.en[stat.category],
+                    issues: stat.failing,
+                    fieldsChecked: stat.checked,
+                })),
+            },
+            scope: document ? "one document" : filtered ? "filtered" : "whole site",
+            findings: matching.slice(0, limit).map((finding) => ({
+                check: finding.check,
+                problem: CHECK_LABELS.en[finding.check],
+                detail: findingDetail("en", finding),
+                collection: finding.collection,
+                id: finding.id,
+                title: finding.title,
+                field: finding.path,
+                ...(finding.locale ? { locale: finding.locale } : {}),
+                ...(finding.status === "draft" ? { draft: true } : {}),
+                fix: fixFor(finding, inBatches, withAssistant),
+            })),
+            more: Math.max(0, matching.length - limit),
+            ...(result.problems.length ? { notChecked: result.problems } : {}),
+        },
+    };
+}
+async function open(input, { req }, scan) {
+    const filters = readInput(input);
+    const adminRoute = req.payload.config.routes.admin;
+    if (input.batch !== true) {
+        const category = filters.category ?? (filters.check ? categoryOf(filters.check) : undefined);
+        return {
+            ok: true,
+            data: { link: "work list" },
+            navigate: {
+                href: listURL(adminRoute, { ...filters, category, check: undefined }),
+                label: "Content health",
+            },
+        };
+    }
+    const check = filters.check;
+    if (!check || !BATCH_CHECKS[check]) {
+        return {
+            ok: false,
+            error: "not_batchable",
+            message: "Only some checks can be fixed in a batch: name one whose findings say batch.",
+        };
+    }
+    const inBatches = new Set(batchCollections(req.payload.config.admin?.custom));
+    const targets = sortFindings((await scan()).findings).filter((finding) => matchesFilters(finding, filters) && inBatches.has(finding.collection));
+    if (!targets.length) {
+        return { ok: false, error: "nothing_to_fix", message: "No findings of that check to fix." };
+    }
+    const language = uiLanguage(req.i18n?.language);
+    const ask = BATCH_ASK[language][check]?.(targets[0]) ?? "";
+    const count = Math.min(targets.length, MAX_BATCH_TARGETS);
+    return {
+        ok: true,
+        data: { documents: count, more: targets.length - count },
+        navigate: {
+            href: batchURL(adminRoute, { ...filters, check }, targets.map(batchTarget), ask),
+            label: language === "sv" ? `Åtgärda ${count} med assistenten` : `Fix ${count} with the assistant`,
+        },
+    };
+}
+/** How a finding is fixed: many at once, on its document with the assistant, or by hand. */
+function fixFor(finding, inBatches, withAssistant) {
+    if (BATCH_CHECKS[finding.check] && inBatches.has(finding.collection))
+        return "batch";
+    return withAssistant.has(finding.collection) ? "assistant" : "by hand";
+}
+function readInput(input) {
+    const text = (value) => (typeof value === "string" && value ? value : undefined);
+    const category = text(input.category);
+    const check = text(input.check);
+    return {
+        ...(category && CATEGORY_IDS.includes(category)
+            ? { category: category }
+            : {}),
+        ...(check && CHECK_IDS.includes(check) ? { check: check } : {}),
+        ...(text(input.collection) ? { collection: text(input.collection) } : {}),
+        ...(text(input.locale) ? { locale: text(input.locale) } : {}),
+    };
+}

package/dist/categories.js

@@ -18,7 +18,7 @@ export const CATEGORY_CHECKS = {
         "links.broken",
     ],
     translations: ["content.untranslated"],
-    accessibility: ["media.alt-missing"],
+    accessibility: ["media.alt-missing", "media.video-description-missing"],
 };
 export function categoryOf(check) {
     return CATEGORY_IDS.find((id) => CATEGORY_CHECKS[id].includes(check));

package/dist/checks.js

@@ -18,6 +18,11 @@ export function rulesFor(options) {
         const field = (options.altText === true ? undefined : options.altText.field) ?? "alt";
         rules.push({ check: "media.alt-missing", kind: "required", path: field, imagesOnly: true });
     }
+    if (options.videoDescription) {
+        const field = (options.videoDescription === true ? undefined : options.videoDescription.field) ??
+            "description";
+        rules.push({ check: "media.video-description-missing", kind: "required", path: field });
+    }
     if (options.seo) {
         const seo = options.seo === true ? {} : options.seo;
         const title = seo.title ?? SEO_DEFAULTS.title;

package/dist/copy.js

@@ -4,6 +4,7 @@ export function uiLanguage(adminLanguage) {
 export const CHECK_LABELS = {
     en: {
         "media.alt-missing": "Missing alt text",
+        "media.video-description-missing": "Missing video description",
         "seo.title-missing": "Missing meta title",
         "seo.title-length": "Meta title length",
         "seo.title-duplicate": "Duplicate meta title",
@@ -20,6 +21,7 @@ export const CHECK_LABELS = {
     },
     sv: {
         "media.alt-missing": "Alt-text saknas",
+        "media.video-description-missing": "Videobeskrivning saknas",
         "seo.title-missing": "Metatitel saknas",
         "seo.title-length": "Metatitelns längd",
         "seo.title-duplicate": "Dubblerad metatitel",
@@ -98,6 +100,7 @@ export const COPY = {
 export const ASK = {
     en: {
         "media.alt-missing": () => "Write an alt text for this image.",
+        "media.video-description-missing": () => "Write a description of this video for readers who cannot see it.",
         "seo.title-missing": ({ range }) => range
             ? `Write a meta title for this page, ${range.min}–${range.max} characters.`
             : "Write a meta title for this page.",
@@ -130,6 +133,7 @@ export const ASK = {
     },
     sv: {
         "media.alt-missing": () => "Skriv en alt-text för den här bilden.",
+        "media.video-description-missing": () => "Skriv en beskrivning av den här videon för den som inte kan se den.",
         "seo.title-missing": ({ range }) => range
             ? `Skriv en metatitel för den här sidan, ${range.min}–${range.max} tecken.`
             : "Skriv en metatitel för den här sidan.",

package/dist/group.d.ts

@@ -25,3 +25,5 @@ export type CheckStats = {
 };
 /** Per check that ran: how many values it looked at and which ones need work. */
 export declare function checkStats(checks: CheckId[], checked: Partial<Record<CheckId, number>>, findings: Finding[]): CheckStats[];
+/** By check, then document, then locale, so a document's locales sit together. */
+export declare function sortFindings(findings: Finding[]): Finding[];

package/dist/group.js

@@ -36,3 +36,12 @@ export function checkStats(checks, checked, findings) {
         return { check, checked: checked[check] ?? 0, failing, documents };
     });
 }
+/** By check, then document, then locale, so a document's locales sit together. */
+export function sortFindings(findings) {
+    return [...findings].sort((a, b) => CHECK_IDS.indexOf(a.check) - CHECK_IDS.indexOf(b.check) ||
+        a.collection.localeCompare(b.collection) ||
+        a.title.localeCompare(b.title) ||
+        String(a.id).localeCompare(String(b.id)) ||
+        a.path.localeCompare(b.path) ||
+        (a.locale ?? "").localeCompare(b.locale ?? ""));
+}

package/dist/plugin.js

@@ -1,3 +1,4 @@
+import { assistantExtension, EXTENSIONS_CUSTOM_KEY } from "./assistant.js";
 import { CHECK_LABELS } from "./copy.js";
 import { VIEW_PATH } from "./links.js";
 import { CLIENT_ENTRY, RSC_ENTRY } from "./package-name.js";
@@ -65,7 +66,15 @@ export function contentHealthPlugin(options) {
                     ...(defaultLayout ? { defaultLayout } : {}),
                 },
             },
-            custom: { ...config.custom, [CUSTOM_KEY]: options },
+            custom: {
+                ...config.custom,
+                [CUSTOM_KEY]: options,
+                // Used by the editor assistant once the host turns it on; harmless without it.
+                [EXTENSIONS_CUSTOM_KEY]: [
+                    ...(config.custom?.[EXTENSIONS_CUSTOM_KEY] ?? []),
+                    assistantExtension(),
+                ],
+            },
         };
     };
 }

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-export declare const CHECK_IDS: readonly ["media.alt-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"];
+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"];
 export type CheckId = (typeof CHECK_IDS)[number];
 export type LengthRange = {
     min: number;
@@ -94,11 +94,20 @@ export type AltTextOptions = {
     /** Field holding the alt text. Default `alt`. */
     field?: string;
 };
+export type VideoDescriptionOptions = {
+    /** Field holding the description. Default `description`, as in `@simmalugnt-se/payload-mux`. */
+    field?: string;
+};
 export type CollectionHealthOptions = {
     /** SEO checks on the fields `@payloadcms/plugin-seo` adds, or the paths given here. */
     seo?: boolean | SeoOptions;
     /** Alt text on images in an upload collection. Files that are not images are skipped. */
     altText?: boolean | AltTextOptions;
+    /**
+     * A description on every video, its text alternative for readers who cannot see it, as an alt
+     * text is for an image. For a videos collection such as `@simmalugnt-se/payload-mux`'s.
+     */
+    videoDescription?: boolean | VideoDescriptionOptions;
     /** Heading structure and thin content, read from the page body. */
     content?: ContentOptions;
     /**

package/dist/types.js

@@ -1,5 +1,6 @@
 export const CHECK_IDS = [
     "media.alt-missing",
+    "media.video-description-missing",
     "seo.title-missing",
     "seo.title-length",
     "seo.title-duplicate",

package/dist/view/ContentHealthView.js

@@ -4,10 +4,10 @@ import { Gutter, SetStepNav } from "@payloadcms/ui";
 import { redirect } from "next/navigation";
 import { categoryOf, categoryStats, categoryTone, defaultCategory, } from "../categories.js";
 import { ASK, BATCH_ASK, CATEGORY_LABELS, CHECK_LABELS, COPY, findingDetail, LIST_COPY, uiLanguage, } from "../copy.js";
-import { checkStats, countDocuments } from "../group.js";
+import { checkStats, countDocuments, sortFindings } from "../group.js";
 import { accessRedirect, assistantCollections, BATCH_CHECKS, batchCollections, batchTarget, editURL, readFilters, } from "../links.js";
 import { scanContentHealth } from "../scan.js";
-import { CHECK_IDS } from "../types.js";
+import {} from "../types.js";
 import { Ring } from "../widget/Ring.js";
 import { WorkList, } from "./WorkList.js";
 import "../styles/tokens.css";
@@ -95,15 +95,6 @@ export async function ContentHealthView({ initPageResult, params, searchParams,
                                         ? copy.summary(result.findings.length, countDocuments(result.findings))
                                         : copy.none })] })] }), _jsx(WorkList, { adminRoute: adminRoute, batchAsk: batchAsk, categories: categories, collections: collections, initialFilters: initialFilters, language: language, locales: locales, rows: rows }), result.problems.length ? (_jsx("ul", { className: "content-health-list__problems", children: result.problems.map((problem) => (_jsx("li", { children: problem }, problem))) })) : null] }) }));
 }
-/** By check, then document, then locale, so a document's locales sit together. */
-function sortFindings(findings) {
-    return [...findings].sort((a, b) => CHECK_IDS.indexOf(a.check) - CHECK_IDS.indexOf(b.check) ||
-        a.collection.localeCompare(b.collection) ||
-        a.title.localeCompare(b.title) ||
-        String(a.id).localeCompare(String(b.id)) ||
-        a.path.localeCompare(b.path) ||
-        (a.locale ?? "").localeCompare(b.locale ?? ""));
-}
 /** A config label: a string, or one per language. Functions are left to Payload. */
 function label(value, language) {
     if (typeof value === "string") {

package/package.json

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