@webround/editor 0.0.0-stage → 0.3.0

package/dist/check/rules.js

@@ -0,0 +1,517 @@
+import { CHECK_SITE, issueKey, walk } from './types.js';
+import { wrJsonLdProblems, wrSiteUrlOf } from '@webround/core/seo';
+import { leadsSomewhere } from './links.js';
+import { ARIA_ATTRIBUTES, FOCUSABLE_TAGS, GENERIC_LINK_TEXTS, GENERIC_TAGS, REQUIRED_BY_ROLE, expectedAutocomplete, isKnownRole, isValidAutocomplete, normalizedLinkText } from './aria.js';
+const HEADING = /^h([1-6])$/;
+function everyNode(page) {
+    const all = [];
+    walk(page.nodes, n => all.push(n));
+    return all;
+}
+/** Two elements on different sides of the same condition (`c ? a : b`) are never shown together. */
+function exclusive(a, b) {
+    return (a.branch ?? []).some(x => (b.branch ?? []).some(y => x.key === y.key && x.side !== y.side));
+}
+/** Tailwind classes that take the focus outline away (for every state, or on focus), and ones that show the focus some other way. */
+const FOCUS_OUTLINE_REMOVED = /^(?:(?:focus|focus-visible|focus-within):)?(?:outline-none|outline-hidden|outline-0)$/;
+const FOCUS_STYLED = /^(?:[\w-]+:)*(?:focus|focus-visible):(?!outline-none$|outline-hidden$|outline-0$)\S+$/;
+/** Search results show about this much of a title and of a description; the rest is cut. */
+const TITLE_MAX = 60;
+const DESCRIPTION_MAX = 160;
+/** The same rule for title and description: missing in the language the page is read in (the default language's text would be shown instead), or too long. */
+function seoTextRule(field, max) {
+    return {
+        name: `seo-${field}`,
+        severity: 'warning',
+        run(page, report) {
+            const seo = page.seo;
+            // A family of pages (`blog/[slug]`) has one JSON for all: a title or description there would be the same for every one, so none is expected
+            if (!seo || seo.noindex || seo.family)
+                return;
+            const lang = page.lang ?? 'default';
+            const text = seo[field][lang]?.trim();
+            const fix = { kind: 'seo-page', field, lang };
+            if (!text)
+                report(null, `The page has no SEO ${field}.`, fix);
+            else if (text.length > max)
+                report(null, `The SEO ${field} is ${text.length} characters: search results cut it after about ${max}.`, fix);
+        },
+    };
+}
+export const RULES = [
+    seoTextRule('title', TITLE_MAX),
+    seoTextRule('description', DESCRIPTION_MAX),
+    {
+        name: 'syntax-error',
+        severity: 'error',
+        run(page, report) {
+            for (const problem of page.syntax ?? [])
+                report(null, `${problem.message} (${problem.file}:${problem.line})`);
+        },
+    },
+    {
+        name: 'img-alt',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (n.tag === 'img' && !n.attrs.alt?.trim())
+                    report(n, 'Image without alternative text.');
+            }
+        },
+    },
+    {
+        name: 'single-h1',
+        severity: 'warning',
+        run(page, report) {
+            const h1s = everyNode(page).filter(n => n.tag === 'h1');
+            if (h1s.length === 0)
+                report(null, 'The page has no <h1>.');
+            // An <h1> that cannot be shown with one before it (the other side of a condition) is not one more
+            h1s.forEach((h1, index) => { if (h1s.slice(0, index).some(before => !exclusive(before, h1)))
+                report(h1, 'More than one <h1> in the page.'); });
+        },
+    },
+    {
+        name: 'heading-order',
+        severity: 'warning',
+        run(page, report) {
+            let previous = 0;
+            for (const n of everyNode(page)) {
+                const level = Number(HEADING.exec(n.tag)?.[1] ?? 0);
+                if (!level)
+                    continue;
+                if (previous && level > previous + 1)
+                    report(n, `Heading jumps from <h${previous}> to <h${level}>.`);
+                previous = level;
+            }
+        },
+    },
+    {
+        name: 'link-name',
+        severity: 'error',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (n.tag === 'a' && !n.text && !n.attrs['aria-label']?.trim())
+                    report(n, 'Link without text or aria-label.');
+            }
+        },
+    },
+    {
+        name: 'button-name',
+        severity: 'error',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (n.tag === 'button' && !n.text && !n.attrs['aria-label']?.trim())
+                    report(n, 'Button without text or aria-label.');
+            }
+        },
+    },
+    {
+        name: 'seo-jsonld',
+        severity: 'warning',
+        run(page, report) {
+            for (const problem of page.seo?.jsonLdProblems ?? [])
+                report(null, `The structured data of the page is not valid: ${problem}. Search engines ignore it.`);
+        },
+    },
+    {
+        name: 'broken-link',
+        severity: 'warning',
+        run(page, report) {
+            const project = page.project;
+            if (!project)
+                return;
+            for (const n of everyNode(page)) {
+                const href = n.attrs.href;
+                if (n.tag === 'a' && href !== undefined && !leadsSomewhere(href, project))
+                    report(n, `The link to ${href} leads to no page of the site.`, undefined, href);
+            }
+        },
+    },
+    {
+        name: 'button-action',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (n.tag === 'button' && n.acts === false)
+                    report(n, 'The button does nothing: it has no click handler, is not a submit button and is not inside a form or a link.');
+            }
+        },
+    },
+    {
+        name: 'iframe-title',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (n.tag === 'iframe' && !n.attrs.title?.trim() && !n.attrs['aria-label']?.trim() && !n.attrs['{spread}'])
+                    report(n, 'The frame has no title: a screen reader announces it as "frame" and nothing more.');
+            }
+        },
+    },
+    {
+        name: 'video-autoplay',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (n.tag === 'video' && n.attrs.autoplay !== undefined && n.attrs.autoplay !== 'false' && n.attrs.controls === undefined && !n.attrs['{spread}']) {
+                    report(n, 'The video starts by itself and has no controls: nobody can pause it (WCAG 2.2.2).');
+                }
+            }
+        },
+    },
+    {
+        name: 'click-keyboard',
+        severity: 'warning',
+        run(page, report) {
+            const interactive = new Set(['a', 'button', 'input', 'select', 'textarea', 'summary', 'details', 'label', 'option']);
+            for (const n of everyNode(page)) {
+                if (n.attrs.onclick && n.kind === 'element' && !interactive.has(n.tag) && !n.attrs.role && n.attrs.tabindex === undefined && !n.attrs.onkeydown && !n.attrs['{spread}']) {
+                    report(n, `A <${n.tag}> reacts to clicks but cannot be reached or used with the keyboard: use a button, or give it a role, tabIndex and a key handler.`);
+                }
+            }
+        },
+    },
+    {
+        name: 'tabindex-positive',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (Number(n.attrs.tabindex) > 0)
+                    report(n, 'tabIndex above 0 changes the order the keyboard goes through the page, and almost always breaks it: use 0, or -1.');
+            }
+        },
+    },
+    {
+        name: 'form-label',
+        severity: 'warning',
+        run(page, report) {
+            const fields = new Set(['input', 'select', 'textarea']);
+            const labelled = new Set(page.labelledIds ?? []);
+            for (const n of everyNode(page)) {
+                // A WrInput is judged by `form-input-name` (its label is in the JSON, not an attribute)
+                if (!fields.has(n.tag) || n.kind === 'input' || n.attrs['{spread}'])
+                    continue;
+                if (['hidden', 'submit', 'button', 'reset', 'image'].includes(n.attrs.type))
+                    continue;
+                if (n.attrs['aria-label']?.trim() || n.attrs['aria-labelledby'] || n.attrs.title?.trim() || n.insideLabel || (n.id && labelled.has(n.id)))
+                    continue;
+                report(n, `A form field has no label: a placeholder is not one. Wrap it in a <label>, or give it an aria-label.`);
+            }
+        },
+    },
+    {
+        name: 'form-altcha',
+        severity: 'error',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (n.kind !== 'form')
+                    continue;
+                let found = false;
+                walk(n.children, c => { if (c.kind === 'altcha')
+                    found = true; });
+                if (!found)
+                    report(n, 'The form has no Altcha: the Webround backend refuses a form without its proof of work, so it can never be sent.');
+            }
+        },
+    },
+    {
+        name: 'form-input-name',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (n.kind !== 'input')
+                    continue;
+                const written = Object.values(n.values?.label ?? {}).some(text => text.trim() !== '');
+                if (!written && !n.attrs['aria-label']?.trim())
+                    report(n, 'A form field has no label: a placeholder is not one, and the owner reads this name in the email.');
+            }
+        },
+    },
+    {
+        name: 'form-policy-pages',
+        severity: 'warning',
+        run(page, report) {
+            const routes = page.project?.routes;
+            if (!routes)
+                return;
+            const form = everyNode(page).find(n => n.kind === 'form');
+            if (!form)
+                return;
+            if (!routes.includes('privacy-policy'))
+                report(form, 'The site has no "privacy-policy" page: a form collects personal data, and the consent line must link to a privacy policy.', undefined, 'privacy-policy');
+            if (!routes.includes('cookie-policy'))
+                report(form, 'The site has no "cookie-policy" page.', undefined, 'cookie-policy');
+        },
+    },
+    {
+        name: 'aria-valid-attr',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                const unknown = (n.attrs['{aria}'] ?? '').split(' ').filter(name => name && !ARIA_ATTRIBUTES.has(name.slice(5)));
+                if (unknown.length > 0)
+                    report(n, `${unknown.join(', ')} ${unknown.length === 1 ? 'is' : 'are'} not ${unknown.length === 1 ? 'an ARIA attribute' : 'ARIA attributes'}: a typo is ignored by screen readers.`);
+            }
+        },
+    },
+    {
+        name: 'aria-valid-role',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                const roles = (n.attrs.role ?? '').split(/\s+/).filter(role => role && role !== '{…}');
+                if (roles.length > 0 && !roles.some(isKnownRole))
+                    report(n, `"${roles.join(' ')}" is not a role ARIA knows: it is ignored, and the element keeps no role at all.`);
+            }
+        },
+    },
+    {
+        name: 'aria-required-attr',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                const role = (n.attrs.role ?? '').split(/\s+/)[0];
+                const needs = REQUIRED_BY_ROLE[role];
+                if (!needs || n.attrs['{spread}'])
+                    continue;
+                const has = new Set((n.attrs['{aria}'] ?? '').split(' ').map(name => name.slice(5)));
+                const missing = needs.filter(name => !has.has(name));
+                if (missing.length > 0)
+                    report(n, `A ${role} needs ${missing.map(name => `aria-${name}`).join(' and ')}: without it a screen reader cannot say what it is doing.`);
+            }
+        },
+    },
+    {
+        name: 'aria-hidden-focusable',
+        severity: 'warning',
+        run(page, report) {
+            const focusable = (n) => (FOCUSABLE_TAGS.has(n.tag) || (n.tag === 'a' && n.attrs.href !== undefined) || (n.tag === 'input' && n.attrs.type !== 'hidden') || Number(n.attrs.tabindex) >= 0) && n.attrs.tabindex !== '-1';
+            const inside = (n) => n.children.some(child => focusable(child) || inside(child));
+            const visit = (nodes) => {
+                for (const n of nodes) {
+                    if (n.attrs['aria-hidden'] === 'true') {
+                        if (focusable(n) || inside(n))
+                            report(n, 'The element is hidden from screen readers (aria-hidden) but can still be reached with the keyboard: it is there for one and not for the other.');
+                        continue; // what is inside is hidden as well: one finding is enough
+                    }
+                    visit(n.children);
+                }
+            };
+            visit(page.nodes);
+        },
+    },
+    {
+        name: 'aria-reference',
+        severity: 'warning',
+        run(page, report) {
+            const ids = new Set(everyNode(page).map(n => n.id).filter((id) => !!id));
+            for (const n of everyNode(page)) {
+                for (const attribute of ['aria-labelledby', 'aria-describedby']) {
+                    const value = n.attrs[attribute];
+                    if (!value || value === '{…}')
+                        continue;
+                    const missing = value.split(/\s+/).filter(id => id && !ids.has(id));
+                    if (missing.length > 0)
+                        report(n, `${attribute} points to ${missing.join(', ')}, which ${missing.length === 1 ? 'is' : 'are'} not in the page.`);
+                }
+            }
+        },
+    },
+    {
+        name: 'aria-label-ignored',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                // A `WrNav` is the exception: its box is a `div`, but it gives its name to the `<nav>` that the menu draws (`options.ariaLabel`)
+                if (n.kind !== 'nav' && n.attrs['aria-label']?.trim() && GENERIC_TAGS.has(n.tag) && !n.attrs.role && !n.attrs['{spread}']) {
+                    report(n, `An aria-label on a <${n.tag}> is not announced: it is only a container. Give it a role, or use the label on what holds the content (a <section>, a <nav>…).`);
+                }
+            }
+        },
+    },
+    {
+        name: 'link-text-generic',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (n.tag !== 'a' || n.attrs['aria-label']?.trim())
+                    continue;
+                const text = normalizedLinkText(n.text);
+                if (text && GENERIC_LINK_TEXTS.has(text))
+                    report(n, `The link says only "${n.text.trim()}": out of its sentence (a screen reader lists links on their own) nobody knows where it goes.`);
+            }
+        },
+    },
+    {
+        name: 'landmark-main',
+        severity: 'warning',
+        run(page, report) {
+            const mains = [...everyNode(page)].filter(n => n.tag === 'main' || n.attrs.role === 'main');
+            if (page.source === 'dom') {
+                // The rendered page has the layout's <main> in it: one is right, a second one is the page's own
+                for (const n of mains.slice(1))
+                    report(n, 'The page has more than one <main> (there is one main landmark). Make this a <div> or a <section>.');
+                return;
+            }
+            // In the code the layout's <main> is not there (WrLayout wraps every page in it): any <main> of the page's own is a second one
+            for (const n of mains)
+                report(n, 'The layout already puts the page in a <main>: a second one is an error (there is one main landmark). Make this a <div> or a <section>.');
+        },
+    },
+    {
+        name: 'focus-visible',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                const classes = (n.attrs.class ?? '').split(/\s+/).filter(Boolean);
+                if (classes.length === 0 || n.attrs.class === '{…}')
+                    continue;
+                const interactive = FOCUSABLE_TAGS.has(n.tag) || (n.tag === 'a' && n.attrs.href !== undefined) || (n.tag === 'input' && n.attrs.type !== 'hidden') || Number(n.attrs.tabindex) >= 0 || n.attrs.role === 'button' || n.attrs.role === 'link';
+                if (!interactive)
+                    continue;
+                if (classes.some(c => FOCUS_OUTLINE_REMOVED.test(c)) && !classes.some(c => FOCUS_STYLED.test(c) && !FOCUS_OUTLINE_REMOVED.test(c))) {
+                    report(n, 'The focus outline is removed and nothing replaces it: someone using the keyboard cannot tell where they are (WCAG 2.4.7). Add a focus-visible ring or outline.');
+                }
+            }
+        },
+    },
+    {
+        name: 'motion-reduce',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                const classes = (n.attrs.class ?? '').split(/\s+/).filter(Boolean);
+                if (classes.length === 0 || n.attrs.class === '{…}')
+                    continue;
+                const moves = classes.filter(c => /^(animate-(?!none$)[\w[\]-]+|scroll-smooth)$/.test(c));
+                if (moves.length > 0 && !classes.some(c => /^motion-reduce:/.test(c))) {
+                    report(n, `${moves.join(', ')} moves without checking whether the person asked for less motion: add motion-reduce:animate-none (or use motion-safe:) (WCAG 2.3.3, and 2.2.2 for what never stops).`);
+                }
+            }
+        },
+    },
+    {
+        name: 'autocomplete',
+        severity: 'warning',
+        run(page, report) {
+            for (const n of everyNode(page)) {
+                if (!['input', 'select', 'textarea'].includes(n.tag) || n.attrs['{spread}'])
+                    continue;
+                const given = n.attrs.autocomplete;
+                if (given !== undefined && given !== '{…}' && !isValidAutocomplete(given)) {
+                    report(n, `autoComplete="${given}" is not a value browsers know (it is ignored): use the field's purpose, like email, given-name, tel or postal-code (WCAG 1.3.5).`);
+                    continue;
+                }
+                const wanted = expectedAutocomplete(n.attrs);
+                if (wanted && given === undefined)
+                    report(n, `A field that asks for the person's own data should say what it is: add autoComplete="${wanted}", so the browser and assistive tools can fill it (WCAG 1.3.5).`);
+            }
+        },
+    },
+    {
+        name: 'duplicate-id',
+        severity: 'error',
+        run(page, report) {
+            const seen = new Set();
+            for (const n of everyNode(page)) {
+                if (!n.id || n.id === '{…}')
+                    continue; // an id the code computes: which one it is cannot be read, so it is not "the same" as another
+                if (seen.has(n.id))
+                    report(n, `The id "${n.id}" is used more than once.`);
+                seen.add(n.id);
+            }
+        },
+    },
+];
+export const SITE_RULES = [
+    {
+        name: 'seo-jsonld-site',
+        severity: 'warning',
+        run: (site, report) => { for (const problem of wrJsonLdProblems(site.seo.jsonLd))
+            report(`The structured data of the site is not valid: ${problem}. Search engines ignore it.`, undefined); },
+    },
+    {
+        name: 'focus-visible-css',
+        severity: 'warning',
+        run: (site, report) => {
+            for (const { file, selector } of site.css.focusRemoved)
+                report(`${file}: "${selector}" removes the focus outline and puts nothing in its place: someone using the keyboard cannot tell where they are (WCAG 2.4.7).`, undefined, undefined, `${file}:${selector}`);
+        },
+    },
+    {
+        name: 'motion-reduce-css',
+        severity: 'warning',
+        run: (site, report) => { if (site.css.animates && !site.css.reducesMotion)
+            report('The stylesheets animate things and none has an @media (prefers-reduced-motion: reduce): people who asked their system for less motion still get it all.'); },
+    },
+    {
+        name: 'html-lang',
+        severity: 'warning',
+        run: (site, report) => { if (site.index && !site.index.lang)
+            report('index.html has no lang on <html>: screen readers cannot tell what language to speak before the page says (it does set it once loaded, but not on the first paint).'); },
+    },
+    {
+        name: 'viewport-zoom',
+        severity: 'warning',
+        run: (site, report) => {
+            const viewport = site.index?.viewport ?? '';
+            if (/user-scalable\s*=\s*(no|0)/i.test(viewport) || /maximum-scale\s*=\s*(0?\.\d+|1(\.0+)?)\b/i.test(viewport))
+                report('The viewport stops visitors from zooming (user-scalable / maximum-scale): people with low vision need it (WCAG 1.4.4).');
+        },
+    },
+    {
+        name: 'seo-favicon',
+        severity: 'warning',
+        run: (site, report) => { if (!site.seo.favicon?.trim())
+            report('The site has no favicon.', { kind: 'seo-site', field: 'favicon' }); },
+    },
+    {
+        name: 'seo-site-url',
+        severity: 'warning',
+        run: (site, report) => {
+            if (!wrSiteUrlOf(site.seo))
+                report('The site does not know its public address: canonical links, language alternates and the sitemap need it.', { kind: 'seo-site', field: 'siteUrl' });
+        },
+    },
+    {
+        name: 'orphan-key',
+        severity: 'warning',
+        run(site, report) {
+            for (const { scope, keys } of site.orphans) {
+                const some = keys.slice(0, 3).join(', ') + (keys.length > 3 ? ` and ${keys.length - 3} more` : '');
+                const what = `The values of ${keys.length === 1 ? 'an element that is' : `${keys.length} elements that are`} no longer in the code are still in the JSON (${some}).`;
+                // With ids the code computes, a key that looks unused may belong to one of them: nothing is offered to be removed
+                if (site.dynamicIds)
+                    report(`${what} Some elements compute their ids, so check before removing them.`, undefined, scope);
+                else
+                    report(what, { kind: 'prune', scope, keys }, scope);
+            }
+        },
+    },
+];
+export function runRules(pages, rules = RULES) {
+    const issues = [];
+    for (const page of pages) {
+        for (const rule of rules) {
+            rule.run(page, (node, message, fix, subject) => {
+                // What it is about: the said subject, else the element's id, else the place of a plain element in its file
+                const about = subject ?? node?.id ?? (node?.where ? `${node.tag}@${node.where.file}:${node.where.line}` : undefined);
+                issues.push({
+                    rule: rule.name, severity: rule.severity, page: page.name, message,
+                    ...(node?.id ? { nodeId: node.id } : {}), ...(node?.where ? { where: node.where } : {}), ...(fix ? { fix } : {}),
+                    ...(about ? { subject: about } : {}),
+                    key: issueKey({ rule: rule.name, page: page.name, subject: about, fix }),
+                });
+            });
+        }
+    }
+    return issues;
+}
+/** What is wrong with the site as a whole, not with one page. */
+export function runSiteRules(site, rules = SITE_RULES) {
+    const issues = [];
+    for (const rule of rules)
+        rule.run(site, (message, fix, page, subject) => issues.push({ rule: rule.name, severity: rule.severity, page: page ?? CHECK_SITE, message, ...(fix ? { fix } : {}), ...(subject ? { subject } : {}), key: issueKey({ rule: rule.name, page: page ?? CHECK_SITE, subject, fix }) }));
+    return issues;
+}
+//# sourceMappingURL=rules.js.map

package/dist/check/types.d.ts

@@ -0,0 +1,160 @@
+import type { WrElementKind } from '@webround/core/kinds';
+/** What an element is for a rule: the Webround kinds keep theirs, plain HTML is just `element` (the rules go by tag). */
+export type CheckKind = WrElementKind | 'element';
+export interface CheckNode {
+    /** `data-wr-id` / `id=` of a Wr component; plain HTML has none. */
+    id?: string;
+    kind: CheckKind;
+    /** Lowercase HTML tag the node ends up as (`h1`, `img`, `a`…). */
+    tag: string;
+    /** Only the attributes rules read, already resolved for the default language (JSON wins over code). */
+    attrs: Record<string, string>;
+    /** Text the user would read, tags stripped. */
+    text: string;
+    children: CheckNode[];
+    /** The scope (page, `_shared/header`…) it is in, when the tree is read for more than the checks (see the outline). */
+    scope?: string;
+    /** Only the code producer says it, for a button: does pressing it do anything (a handler, a submit, a form or a link around it)? Absent = not known. */
+    acts?: boolean;
+    /** Only the code producer says it, for a form field: it sits inside a `<label>`. */
+    insideLabel?: boolean;
+    /**
+     * Only the code producer says it: the sides of the conditions the element is under (`c ? a : b`, or `c && a` against `!c && b`), the outermost first. Two elements on different sides of the same
+     * condition (same `key`) are never shown together: a rule that counts what the page shows does not count both.
+     */
+    branch?: {
+        key: string;
+        side: string;
+    }[];
+    /** Shown as hidden in the JSON: the checks do not count it (it does not render), an outline says so. */
+    hidden?: true;
+    /** What the element says in each language, for the fields that are translated (`content`, `alt`, `ariaLabel`): field → language key → value. */
+    values?: Record<string, Record<string, string>>;
+    /** Where to look: a file and line for the code producer, nothing for the DOM. */
+    where?: {
+        file: string;
+        line: number;
+    };
+}
+export interface CheckPage {
+    name: string;
+    nodes: CheckNode[];
+    /** `dom` when the tree is what a browser rendered (the layout's own elements are in it); absent when it is read from the code. */
+    source?: 'dom';
+    /** Code the parser could not read (only the code producer knows): such a page cannot be judged, and cannot be shown. */
+    syntax?: {
+        file: string;
+        line: number;
+        message: string;
+    }[];
+    /** The language this tree is read in: `default`, or a language code of the site. Absent when the site has one language. */
+    lang?: string;
+    /** What the site has that a link can point to (only the code producer knows it): the routes, the languages, the files in `public/`. */
+    project?: CheckProject;
+    /** The ids of the form fields some `<label htmlFor>` of the code points at. */
+    labelledIds?: string[];
+    /** What the page tells search engines (only the code producer knows it: the DOM has no `config`): text by language key, `default` first. */
+    seo?: {
+        title: Record<string, string>;
+        description: Record<string, string>;
+        noindex: boolean;
+        /** The page is a family of pages (`product/[slug]`, `shop/[slug]`): one JSON for all of them, so a title or description written there would be the same for each. What they say comes from the data the page loads (`useWrSeo`). */
+        family: boolean;
+        /** What is wrong with the page's JSON-LD (empty when it is fine). */
+        jsonLdProblems: string[];
+    };
+}
+/** Where a link of the site may lead. */
+export interface CheckProject {
+    /** The route paths (`about`, `blog/[slug]`: `home` is the home page). */
+    routes: string[];
+    langs?: {
+        default: string;
+        available: string[];
+    };
+    /** Files served as they are (`/robots.txt`, `/brochure.pdf`), as paths from the site's root. */
+    publicFiles: string[];
+}
+export type Severity = 'error' | 'warning';
+/** The page name an issue about the whole site carries (the way `_shared/header` names what is not a page). */
+export declare const CHECK_SITE = "_site";
+/** Where a problem is solved when it is not an element of the page: a field of the page's SEO data, or of the site's. */
+export type IssueFix = {
+    kind: 'seo-page';
+    field: 'title' | 'description'; /** the language key (`default` or a code) the field is missing in */
+    lang: string;
+} | {
+    kind: 'seo-site';
+    field: 'favicon' | 'siteUrl';
+}
+/** Keys of a scope's JSON that no element of the code uses: removed by `json-prune`. */
+ | {
+    kind: 'prune';
+    scope: string;
+    keys: string[];
+};
+/** What the checks know of the site as a whole (not of one page). */
+export interface CheckSite {
+    seo: import('@webround/core/seo').WrSeoSite;
+    /** Keys in the JSON of each scope (page, header, footer) that no element in any file of `src/` has the id of. */
+    orphans: {
+        scope: string;
+        keys: string[];
+    }[];
+    /** What the project's stylesheets do about the focus ring and about animation. */
+    css: import('./css.js').CheckCss;
+    /** What `index.html` says (the page every route is served in); null while the project has none. */
+    index: {
+        lang: string | null;
+        viewport: string | null;
+    } | null;
+    /** Some element has an id the code computes: a key that looks unused may belong to it, so nothing can be said to be unused. */
+    dynamicIds: boolean;
+}
+export interface Issue {
+    rule: string;
+    severity: Severity;
+    /** The page, or `CHECK_SITE` for what is about the whole site. */
+    page: string;
+    /** The languages it happens in (language keys: `default` or a code), when the site has several: ONE issue says where, not one per language. */
+    langs?: string[];
+    message: string;
+    nodeId?: string;
+    where?: {
+        file: string;
+        line: number;
+    };
+    /** Where to fix it, when there is no element to point at (a missing title, a missing favicon). */
+    fix?: IssueFix;
+    /** What it is about: the address of a broken link, the id of an element, the place of a plain element in its file. */
+    subject?: string;
+    /** Who it is: the same problem has the same key every time it is found, in every language, so that a person's decision about it (to silence it) sticks. */
+    key: string;
+    /** The person decided not to deal with it: it is still there, and counted apart. */
+    muted?: true;
+}
+/**
+ * The identity of a problem: its rule, where it is (a page, or `_shared` for the header and footer, which every page shows), and what it is about.
+ * NOT the words (a count in them changes) nor the languages (one decision covers them all).
+ */
+export declare function issueKey(parts: {
+    rule: string;
+    page: string;
+    subject?: string;
+    fix?: IssueFix;
+}): string;
+export interface Rule {
+    name: string;
+    severity: Severity;
+    run(page: CheckPage, report: (node: CheckNode | null, message: string, fix?: IssueFix, subject?: string) => void): void;
+}
+/** A rule about the site as a whole. */
+export interface SiteRule {
+    name: string;
+    severity: Severity;
+    run(site: CheckSite, report: (message: string, fix?: IssueFix, page?: string, subject?: string) => void): void;
+}
+/** Depth-first, in document order. */
+export declare function walk(nodes: readonly CheckNode[], visit: (node: CheckNode) => void): void;
+export declare function stripTags(html: string): string;
+//# sourceMappingURL=types.d.ts.map