@chrissgon/light-site-auditor 0.1.0

package/dist/profile.js

@@ -0,0 +1,19 @@
+/**
+ * The 3G profile every audit uses: Lighthouse's `mobileRegular3G` preset, copied from its source so
+ * the numbers are visible here. Source and access date: docs/spikes/3g.md.
+ * tests/profile.test.ts fails if the installed Lighthouse ever defines the preset differently.
+ */
+export const REGULAR_3G = {
+    /** Round-trip time between the phone and the server, in milliseconds. */
+    rttMs: 300,
+    /** Download and upload bandwidth, in kilobits per second. */
+    throughputKbps: 700,
+    /** The DevTools-throttling equivalents (not used by simulated throttling; kept for completeness). */
+    requestLatencyMs: 300 * 3.75,
+    downloadThroughputKbps: 700 * 0.9,
+    uploadThroughputKbps: 700 * 0.9,
+    /** The phone's processor is emulated as this many times slower than the machine running the audit. */
+    cpuSlowdownMultiplier: 4,
+};
+/** Lighthouse's own throttling method by default: a simulation from one unthrottled load. */
+export const THROTTLING_METHOD = "simulate";

package/dist/report.js

@@ -0,0 +1,241 @@
+import { CATALOG, explainAxe, explainLighthouse, fill, glossaryClosure } from "./explanations.js";
+import { FILE_TYPES, weightByType } from "./weight.js";
+const T = CATALOG.report;
+const METRICS = ["first-contentful-paint", "largest-contentful-paint"];
+/** Lighthouse's own threshold: an audit scoring below 0.9 is not passed. */
+const PASS = 0.9;
+/** One decimal, Portuguese decimal comma: 4202.484 ms → "4,2" seconds; 200211 bytes → "200,2" KB. */
+export const oneDecimal = (n) => (Math.round(n * 10) / 10).toFixed(1).replace(".", ",");
+const seconds = (ms) => oneDecimal(ms / 1000);
+const kb = (bytes) => oneDecimal(bytes / 1000);
+/** The Lighthouse insights and diagnostics that did not pass, largest possible gain first. */
+export function lighthouseProblems(lhr) {
+    const refs = lhr.categories.performance?.auditRefs ?? [];
+    return refs
+        .filter((ref) => ref.group === "insights" || ref.group === "diagnostics")
+        .map((ref) => lhr.audits[ref.id])
+        .filter((a) => a && a.score !== null && a.score < PASS && ["binary", "numeric", "metricSavings"].includes(a.scoreDisplayMode))
+        .map((audit) => ({ audit, lcp: audit.metricSavings?.LCP ?? 0, fcp: audit.metricSavings?.FCP ?? 0 }))
+        .sort((a, b) => b.lcp - a.lcp || b.fcp - a.fcp);
+}
+function explanationBlocks(e, heading, extra = []) {
+    if (!e.explained) {
+        return [
+            { h: 3, text: [...heading, ` (${e.mark})`] },
+            { p: [T.noExplanationNote] },
+            { p: [{ strong: `${T.original}:` }, " ", { code: e.original }] },
+            ...extra.map((p) => ({ p })),
+        ];
+    }
+    return [
+        { h: 3, text: heading },
+        { p: [{ strong: `${T.whatItIs}:` }, ` ${e.what}`] },
+        { p: [{ strong: `${T.whatToDo}:` }, ` ${e.fix}`] },
+        ...extra.map((p) => ({ p })),
+    ];
+}
+export function buildBlocks(lhr, axe, files) {
+    const weight = weightByType(lhr);
+    const throttling = lhr.configSettings.throttling;
+    const blocks = [
+        { h: 1, text: [T.title] },
+        { p: [`${T.intro} ${T.introSources} ${T.introTerms}`] },
+        {
+            ul: [
+                [{ strong: `${T.page}:` }, " ", { code: lhr.finalDisplayedUrl }],
+                [{ strong: `${T.measuredAt}:` }, " ", { code: lhr.fetchTime }],
+            ],
+        },
+    ];
+    // Weight by file type, heaviest first; types with no file are left out.
+    const types = FILE_TYPES.filter((t) => weight.byType[t].files > 0).sort((a, b) => weight.byType[b].transferBytes - weight.byType[a].transferBytes);
+    blocks.push({ h: 2, text: [T.weightHeading] }, { p: [T.weightIntro] }, { p: [{ strong: fill(T.weightTotal, { kb: kb(weight.total.transferBytes), files: weight.total.files }) }] }, {
+        table: {
+            head: [T.weightType, T.weightFiles, T.weightSize],
+            rows: types.map((t) => [[CATALOG.fileTypes[t]], [String(weight.byType[t].files)], [kb(weight.byType[t].transferBytes)]]),
+        },
+    });
+    // Load times on the 3G profile.
+    blocks.push({ h: 2, text: [T.loadHeading] }, { p: [T.loadIntro] }, {
+        ul: METRICS.map((id) => [
+            { strong: fill(T.loadMetric, { title: CATALOG.metrics[id].title, seconds: seconds(lhr.audits[id].numericValue) }) },
+            ` ${CATALOG.metrics[id].what}`,
+        ]),
+    }, {
+        p: [
+            fill(T.loadProfile, {
+                rtt: throttling.rttMs ?? "",
+                kbps: throttling.throughputKbps ?? "",
+                cpu: throttling.cpuSlowdownMultiplier ?? "",
+            }),
+        ],
+    });
+    // What makes the page heavy or slow.
+    const problems = lighthouseProblems(lhr);
+    blocks.push({ h: 2, text: [T.speedHeading] });
+    if (problems.length === 0)
+        blocks.push({ p: [T.speedNone] });
+    for (const { audit, lcp, fcp } of problems) {
+        const e = explainLighthouse(audit.id, audit.title);
+        const gain = lcp > 0 ? [[fill(T.speedGainLcp, { seconds: seconds(lcp) })]] : fcp > 0 ? [[fill(T.speedGainFcp, { seconds: seconds(fcp) })]] : [];
+        blocks.push(...explanationBlocks(e, [e.title], gain));
+    }
+    // Accessibility barriers.
+    const places = axe.violations.reduce((n, v) => n + v.nodes.length, 0);
+    blocks.push({ h: 2, text: [T.a11yHeading] }, { p: [T.a11yIntro] });
+    if (axe.violations.length === 0)
+        blocks.push({ p: [T.a11yNone] });
+    else
+        blocks.push({ p: [{ strong: fill(T.a11yCount, { rules: axe.violations.length, places }) }] });
+    for (const v of axe.violations) {
+        const e = explainAxe(v.id, v.help);
+        const impact = v.impact ? CATALOG.impact[v.impact] : undefined;
+        const shown = v.nodes.slice(0, 5);
+        blocks.push(...explanationBlocks(e, [e.title], [
+            ...(impact ? [[{ strong: `${T.severity}:` }, ` ${impact}`]] : []),
+            [v.nodes.length === 1 ? T.a11yPlacesOne : fill(T.a11yPlaces, { places: v.nodes.length })],
+            [{ strong: `${T.a11yWhere}:` }],
+        ]), { ul: shown.map((n) => [{ code: n.html }]) });
+        if (v.nodes.length > shown.length)
+            blocks.push({ p: [T.a11yMore] });
+    }
+    blocks.push({ p: [T.a11yNote] });
+    // Glossary: every term the prose above uses, and the terms its definitions use.
+    const prose = blocks.flatMap(textOf);
+    const terms = glossaryClosure([...prose, T.termsHeading, T.sourcesHeading, T.sourcesIntro]);
+    blocks.push({ h: 2, text: [T.termsHeading] }, { ul: terms.map((t) => [{ strong: `${t}:` }, ` ${CATALOG.glossary[t]}`]) });
+    // Where every number comes from.
+    const lh = { code: files.lighthouse };
+    blocks.push({ h: 2, text: [T.sourcesHeading] }, { p: [T.sourcesIntro] }, {
+        ul: [
+            [
+                `${T.sourcesWeight} `,
+                lh,
+                ", ",
+                { code: 'audits["network-requests"].details.items[].transferSize' },
+                ", ",
+                { code: "resourceType" },
+                ": ",
+                types.map((t) => `${CATALOG.fileTypes[t]} ${weight.byType[t].transferBytes}`).join("; "),
+                ".",
+            ],
+            [`${T.sourcesTotal}, `, { code: 'audits["total-byte-weight"].numericValue' }, `: ${lhr.audits["total-byte-weight"].numericValue}.`],
+            [
+                `${T.sourcesTime}, `,
+                ...METRICS.flatMap((id, i) => [
+                    i ? "; " : "",
+                    { code: `audits["${id}"].numericValue` },
+                    `: ${lhr.audits[id].numericValue}`,
+                ]),
+                ".",
+            ],
+            [
+                `${T.sourcesProfile}, `,
+                { code: "configSettings.throttling" },
+                ": ",
+                { code: "rttMs" },
+                ` ${throttling.rttMs}, `,
+                { code: "throughputKbps" },
+                ` ${throttling.throughputKbps}, `,
+                { code: "cpuSlowdownMultiplier" },
+                ` ${throttling.cpuSlowdownMultiplier}.`,
+            ],
+            ...(problems.some((p) => p.lcp > 0 || p.fcp > 0)
+                ? [
+                    [
+                        `${T.sourcesGain}, `,
+                        ...problems
+                            .filter((p) => p.lcp > 0 || p.fcp > 0)
+                            .flatMap((p, i) => {
+                            const metric = p.lcp > 0 ? "LCP" : "FCP";
+                            return [i ? "; " : "", { code: `audits["${p.audit.id}"].metricSavings.${metric}` }, `: ${p.lcp > 0 ? p.lcp : p.fcp}`];
+                        }),
+                        ".",
+                    ],
+                ]
+                : []),
+            [`${T.sourcesA11y}, `, { code: files.axe }, ", ", { code: "violations[].nodes" }, "."],
+        ],
+    });
+    return blocks;
+}
+/** The plain text of a block, without code spans (what a reader reads as prose). */
+function textOf(block) {
+    const inline = (parts) => parts.map((p) => (typeof p === "string" ? p : "strong" in p ? p.strong : "")).join("");
+    if ("h" in block)
+        return [inline(block.text)];
+    if ("p" in block)
+        return [inline(block.p)];
+    if ("ul" in block)
+        return block.ul.map(inline);
+    return [...block.table.head, ...block.table.rows.flatMap((row) => row.map(inline))];
+}
+// ---- Markdown -------------------------------------------------------------------------------------
+const mdCode = (s) => {
+    const flat = s.replace(/\s*\n\s*/g, " ");
+    return flat.includes("`") ? `\`\` ${flat} \`\`` : `\`${flat}\``;
+};
+const mdInline = (parts) => parts.map((p) => (typeof p === "string" ? p : "code" in p ? mdCode(p.code) : `**${p.strong}**`)).join("");
+export function toMarkdown(blocks) {
+    const out = [];
+    for (const b of blocks) {
+        if ("h" in b)
+            out.push(`${"#".repeat(b.h)} ${mdInline(b.text)}`);
+        else if ("p" in b)
+            out.push(mdInline(b.p));
+        else if ("ul" in b)
+            out.push(b.ul.map((item) => `- ${mdInline(item)}`).join("\n"));
+        else {
+            const row = (cells) => `| ${cells.join(" | ")} |`;
+            out.push([row(b.table.head), row(b.table.head.map(() => "---")), ...b.table.rows.map((r) => row(r.map(mdInline)))].join("\n"));
+        }
+    }
+    return `${out.join("\n\n")}\n`;
+}
+// ---- HTML -----------------------------------------------------------------------------------------
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+const htmlInline = (parts) => parts
+    .map((p) => (typeof p === "string" ? esc(p) : "code" in p ? `<code>${esc(p.code)}</code>` : `<strong>${esc(p.strong)}</strong>`))
+    .join("");
+const STYLE = `
+body { font: 1.0625rem/1.6 system-ui, sans-serif; color: #1a1a1a; background: #ffffff; max-width: 46rem; margin: 0 auto; padding: 1rem; }
+h1, h2, h3 { line-height: 1.25; }
+h2 { margin-top: 2.5rem; border-bottom: 1px solid #d0d0d0; padding-bottom: 0.25rem; }
+code { font-size: 0.9em; background: #f2f2f2; padding: 0.1em 0.3em; border-radius: 0.2em; overflow-wrap: anywhere; }
+table { border-collapse: collapse; width: 100%; }
+th, td { text-align: left; padding: 0.4rem 0.6rem; border-bottom: 1px solid #d0d0d0; }
+`;
+export function toHtml(blocks) {
+    const body = blocks.map((b) => {
+        if ("h" in b)
+            return `<h${b.h}>${htmlInline(b.text)}</h${b.h}>`;
+        if ("p" in b)
+            return `<p>${htmlInline(b.p)}</p>`;
+        if ("ul" in b)
+            return `<ul>\n${b.ul.map((item) => `<li>${htmlInline(item)}</li>`).join("\n")}\n</ul>`;
+        const head = `<tr>${b.table.head.map((h) => `<th scope="col">${esc(h)}</th>`).join("")}</tr>`;
+        const rows = b.table.rows.map((r) => `<tr>${r.map((c) => `<td>${htmlInline(c)}</td>`).join("")}</tr>`).join("\n");
+        return `<table>\n<thead>${head}</thead>\n<tbody>\n${rows}\n</tbody>\n</table>`;
+    });
+    return [
+        "<!doctype html>",
+        '<html lang="pt-BR">',
+        "<head>",
+        '<meta charset="utf-8">',
+        '<meta name="viewport" content="width=device-width, initial-scale=1">',
+        `<title>${esc(T.title)}</title>`,
+        `<style>${STYLE}</style>`,
+        "</head>",
+        "<body>",
+        "<main>",
+        ...body,
+        "</main>",
+        "</body>",
+        "</html>",
+        "",
+    ].join("\n");
+}
+export function buildReport(lhr, axe, files) {
+    const blocks = buildBlocks(lhr, axe, files);
+    return { markdown: toMarkdown(blocks), html: toHtml(blocks) };
+}

package/dist/weight.js

@@ -0,0 +1,32 @@
+/** The file types the report groups bytes by. */
+export const FILE_TYPES = ["html", "css", "js", "image", "font", "other"];
+/** Lighthouse's `resourceType` (Chrome's DevTools resource types) to the report's file types. */
+const TYPE_OF = {
+    Document: "html",
+    Stylesheet: "css",
+    Script: "js",
+    Image: "image",
+    Font: "font",
+};
+/** The items of the `network-requests` audit: one per request the page made. */
+export function networkItems(lhr) {
+    const details = lhr.audits["network-requests"]?.details;
+    if (!details?.items)
+        throw new Error("the Lighthouse result has no network-requests table");
+    return details.items;
+}
+/** Sums the bytes of every request by file type, from Lighthouse's `network-requests` audit. */
+export function weightByType(lhr) {
+    const empty = () => ({ files: 0, transferBytes: 0, resourceBytes: 0 });
+    const byType = Object.fromEntries(FILE_TYPES.map((type) => [type, empty()]));
+    const total = empty();
+    for (const item of networkItems(lhr)) {
+        const type = TYPE_OF[item.resourceType ?? ""] ?? "other";
+        for (const bytes of [byType[type], total]) {
+            bytes.files += 1;
+            bytes.transferBytes += item.transferSize ?? 0;
+            bytes.resourceBytes += item.resourceSize ?? 0;
+        }
+    }
+    return { byType, total };
+}

package/docs/field/consentimento.md

@@ -0,0 +1,45 @@
+# Consentimento para auditar um site
+
+O auditor só verifica um site real depois que o dono aceita. Este arquivo tem o texto do pedido, que pode ser enviado como está, e o modelo do registro que a ferramenta lê antes de auditar (`auditor <url> --consent <arquivo>`).
+
+## Texto do pedido
+
+> Olá, [nome]. Eu uso uma ferramenta gratuita, o light-site-auditor, que verifica se um site é leve, se abre rápido num celular com internet fraca (3G) e se tem barreiras para pessoas com deficiência. Posso verificar a página inicial de [endereço]?
+>
+> **O que a verificação faz:** abre a página inicial pública do seu site como um visitante comum, duas vezes seguidas, e mede com duas ferramentas abertas, o Lighthouse e o axe, que rodam no meu computador.
+>
+> **O que ela não faz:** não entra em área com login, não preenche nem envia formulários, não abre outras páginas e não gera mais tráfego do que essas duas visitas.
+>
+> Com o resultado, eu escrevo um relatório em português simples, com o que corrigir. O relatório fica só com você, a menos que você concorde com outro uso.
+>
+> Você concorda? Basta responder "sim" ou "não", e você pode mudar de ideia quando quiser.
+
+## Registro do consentimento
+
+Crie um arquivo por site, por exemplo `docs/field/<site>/consentimento.md`, que comece com este bloco:
+
+```markdown
+---
+endereco: https://www.exemplo.com.br/
+dono: Nome de quem aceitou
+status: pendente: aguardando o aceite do dono
+data: -
+como: -
+reacao: pendente
+---
+```
+
+Quando o dono aceitar, troque `status` por `aceito`, `data` pela data do aceite (AAAA-MM-DD) e `como` pela forma do aceite (por exemplo, "por e-mail, respondendo ao pedido"). Depois de entregar o relatório, anote em `reacao` o que o dono achou.
+
+A ferramenta recusa a auditoria quando:
+
+- não há registro (`--consent`) e o endereço não é deste computador (`localhost`, `127.0.0.1`, `[::1]`);
+- `status` é qualquer coisa diferente de `aceito`, inclusive `pendente`;
+- o endereço auditado não é exatamente o `endereco` do registro;
+- falta `endereco`, `dono`, `status`, `data` ou `como`, ou a data não está no formato AAAA-MM-DD ou é futura.
+
+Não existe opção para pular essa verificação.
+
+## O que fica guardado
+
+Na pasta do relatório ficam `relatorio.md`, `relatorio.html`, `lighthouse.json` e `axe.json`. Neste repositório, as pastas `docs/field/<site>/` ficam fora do git (`.gitignore`): o relatório é só do dono do site.

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@chrissgon/light-site-auditor",
+  "version": "0.1.0",
+  "description": "Checks a small business's home page for weight, load time on 3G and accessibility (WCAG 2.1 AA), and explains the fixes in plain Portuguese. Real sites only with the owner's consent.",
+  "keywords": [
+    "accessibility",
+    "acessibilidade",
+    "wcag",
+    "axe",
+    "lighthouse",
+    "performance",
+    "3g",
+    "web-performance",
+    "audit",
+    "auditoria",
+    "cli",
+    "portuguese"
+  ],
+  "homepage": "https://github.com/chrissgon/light-site-auditor#readme",
+  "bugs": {
+    "url": "https://github.com/chrissgon/light-site-auditor/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chrissgon/light-site-auditor.git"
+  },
+  "license": "MIT",
+  "author": "Christopher Gonçalves",
+  "type": "module",
+  "bin": {
+    "auditor": "dist/cli.js"
+  },
+  "files": [
+    "dist/",
+    "docs/field/consentimento.md"
+  ],
+  "engines": {
+    "node": ">=22.19"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.scripts.json",
+    "auditor": "tsx src/cli.ts",
+    "fixture": "tsx scripts/serve-fixture.ts",
+    "check-report": "tsx scripts/check-report.ts",
+    "prepack": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && npm run build"
+  },
+  "dependencies": {
+    "@axe-core/playwright": "4.13.0",
+    "chrome-launcher": "1.2.2",
+    "lighthouse": "13.5.0",
+    "playwright": "1.63.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.19.0",
+    "axe-core": "4.13.0",
+    "tsx": "4.23.15",
+    "typescript": "7.0.2",
+    "vitest": "5.0.2"
+  }
+}