dogsbay 0.0.0-init → 0.2.0-beta.0

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/index.js";

package/dist/audit/dist/crawler.js

@@ -0,0 +1,71 @@
+/**
+ * Dist crawler — walk a built site, parse every HTML file once
+ * with cheerio, and return them as `ParsedHtmlFile[]` ready for
+ * dist-stage rules.
+ *
+ * Parsing once and sharing the cheerio doc across rules avoids
+ * the N-rule × N-file re-parse that would otherwise dominate
+ * audit runtime on large sites.
+ */
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+import { load as loadHtml } from "cheerio";
+const DEFAULT_EXTENSIONS = ["html", "htm"];
+const DEFAULT_EXCLUDE_DIRS = ["pagefind", "_astro", "assets"];
+/**
+ * Walk `distRoot` recursively, parse every HTML file with
+ * cheerio, return the list. The list is sorted by path for
+ * deterministic test output.
+ */
+export function crawlDist(distRoot, options = {}) {
+    const exts = new Set((options.extensions ?? DEFAULT_EXTENSIONS).map((e) => e.startsWith(".") ? e.slice(1).toLowerCase() : e.toLowerCase()));
+    const excludeDirs = new Set(options.excludeDirs ?? DEFAULT_EXCLUDE_DIRS);
+    const files = [];
+    walk(distRoot, distRoot, exts, excludeDirs, files);
+    files.sort((a, b) => a.path.localeCompare(b.path));
+    return files;
+}
+function walk(root, current, exts, excludeDirs, out) {
+    let entries;
+    try {
+        entries = readdirSync(current);
+    }
+    catch {
+        return; // Directory missing — caller's problem to validate, not ours
+    }
+    for (const entry of entries) {
+        const full = join(current, entry);
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            continue;
+        }
+        if (st.isDirectory()) {
+            const rel = relative(root, full);
+            // Match either the immediate name or the full relative
+            // path so writers can exclude `docs/internal` vs the
+            // basename `internal`.
+            if (excludeDirs.has(entry) || excludeDirs.has(rel))
+                continue;
+            walk(root, full, exts, excludeDirs, out);
+            continue;
+        }
+        if (!st.isFile())
+            continue;
+        const dot = entry.lastIndexOf(".");
+        if (dot < 0)
+            continue;
+        const ext = entry.slice(dot + 1).toLowerCase();
+        if (!exts.has(ext))
+            continue;
+        const html = readFileSync(full, "utf-8");
+        const $ = loadHtml(html);
+        out.push({
+            path: relative(root, full),
+            html,
+            $,
+        });
+    }
+}

package/dist/audit/output/json.js

@@ -0,0 +1,3 @@
+export function formatJson(report) {
+    return JSON.stringify(report, null, 2) + "\n";
+}

package/dist/audit/output/text.js

@@ -0,0 +1,84 @@
+/**
+ * ESLint-style text formatter for audit reports.
+ *
+ * Issues group by file, sorted by file path. Within a file,
+ * issues stay in registration order (the runner already
+ * produces a stable order). Severity gets coloured via
+ * picocolors when stdout is a TTY.
+ *
+ * Sample output:
+ *
+ *   src/content/docs/intro.md
+ *     warning  Description too long (185 chars; max 160)        seo/description-length
+ *     warning  H1 missing — neither frontmatter title nor body  seo/title-missing
+ *
+ *   dist/concepts/seo/index.html
+ *     error    Broken link: /old-name/                          links/dist-internal-links
+ *
+ *   ✖ 3 issues (1 error, 2 warnings) across 2 files
+ */
+import pc from "picocolors";
+export function formatText(report, options = {}) {
+    const useColor = options.color ?? Boolean(process.stdout.isTTY);
+    const tint = useColor ? pc : noColorPc();
+    if (report.issues.length === 0) {
+        const summary = `Clean — ran ${report.summary.rulesRun} rule${report.summary.rulesRun === 1 ? "" : "s"}, no issues found.`;
+        return tint.green(summary) + "\n";
+    }
+    const grouped = new Map();
+    for (const issue of report.issues) {
+        const list = grouped.get(issue.file) ?? [];
+        list.push(issue);
+        grouped.set(issue.file, list);
+    }
+    const files = Array.from(grouped.keys()).sort();
+    const lines = [];
+    for (const file of files) {
+        lines.push(tint.bold(file));
+        const issues = grouped.get(file);
+        const widthSeverity = Math.max(...issues.map((i) => i.severity.length));
+        const widthMessage = Math.max(...issues.map((i) => i.message.length));
+        for (const issue of issues) {
+            const sev = padRight(issue.severity, widthSeverity);
+            const msg = padRight(issue.message, widthMessage + 2);
+            lines.push(`  ${colorSeverity(sev, issue.severity, tint)}  ${msg}${tint.gray(issue.ruleId)}`);
+        }
+        lines.push("");
+    }
+    const { errors, warnings, info, files: nFiles } = report.summary;
+    const total = errors + warnings + info;
+    const parts = [];
+    if (errors > 0)
+        parts.push(`${errors} error${errors === 1 ? "" : "s"}`);
+    if (warnings > 0)
+        parts.push(`${warnings} warning${warnings === 1 ? "" : "s"}`);
+    if (info > 0)
+        parts.push(`${info} info`);
+    const summaryLine = `✖ ${total} issue${total === 1 ? "" : "s"} (${parts.join(", ")}) across ${nFiles} file${nFiles === 1 ? "" : "s"}`;
+    lines.push(errors > 0 ? tint.red(summaryLine) : tint.yellow(summaryLine));
+    return lines.join("\n") + "\n";
+}
+function colorSeverity(text, severity, tint) {
+    switch (severity) {
+        case "error":
+            return tint.red(text);
+        case "warning":
+            return tint.yellow(text);
+        case "info":
+            return tint.blue(text);
+    }
+}
+function padRight(s, width) {
+    return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+/**
+ * picocolors stub that returns the input unchanged. Used when
+ * colour is disabled so callers don't need to branch.
+ */
+function noColorPc() {
+    const id = (s) => s;
+    // Build a Proxy that returns identity for any property access.
+    return new Proxy({}, {
+        get: () => id,
+    });
+}

package/dist/audit/registry.js

@@ -0,0 +1,62 @@
+const REGISTRY = new Map();
+/**
+ * Register a rule. Throws on duplicate id — rule files import
+ * each other only via the index, and double-registration
+ * indicates a copy-paste bug.
+ */
+export function registerRule(rule) {
+    if (REGISTRY.has(rule.id)) {
+        throw new Error(`Duplicate rule registration: ${rule.id}. Rule ids must be unique.`);
+    }
+    REGISTRY.set(rule.id, rule);
+}
+/** All registered rules, in registration order. */
+export function listRules() {
+    return Array.from(REGISTRY.values());
+}
+/** Lookup by exact id, or `undefined` if unknown. */
+export function getRule(id) {
+    return REGISTRY.get(id);
+}
+/** Test-only: clear the registry between tests. Internal use. */
+export function _clearRegistry() {
+    REGISTRY.clear();
+}
+/**
+ * Apply category / stage / explicit / skip filters. Glob patterns
+ * use `*` to match any run of characters within a single segment
+ * (no recursive descent — pattern grammar is intentionally
+ * simple).
+ */
+export function filterRules(options = {}, rules = listRules()) {
+    let out = rules;
+    if (options.rules && options.rules.length > 0) {
+        const patterns = options.rules.map(compileGlob);
+        out = out.filter((r) => patterns.some((re) => re.test(r.id)));
+    }
+    else {
+        if (options.categories && options.categories.length > 0) {
+            const cats = new Set(options.categories);
+            out = out.filter((r) => cats.has(r.category));
+        }
+        if (options.stages && options.stages.length > 0) {
+            const stages = new Set(options.stages);
+            out = out.filter((r) => stages.has(r.stage));
+        }
+    }
+    if (options.skip && options.skip.length > 0) {
+        const skipPatterns = options.skip.map(compileGlob);
+        out = out.filter((r) => !skipPatterns.some((re) => re.test(r.id)));
+    }
+    return out;
+}
+/**
+ * Compile a glob pattern into a regular expression anchored to
+ * full-string match. `*` becomes `.*`. Other regex metacharacters
+ * are escaped so users don't accidentally activate them.
+ */
+function compileGlob(pattern) {
+    const escaped = pattern.replace(/[-/\\^$+?.()|[\]{}]/g, "\\$&");
+    const withWildcard = escaped.replace(/\*/g, ".*");
+    return new RegExp(`^${withWildcard}$`);
+}

package/dist/audit/rules/seo/description-length.js

@@ -0,0 +1,26 @@
+export const DEFAULT_MAX_DESCRIPTION_LENGTH = 160;
+export const descriptionLength = {
+    id: "seo/description-length",
+    category: "seo",
+    stage: "source",
+    severity: "warning",
+    description: "Frontmatter description exceeds the SERP safe-zone length (160 chars).",
+    run(ctx) {
+        const { page } = ctx;
+        const description = page.frontmatter?.["description"];
+        if (typeof description !== "string")
+            return [];
+        const trimmed = description.trim();
+        if (trimmed.length <= DEFAULT_MAX_DESCRIPTION_LENGTH)
+            return [];
+        return [
+            {
+                ruleId: "seo/description-length",
+                severity: "warning",
+                file: page.slug,
+                message: `Description is ${trimmed.length} characters (max ${DEFAULT_MAX_DESCRIPTION_LENGTH}); SERP snippets truncate at ~160.`,
+                context: trimmed.slice(0, 80) + (trimmed.length > 80 ? "…" : ""),
+            },
+        ];
+    },
+};

package/dist/audit/rules/seo/description-missing.js

@@ -0,0 +1,24 @@
+export const descriptionMissing = {
+    id: "seo/description-missing",
+    category: "seo",
+    stage: "source",
+    severity: "warning",
+    description: "Page has no `description` in frontmatter; SERP snippets fall back to extracted body text.",
+    run(ctx) {
+        const { page } = ctx;
+        if (page.redirect)
+            return [];
+        const description = page.frontmatter?.["description"];
+        const hasDescription = typeof description === "string" && description.trim().length > 0;
+        if (hasDescription)
+            return [];
+        return [
+            {
+                ruleId: "seo/description-missing",
+                severity: "warning",
+                file: page.slug,
+                message: "Page has no `description` in frontmatter.",
+            },
+        ];
+    },
+};

package/dist/audit/rules/seo/dist-meta.js

@@ -0,0 +1,65 @@
+export const distMeta = {
+    id: "seo/dist-meta",
+    category: "seo",
+    stage: "dist",
+    severity: "warning",
+    description: "Rendered HTML has the basic SEO meta surface (title, description, OG tags).",
+    run(ctx) {
+        const { file } = ctx;
+        const $ = file.$;
+        const issues = [];
+        // <title>
+        const title = $("head > title").first().text().trim();
+        if (title.length === 0) {
+            issues.push({
+                ruleId: "seo/dist-meta",
+                severity: "error",
+                file: file.path,
+                message: "Page has no <title> element or its content is empty.",
+            });
+        }
+        // <meta name="description">
+        const metaDesc = $('head > meta[name="description"]')
+            .attr("content")
+            ?.trim();
+        if (!metaDesc) {
+            issues.push({
+                ruleId: "seo/dist-meta",
+                severity: "warning",
+                file: file.path,
+                message: 'Page has no <meta name="description"> or its content is empty.',
+            });
+        }
+        // OG type / title / description
+        const ogType = $('head > meta[property="og:type"]').attr("content")?.trim();
+        if (!ogType) {
+            issues.push({
+                ruleId: "seo/dist-meta",
+                severity: "warning",
+                file: file.path,
+                message: 'Page has no <meta property="og:type">.',
+            });
+        }
+        const ogTitle = $('head > meta[property="og:title"]').attr("content")?.trim();
+        if (!ogTitle) {
+            issues.push({
+                ruleId: "seo/dist-meta",
+                severity: "warning",
+                file: file.path,
+                message: 'Page has no <meta property="og:title">.',
+            });
+        }
+        const ogDesc = $('head > meta[property="og:description"]')
+            .attr("content")
+            ?.trim();
+        if (!ogDesc) {
+            issues.push({
+                ruleId: "seo/dist-meta",
+                severity: "warning",
+                file: file.path,
+                message: 'Page has no <meta property="og:description">.',
+            });
+        }
+        return issues;
+    },
+};

package/dist/audit/rules/seo/h1-brand-keyword.js

@@ -0,0 +1,99 @@
+export const h1BrandKeyword = {
+    id: "seo/h1-brand-keyword",
+    category: "seo",
+    stage: "source",
+    severity: "warning",
+    description: "Landing pages include at least one configured brand keyword in their H1.",
+    run(ctx) {
+        const { page, config } = ctx;
+        if (page.redirect)
+            return [];
+        const brandKeywords = config.brandKeywords;
+        if (!Array.isArray(brandKeywords) || brandKeywords.length === 0) {
+            return [];
+        }
+        if (!isLandingPage(page))
+            return [];
+        const fm = page.frontmatter ?? {};
+        const fmTitle = typeof fm["title"] === "string" ? fm["title"] : "";
+        const bodyH1 = extractH1Text(page.tree);
+        const titleText = (bodyH1 || fmTitle).toLowerCase();
+        if (titleText.length === 0) {
+            // No H1 at all — `seo/title-missing` covers this case;
+            // don't double-report.
+            return [];
+        }
+        const matched = brandKeywords.some((kw) => titleText.includes(kw.toLowerCase()));
+        if (matched)
+            return [];
+        const list = brandKeywords.map((k) => `"${k}"`).join(", ");
+        return [
+            {
+                ruleId: "seo/h1-brand-keyword",
+                severity: "warning",
+                file: page.slug,
+                message: `Landing page H1 includes none of the configured brand keywords (${list}).`,
+                context: bodyH1 || fmTitle,
+            },
+        ];
+    },
+};
+function isLandingPage(page) {
+    if (page.slug === "" || page.slug === "index")
+        return true;
+    if (page.meta?.type === "landing")
+        return true;
+    return false;
+}
+function extractH1Text(tree) {
+    if (!tree || tree.length === 0)
+        return "";
+    for (const node of tree) {
+        if (node.type !== "heading")
+            continue;
+        const depth = node.depth;
+        const level = node.props?.level;
+        const isH1 = depth === 1 || level === 1;
+        if (!isH1)
+            continue;
+        if (node.inline)
+            return inlineToText(node.inline).trim();
+        if (node.html)
+            return node.html.trim();
+        return "";
+    }
+    return "";
+}
+function inlineToText(nodes) {
+    let out = "";
+    for (const n of nodes) {
+        switch (n.type) {
+            case "text":
+                out += n.text;
+                break;
+            case "code":
+                out += n.text;
+                break;
+            case "link":
+            case "highlight":
+                out += inlineToText(n.children);
+                break;
+            case "kbd":
+                out += n.keys.join("+");
+                break;
+            case "math":
+                out += n.latex;
+                break;
+            case "image":
+                if (n.alt)
+                    out += n.alt;
+                break;
+            case "break":
+                out += " ";
+                break;
+            default:
+                break;
+        }
+    }
+    return out;
+}

package/dist/audit/rules/seo/index.js

@@ -0,0 +1,63 @@
+/**
+ * SEO rule category — register all `seo/*` rules into the
+ * global registry. Imported once by the audit runner (or the
+ * site-check command) at startup.
+ *
+ * Rules landed in this category:
+ *   - seo/title-missing            (source)
+ *   - seo/description-missing      (source)
+ *   - seo/description-length       (source)
+ *   - seo/keyword-placement        (source, opt-in via frontmatter)
+ *   - seo/h1-brand-keyword         (source, opt-in via site config)
+ *   - seo/dist-meta                (dist)
+ *   - seo/json-ld-parse            (dist)
+ *   - seo/json-ld-required-fields  (dist)
+ *   - seo/sitemap-present          (dist, fires once per run)
+ *   - seo/sitemap-complete         (dist, fires once per run)
+ *   - seo/sitemap-robots-coherence (dist, fires once per run)
+ *
+ * Future additions land here:
+ *   - seo/json-ld-type-coherence   (dist; checks @type matches
+ *                                   meta.type)
+ *   - seo/reciprocal-links         (corpus stage; lands with the
+ *                                   Corpus category PR)
+ */
+import { registerRule } from "../../registry.js";
+import { titleMissing } from "./title-missing.js";
+import { descriptionMissing } from "./description-missing.js";
+import { descriptionLength } from "./description-length.js";
+import { keywordPlacement } from "./keyword-placement.js";
+import { h1BrandKeyword } from "./h1-brand-keyword.js";
+import { distMeta } from "./dist-meta.js";
+import { jsonLdParse } from "./json-ld-parse.js";
+import { jsonLdRequiredFields } from "./json-ld-required-fields.js";
+import { sitemapPresent, sitemapComplete, sitemapRobotsCoherence, } from "./sitemap.js";
+let registered = false;
+/**
+ * Idempotent — calling `registerSeoRules` more than once is a
+ * no-op. Lets callers (CLI, tests) register without coordinating.
+ */
+export function registerSeoRules() {
+    if (registered)
+        return;
+    registered = true;
+    registerRule(titleMissing);
+    registerRule(descriptionMissing);
+    registerRule(descriptionLength);
+    registerRule(keywordPlacement);
+    registerRule(h1BrandKeyword);
+    registerRule(distMeta);
+    registerRule(jsonLdParse);
+    registerRule(jsonLdRequiredFields);
+    registerRule(sitemapPresent);
+    registerRule(sitemapComplete);
+    registerRule(sitemapRobotsCoherence);
+}
+/**
+ * Test-only: reset the "registered" flag so unit tests can
+ * register fresh after `_clearRegistry()`. Production code never
+ * calls this.
+ */
+export function _resetSeoRegistration() {
+    registered = false;
+}

package/dist/audit/rules/seo/json-ld-parse.js

@@ -0,0 +1,32 @@
+export const jsonLdParse = {
+    id: "seo/json-ld-parse",
+    category: "seo",
+    stage: "dist",
+    severity: "error",
+    description: "Every `<script type=\"application/ld+json\">` block parses as valid JSON.",
+    run(ctx) {
+        const { file } = ctx;
+        const $ = file.$;
+        const issues = [];
+        $('script[type="application/ld+json"]').each((_idx, el) => {
+            const raw = $(el).text().trim();
+            if (raw.length === 0) {
+                // Empty block — odd but harmless; skip.
+                return;
+            }
+            try {
+                JSON.parse(raw);
+            }
+            catch (err) {
+                issues.push({
+                    ruleId: "seo/json-ld-parse",
+                    severity: "error",
+                    file: file.path,
+                    message: "JSON-LD block does not parse as valid JSON.",
+                    context: err.message,
+                });
+            }
+        });
+        return issues;
+    },
+};

package/dist/audit/rules/seo/json-ld-required-fields.js

@@ -0,0 +1,116 @@
+/**
+ * Required-fields map per `@type`. Values are the field names
+ * Google's Rich Results validator needs at a minimum. Recommended
+ * fields (e.g. `Article.author`, `Article.image`) live in a
+ * future `seo/json-ld-recommended-fields` rule, not here.
+ */
+const REQUIRED_FIELDS = {
+    Article: ["headline"],
+    TechArticle: ["headline"],
+    HowTo: ["name", "step"],
+    Course: ["name", "description", "provider"],
+    Person: ["name"],
+    Organization: ["name"],
+    BreadcrumbList: ["itemListElement"],
+};
+/** Field that, when present, should be an array (not a scalar). */
+const ARRAY_FIELDS = {
+    HowTo: ["step"],
+    BreadcrumbList: ["itemListElement"],
+};
+export const jsonLdRequiredFields = {
+    id: "seo/json-ld-required-fields",
+    category: "seo",
+    stage: "dist",
+    severity: "warning",
+    description: "JSON-LD blocks declare a recognised @type and carry that type's required fields.",
+    run(ctx) {
+        const { file } = ctx;
+        const $ = file.$;
+        const issues = [];
+        $('script[type="application/ld+json"]').each((idx, el) => {
+            const raw = $(el).text().trim();
+            if (raw.length === 0)
+                return;
+            let parsed;
+            try {
+                parsed = JSON.parse(raw);
+            }
+            catch {
+                // json-ld-parse already flags this; don't double-report.
+                return;
+            }
+            // Allow arrays (`@graph` style) by recursing on each item.
+            const blocks = Array.isArray(parsed) ? parsed : [parsed];
+            for (const block of blocks) {
+                if (typeof block !== "object" || block === null)
+                    continue;
+                validateBlock(block, idx, file.path, issues);
+            }
+        });
+        return issues;
+    },
+};
+function validateBlock(block, blockIndex, file, out) {
+    const atType = block["@type"];
+    if (typeof atType !== "string") {
+        // Either missing or an array (multi-type). Multi-type is
+        // legal Schema.org but uncommon and validation gets tricky;
+        // skip it for v1.
+        if (atType === undefined) {
+            out.push({
+                ruleId: "seo/json-ld-required-fields",
+                severity: "warning",
+                file,
+                message: `JSON-LD block #${blockIndex + 1} has no \`@type\`.`,
+            });
+        }
+        return;
+    }
+    const required = REQUIRED_FIELDS[atType];
+    if (!required) {
+        // Unrecognised @type — pass through. Sites can layer in any
+        // Schema.org type via customJsonLd; we won't fight them.
+        return;
+    }
+    for (const field of required) {
+        if (!(field in block)) {
+            out.push({
+                ruleId: "seo/json-ld-required-fields",
+                severity: "warning",
+                file,
+                message: `JSON-LD ${atType} block missing required field \`${field}\`.`,
+            });
+        }
+        else {
+            const value = block[field];
+            // Empty string / empty array / null all count as missing.
+            if (value === null ||
+                value === "" ||
+                (Array.isArray(value) && value.length === 0)) {
+                out.push({
+                    ruleId: "seo/json-ld-required-fields",
+                    severity: "warning",
+                    file,
+                    message: `JSON-LD ${atType} block has empty required field \`${field}\`.`,
+                });
+            }
+        }
+    }
+    const arrayFields = ARRAY_FIELDS[atType];
+    if (arrayFields) {
+        for (const field of arrayFields) {
+            if (field in block) {
+                const value = block[field];
+                if (!Array.isArray(value)) {
+                    out.push({
+                        ruleId: "seo/json-ld-required-fields",
+                        severity: "warning",
+                        file,
+                        message: `JSON-LD ${atType} field \`${field}\` should be an array, got ${typeof value}.`,
+                    });
+                }
+            }
+        }
+    }
+}