@goflag/cli 0.1.4 → 0.2.0

package/dist/{chunk-3777NRM4.js → chunk-GFM3YN5N.js}

@@ -1217,241 +1217,444 @@ function canonicaliseUrl(href, base, options = {}) {
   return url.toString();
 }
 
+// src/lib/rules/evaluate.ts
+function bandFor(value, bands) {
+  const inside = ([min, max]) => value >= min && value <= max;
+  if (inside(bands.ideal)) return { status: "pass", band: "ideal" };
+  if (inside(bands.acceptable)) return { status: "warn", band: "acceptable" };
+  return { status: "warn", band: "poor" };
+}
+function evaluateRules(extraction, rules) {
+  const findings = [];
+  const crashes = [];
+  for (const rule of rules) {
+    try {
+      if (rule.kind === "boolean") {
+        const verdict = rule.evaluate(extraction);
+        findings.push({
+          ruleId: rule.id,
+          kind: rule.kind,
+          status: verdict.status,
+          severity: verdict.status === "fail" ? rule.severity : void 0,
+          observed: verdict.observed,
+          expected: rule.expected,
+          message: verdict.message,
+          origin: verdict.origin,
+          rigor: rule.rigor,
+          sources: rule.sources
+        });
+      } else {
+        const verdict = rule.evaluate(extraction);
+        findings.push({
+          ruleId: rule.id,
+          kind: rule.kind,
+          status: verdict.status,
+          band: verdict.band,
+          severity: verdict.status === "warn" && verdict.band && verdict.band !== "ideal" ? rule.severityByBand[verdict.band] : void 0,
+          observed: verdict.observed,
+          expected: rule.expected,
+          message: verdict.message,
+          origin: verdict.origin,
+          rigor: rule.rigor,
+          sources: rule.sources
+        });
+      }
+    } catch (err) {
+      crashes.push({
+        ruleId: rule.id,
+        message: err instanceof Error ? err.message : String(err)
+      });
+    }
+  }
+  return { findings, crashes };
+}
+function findingsToIssues(result, rules) {
+  const byId = new Map(rules.map((rule) => [rule.id, rule]));
+  const issues = [];
+  for (const finding of result.findings) {
+    if (finding.status !== "fail" && finding.status !== "warn") continue;
+    issues.push({
+      ruleId: finding.ruleId,
+      severity: finding.severity ?? "info",
+      message: finding.message ?? `Expected ${finding.expected}.`,
+      origin: finding.origin,
+      fix: byId.get(finding.ruleId)?.fix
+    });
+  }
+  for (const crash of result.crashes) {
+    issues.push({
+      ruleId: "engine.rule-crashed",
+      severity: "info",
+      message: `Rule \`${crash.ruleId}\` threw: ${crash.message}`
+    });
+  }
+  return issues;
+}
+
 // src/lib/rules/index.ts
-var TITLE_MIN = 10;
-var TITLE_MAX = 60;
-var DESC_MIN = 50;
-var DESC_MAX = 160;
+var TITLE_IDEAL = [10, 60];
+var TITLE_ACCEPTABLE = [5, 70];
+var DESC_IDEAL = [50, 160];
+var DESC_ACCEPTABLE = [25, 200];
 function tokens(value) {
   if (!value) return [];
   return value.split(",").map((t) => t.trim().toLowerCase()).filter(Boolean);
 }
 var titleMissing = {
   id: "title.missing",
+  kind: "boolean",
+  category: "document",
   severity: "error",
-  summary: "Every page needs a non-empty `<title>`",
-  check: ({ page, issue }) => {
-    const t = page.meta.title?.value?.trim();
-    if (t && t.length > 0) return;
-    return issue({
+  title: "Every page needs a non-empty `<title>`",
+  why: "The title element is required by the HTML standard and is the primary label search engines, browser tabs, bookmarks, and screen readers use for the page.",
+  rigor: "spec-required",
+  sources: ["whatwg-html-title"],
+  reads: ["document.title"],
+  expected: "a non-empty `<title>` element",
+  relates: ["title.length", "og.title.missing"],
+  fix: {
+    title: "Add a <title> to <head>",
+    snippet: [
+      "// app/\u2026/page.tsx \u2014 App Router owns the <head>; never hand-write the tag.",
+      'export const metadata = { title: "Page name \u2014 Site name" };'
+    ].join("\n"),
+    language: "tsx"
+  },
+  evaluate: (ex) => {
+    const observed = ex.document.title?.value?.trim();
+    if (observed) return { status: "pass", observed };
+    return {
+      status: "fail",
+      observed: observed ?? null,
       message: "Page is missing a `<title>` element (or it is empty).",
-      origin: { kind: "title" },
-      fix: {
-        title: "Add a <title> to <head>",
-        snippet: [
-          "// app/\u2026/page.tsx \u2014 App Router owns the <head>; never hand-write the tag.",
-          'export const metadata = { title: "Page name \u2014 Site name" };'
-        ].join("\n"),
-        language: "tsx"
-      }
-    });
+      origin: { kind: "title" }
+    };
   }
 };
 var titleLength = {
   id: "title.length",
-  severity: "warning",
-  summary: `Keep \`<title>\` between ${TITLE_MIN} and ${TITLE_MAX} characters`,
-  check: ({ page, issue }) => {
-    const t = page.meta.title?.value?.trim();
-    if (!t) return;
-    if (t.length >= TITLE_MIN && t.length <= TITLE_MAX) return;
-    const direction = t.length < TITLE_MIN ? "short" : "long";
-    return issue({
-      message: `Title is ${t.length} characters \u2014 ${direction} of the recommended ${TITLE_MIN}\u2013${TITLE_MAX} window.`,
-      origin: { kind: "title" }
+  kind: "scored",
+  category: "document",
+  title: `Keep \`<title>\` between ${TITLE_IDEAL[0]} and ${TITLE_IDEAL[1]} characters`,
+  why: "Long titles get truncated in search results and short ones waste the one line every result gets. The window is display folklore, not spec \u2014 Google states title length is not a ranking factor.",
+  rigor: "heuristic",
+  sources: ["google-title-link", "moz-title-tag"],
+  reads: ["document.title"],
+  bands: { ideal: TITLE_IDEAL, acceptable: TITLE_ACCEPTABLE },
+  severityByBand: { acceptable: "warning", poor: "warning" },
+  expected: `${TITLE_IDEAL[0]}\u2013${TITLE_IDEAL[1]} characters`,
+  relates: ["title.missing"],
+  evaluate: (ex) => {
+    const value = ex.document.title?.value?.trim();
+    if (!value) return { status: "na", observed: 0 };
+    const { status, band } = bandFor(value.length, {
+      ideal: TITLE_IDEAL,
+      acceptable: TITLE_ACCEPTABLE
     });
+    if (status === "pass") return { status, band, observed: value.length };
+    const direction = value.length < TITLE_IDEAL[0] ? "short" : "long";
+    return {
+      status,
+      band,
+      observed: value.length,
+      message: `Title is ${value.length} characters \u2014 ${direction} of the recommended ${TITLE_IDEAL[0]}\u2013${TITLE_IDEAL[1]} window.`,
+      origin: { kind: "title" }
+    };
   }
 };
 var descriptionMissing = {
   id: "description.missing",
+  kind: "boolean",
+  category: "meta",
   severity: "warning",
-  summary: 'Provide a `<meta name="description">` on every indexable page',
-  check: ({ page, issue }) => {
-    const d = page.meta.description?.value?.trim();
-    if (d && d.length > 0) return;
-    return issue({
+  title: 'Provide a `<meta name="description">` on every indexable page',
+  why: "The description feeds the search-result snippet. Without one, engines improvise from page text \u2014 usually worse than a sentence you wrote.",
+  rigor: "spec-recommended",
+  sources: ["whatwg-html-standard-metadata-names", "google-snippet"],
+  reads: ["meta.description"],
+  expected: 'a non-empty `<meta name="description">`',
+  relates: ["description.length", "og.description.missing"],
+  fix: {
+    title: "Add a meta description",
+    snippet: [
+      "// app/\u2026/page.tsx",
+      "export const metadata = {",
+      '  description: "One sentence that promises what this page delivers.",',
+      "};"
+    ].join("\n"),
+    language: "tsx"
+  },
+  evaluate: (ex) => {
+    const observed = ex.meta.description?.value?.trim();
+    if (observed) return { status: "pass", observed };
+    return {
+      status: "fail",
+      observed: observed ?? null,
       message: 'Page has no `<meta name="description">`.',
-      origin: { kind: "meta", name: "description" },
-      fix: {
-        title: "Add a meta description",
-        snippet: [
-          "// app/\u2026/page.tsx",
-          "export const metadata = {",
-          '  description: "One sentence that promises what this page delivers.",',
-          "};"
-        ].join("\n"),
-        language: "tsx"
-      }
-    });
+      origin: { kind: "meta", name: "description" }
+    };
   }
 };
 var descriptionLength = {
   id: "description.length",
-  severity: "warning",
-  summary: `Keep descriptions between ${DESC_MIN} and ${DESC_MAX} characters`,
-  check: ({ page, issue }) => {
-    const d = page.meta.description?.value?.trim();
-    if (!d) return;
-    if (d.length >= DESC_MIN && d.length <= DESC_MAX) return;
-    const direction = d.length < DESC_MIN ? "short" : "long";
-    return issue({
-      message: `Description is ${d.length} characters \u2014 ${direction} of the recommended ${DESC_MIN}\u2013${DESC_MAX} window.`,
-      origin: { kind: "meta", name: "description" }
+  kind: "scored",
+  category: "meta",
+  title: `Keep descriptions between ${DESC_IDEAL[0]} and ${DESC_IDEAL[1]} characters`,
+  why: "Snippets truncate around 160 characters and very short descriptions get replaced by improvised page text. Display folklore, not spec.",
+  rigor: "heuristic",
+  sources: ["google-snippet", "moz-meta-description"],
+  reads: ["meta.description"],
+  bands: { ideal: DESC_IDEAL, acceptable: DESC_ACCEPTABLE },
+  severityByBand: { acceptable: "warning", poor: "warning" },
+  expected: `${DESC_IDEAL[0]}\u2013${DESC_IDEAL[1]} characters`,
+  relates: ["description.missing"],
+  evaluate: (ex) => {
+    const value = ex.meta.description?.value?.trim();
+    if (!value) return { status: "na", observed: 0 };
+    const { status, band } = bandFor(value.length, {
+      ideal: DESC_IDEAL,
+      acceptable: DESC_ACCEPTABLE
     });
+    if (status === "pass") return { status, band, observed: value.length };
+    const direction = value.length < DESC_IDEAL[0] ? "short" : "long";
+    return {
+      status,
+      band,
+      observed: value.length,
+      message: `Description is ${value.length} characters \u2014 ${direction} of the recommended ${DESC_IDEAL[0]}\u2013${DESC_IDEAL[1]} window.`,
+      origin: { kind: "meta", name: "description" }
+    };
   }
 };
 var canonicalMissing = {
   id: "canonical.missing",
+  kind: "boolean",
+  category: "canonical",
   severity: "warning",
-  summary: 'Declare a `<link rel="canonical">` so search engines pick the right URL',
-  check: ({ page, issue }) => {
-    if (page.links.canonical) return;
-    return issue({
+  title: 'Declare a `<link rel="canonical">` so search engines pick the right URL',
+  why: "Without a canonical, engines choose among duplicate URLs (tracking params, http/https, trailing slashes) themselves \u2014 and may split ranking signals across them.",
+  rigor: "vendor-spec",
+  sources: ["ietf-rfc6596", "google-canonicalization"],
+  reads: ["meta.canonical"],
+  expected: 'a `<link rel="canonical">` declaration',
+  relates: ["canonical.absolute"],
+  fix: {
+    title: "Declare the canonical URL",
+    snippet: [
+      "// app/\u2026/page.tsx \u2014 relative canonicals resolve against metadataBase,",
+      "// which defaults to localhost and silently breaks in production.",
+      "export const metadata = {",
+      "  metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL!),",
+      '  alternates: { canonical: "/the-page" },',
+      "};"
+    ].join("\n"),
+    language: "tsx"
+  },
+  evaluate: (ex) => {
+    const observed = ex.meta.canonical?.value;
+    if (observed) return { status: "pass", observed };
+    return {
+      status: "fail",
+      observed: null,
       message: 'Page is missing `<link rel="canonical">`.',
-      origin: { kind: "link", rel: "canonical" },
-      fix: {
-        title: "Declare the canonical URL",
-        snippet: [
-          "// app/\u2026/page.tsx \u2014 relative canonicals resolve against metadataBase,",
-          "// which defaults to localhost and silently breaks in production.",
-          "export const metadata = {",
-          "  metadataBase: new URL(process.env.NEXT_PUBLIC_SITE_URL!),",
-          '  alternates: { canonical: "/the-page" },',
-          "};"
-        ].join("\n"),
-        language: "tsx"
-      }
-    });
+      origin: { kind: "link", rel: "canonical" }
+    };
   }
 };
 var canonicalAbsolute = {
   id: "canonical.absolute",
+  kind: "boolean",
+  category: "canonical",
   severity: "error",
-  summary: '`rel="canonical"` must be an absolute, fully-qualified URL',
-  check: ({ page, issue }) => {
-    const link = page.raw.links.find((l) => l.rel.toLowerCase() === "canonical");
-    const raw = link?.href?.trim();
-    if (!raw) return;
-    if (/^https?:\/\//i.test(raw)) return;
-    return issue({
-      message: `Canonical is "${raw}" \u2014 must be an absolute http(s) URL (consumers see the raw value, not the resolved "${page.links.canonical ?? raw}").`,
+  title: '`rel="canonical"` must be an absolute, fully-qualified URL',
+  why: "Consumers read the literal attribute value, not the browser-resolved URL. A relative canonical means every consumer resolves it against whatever base it assumes \u2014 including the wrong origin.",
+  rigor: "vendor-spec",
+  sources: ["ietf-rfc6596", "google-canonicalization", "whatwg-url"],
+  reads: ["meta.canonical"],
+  expected: "an absolute `http(s)://` canonical URL",
+  relates: ["canonical.missing"],
+  evaluate: (ex) => {
+    const canonical = ex.meta.canonical;
+    const raw = canonical?.raw?.trim();
+    if (!raw) return { status: "na", observed: null };
+    if (/^https?:\/\//i.test(raw)) return { status: "pass", observed: raw };
+    return {
+      status: "fail",
+      observed: raw,
+      message: `Canonical is "${raw}" \u2014 must be an absolute http(s) URL (consumers see the raw value, not the resolved "${canonical?.value ?? raw}").`,
       origin: { kind: "link", rel: "canonical" }
-    });
+    };
   }
 };
 var viewportMissing = {
   id: "viewport.missing",
+  kind: "boolean",
+  category: "meta",
   severity: "warning",
-  summary: 'Declare a `<meta name="viewport">` so mobile browsers render at the right scale',
-  check: ({ page, issue }) => {
-    const v = page.meta.viewport?.value?.trim();
-    if (v && v.length > 0) return;
-    return issue({
+  title: 'Declare a `<meta name="viewport">` so mobile browsers render at the right scale',
+  why: "Without a viewport declaration mobile browsers render at desktop width and scale down \u2014 unreadable text and a mobile-usability demotion.",
+  rigor: "guideline",
+  sources: ["mdn-viewport", "whatwg-html-standard-metadata-names"],
+  reads: ["meta.viewport"],
+  expected: 'a `<meta name="viewport">` declaration',
+  fix: {
+    title: "Add a viewport meta",
+    snippet: [
+      "// app/layout.tsx \u2014 a dedicated export, not part of `metadata`.",
+      'export const viewport = { width: "device-width", initialScale: 1 };'
+    ].join("\n"),
+    language: "tsx"
+  },
+  evaluate: (ex) => {
+    const observed = ex.meta.viewport?.value?.trim();
+    if (observed) return { status: "pass", observed };
+    return {
+      status: "fail",
+      observed: null,
       message: 'Page has no `<meta name="viewport">` \u2014 mobile browsers will render at desktop width.',
-      origin: { kind: "meta", name: "viewport" },
-      fix: {
-        title: "Add a viewport meta",
-        snippet: [
-          "// app/layout.tsx \u2014 a dedicated export, not part of `metadata`.",
-          'export const viewport = { width: "device-width", initialScale: 1 };'
-        ].join("\n"),
-        language: "tsx"
-      }
-    });
+      origin: { kind: "meta", name: "viewport" }
+    };
   }
 };
 var ogTitleMissing = {
   id: "og.title.missing",
+  kind: "boolean",
+  category: "opengraph",
   severity: "warning",
-  summary: "Set an explicit `og:title` instead of relying on `<title>` fallback",
-  check: ({ page, issue }) => {
-    if (page.openGraph.title?.value?.trim()) return;
-    return issue({
+  title: "Set an explicit `og:title` instead of relying on `<title>` fallback",
+  why: "og:title is one of the four properties the Open Graph protocol requires. Consumers that fall back to `<title>` drag site-name boilerplate into the unfurl.",
+  rigor: "vendor-spec",
+  sources: ["ogp"],
+  reads: ["openGraph.title"],
+  expected: "an explicit `og:title`",
+  relates: ["title.missing", "og.image.missing"],
+  evaluate: (ex) => {
+    const observed = ex.openGraph.title?.value?.trim();
+    if (observed) return { status: "pass", observed };
+    return {
+      status: "fail",
+      observed: null,
       message: "Page has no `og:title`; consumers will fall back to `<title>` (or nothing).",
       origin: { kind: "meta", property: "og:title" }
-    });
+    };
   }
 };
 var ogDescriptionMissing = {
   id: "og.description.missing",
+  kind: "boolean",
+  category: "opengraph",
   severity: "info",
-  summary: "Set an explicit `og:description` for richer link unfurls",
-  check: ({ page, issue }) => {
-    if (page.openGraph.description?.value?.trim()) return;
+  title: "Set an explicit `og:description` for richer link unfurls",
+  why: "A page that opted into Open Graph but omitted og:description gets unfurls that fall back to the meta description \u2014 or to nothing.",
+  rigor: "vendor-spec",
+  sources: ["ogp", "meta-og-sharing"],
+  reads: ["openGraph.description", "openGraph.title", "openGraph.images", "openGraph.url"],
+  expected: "an `og:description` alongside the other `og:*` tags",
+  relates: ["description.missing"],
+  evaluate: (ex) => {
+    const observed = ex.openGraph.description?.value?.trim();
+    if (observed) return { status: "pass", observed };
     const hasOtherOg = Boolean(
-      page.openGraph.title?.value || page.openGraph.images.length > 0 || page.openGraph.url?.value
+      ex.openGraph.title?.value || ex.openGraph.images.length > 0 || ex.openGraph.url?.value
     );
-    if (!hasOtherOg) return;
-    return issue({
+    if (!hasOtherOg) return { status: "na", observed: null };
+    return {
+      status: "fail",
+      observed: null,
       message: "Page has `og:*` tags but no `og:description`; unfurls will fall back to the meta description (or nothing).",
       origin: { kind: "meta", property: "og:description" }
-    });
+    };
   }
 };
 var ogImageMissing = {
   id: "og.image.missing",
+  kind: "boolean",
+  category: "opengraph",
   severity: "warning",
-  summary: "Provide at least one `og:image` so links unfurl with a preview",
-  check: ({ page, issue }) => {
-    if (page.openGraph.images.length > 0) return;
-    return issue({
+  title: "Provide at least one `og:image` so links unfurl with a preview",
+  why: "og:image is one of the four required Open Graph properties, and the one with the most visible payoff: without it, unfurls are text-only or pick a random body image.",
+  rigor: "vendor-spec",
+  sources: ["ogp", "meta-og-sharing"],
+  reads: ["openGraph.images"],
+  expected: "at least one `og:image`",
+  relates: ["og.title.missing"],
+  fix: {
+    title: "Add an og:image",
+    snippet: [
+      "// app/\u2026/page.tsx",
+      "export const metadata = {",
+      '  openGraph: { images: [{ url: "/og.png", width: 1200, height: 630 }] },',
+      "};",
+      "// Or generate one per page: app/\u2026/opengraph-image.tsx with ImageResponse."
+    ].join("\n"),
+    language: "tsx"
+  },
+  evaluate: (ex) => {
+    if (ex.openGraph.images.length > 0) {
+      return { status: "pass", observed: ex.openGraph.images.map((i) => i.url.value) };
+    }
+    return {
+      status: "fail",
+      observed: [],
       message: "Page has no `og:image`. Link unfurls will fall back to text-only or a random body image.",
-      origin: { kind: "meta", property: "og:image" },
-      fix: {
-        title: "Add an og:image",
-        snippet: [
-          "// app/\u2026/page.tsx",
-          "export const metadata = {",
-          '  openGraph: { images: [{ url: "/og.png", width: 1200, height: 630 }] },',
-          "};",
-          "// Or generate one per page: app/\u2026/opengraph-image.tsx with ImageResponse."
-        ].join("\n"),
-        language: "tsx"
-      }
-    });
+      origin: { kind: "meta", property: "og:image" }
+    };
   }
 };
 var robotsConflict = {
   id: "robots.conflict",
+  kind: "boolean",
+  category: "robots",
   severity: "error",
-  summary: "`robots`, `googlebot`, and `X-Robots-Tag` must not contradict each other",
-  check: ({ page, issue }) => {
-    const issues = [];
-    const metaRobots = new Set(tokens(page.meta.robots?.value));
-    const metaGoogle = new Set(tokens(page.meta.googlebot?.value));
-    const header = new Set(tokens(page.fetch.headers["x-robots-tag"]));
-    const allSources = [
-      { name: "meta robots", tokens: metaRobots, origin: { kind: "meta", name: "robots" } },
-      { name: "meta googlebot", tokens: metaGoogle, origin: { kind: "meta", name: "googlebot" } },
+  title: "`robots`, `googlebot`, and `X-Robots-Tag` must not contradict each other",
+  why: "When directives conflict, crawlers resolve them with the most restrictive interpretation \u2014 a stray `noindex` wins over the `index` you meant, and the page silently drops out of search.",
+  rigor: "vendor-spec",
+  sources: ["google-robots-meta"],
+  reads: ["meta.robots", "meta.googlebot", "http.headers"],
+  expected: "consistent indexing directives across meta tags and headers",
+  evaluate: (ex) => {
+    const candidates = [
+      {
+        name: "meta robots",
+        tokens: new Set(tokens(ex.meta.robots?.value)),
+        origin: { kind: "meta", name: "robots" }
+      },
+      {
+        name: "meta googlebot",
+        tokens: new Set(tokens(ex.meta.googlebot?.value)),
+        origin: { kind: "meta", name: "googlebot" }
+      },
       {
         name: "X-Robots-Tag header",
-        tokens: header,
+        tokens: new Set(tokens(ex.http.headers["x-robots-tag"])),
         origin: { kind: "header", name: "x-robots-tag" }
       }
     ];
-    const sources = allSources.filter((s) => s.tokens.size > 0);
-    if (sources.length < 2) return [];
-    const indexers = sources.filter((s) => s.tokens.has("index") && !s.tokens.has("noindex"));
-    const noindexers = sources.filter((s) => s.tokens.has("noindex"));
-    if (indexers.length > 0 && noindexers.length > 0) {
-      issues.push(
-        issue({
-          message: `Conflicting indexing directives: ${noindexers.map((s) => s.name).join(", ")} say \`noindex\`, ${indexers.map((s) => s.name).join(", ")} say \`index\`.`,
-          origin: noindexers[0].origin
-        })
-      );
-    }
-    const followers = sources.filter((s) => s.tokens.has("follow") && !s.tokens.has("nofollow"));
-    const nofollowers = sources.filter((s) => s.tokens.has("nofollow"));
-    if (followers.length > 0 && nofollowers.length > 0) {
-      issues.push(
-        issue({
-          message: `Conflicting follow directives: ${nofollowers.map((s) => s.name).join(", ")} say \`nofollow\`, ${followers.map((s) => s.name).join(", ")} say \`follow\`.`,
-          origin: nofollowers[0].origin
-        })
-      );
+    const declarations = candidates.filter((d) => d.tokens.size > 0);
+    const observed = Object.fromEntries(declarations.map((d) => [d.name, [...d.tokens].sort()]));
+    if (declarations.length < 2) return { status: "na", observed };
+    const conflicts = [];
+    let origin;
+    for (const [negative, positive] of [
+      ["noindex", "index"],
+      ["nofollow", "follow"]
+    ]) {
+      const sayNo = declarations.filter((d) => d.tokens.has(negative));
+      const sayYes = declarations.filter((d) => d.tokens.has(positive) && !d.tokens.has(negative));
+      if (sayNo.length > 0 && sayYes.length > 0) {
+        conflicts.push(
+          `${sayNo.map((d) => d.name).join(", ")} say \`${negative}\`, ${sayYes.map((d) => d.name).join(", ")} say \`${positive}\``
+        );
+        origin ??= sayNo[0].origin;
+      }
     }
-    return issues;
+    if (conflicts.length === 0) return { status: "pass", observed };
+    return {
+      status: "fail",
+      observed,
+      message: `Conflicting robots directives: ${conflicts.join("; ")}.`,
+      origin
+    };
   }
 };
 var RULES = [
@@ -1468,8 +1671,99 @@ var RULES = [
   viewportMissing
 ];
 var RULE_BY_ID = new Map(RULES.map((r) => [r.id, r]));
-function getRule(id) {
-  return RULE_BY_ID.get(id);
+
+// src/lib/rules/extraction/types.ts
+var EXTRACTION_VERSION = 1;
+
+// src/lib/rules/extraction/from-page.ts
+function htmlFact(value, attribute) {
+  if (value === void 0) return void 0;
+  return { value, origin: { kind: "html", attribute }, raw: value };
+}
+function documentFromPage(page) {
+  return {
+    title: page.meta.title,
+    lang: htmlFact(page.raw.htmlLang, "lang"),
+    dir: htmlFact(page.raw.htmlDir, "dir"),
+    charset: page.meta.charset,
+    // `<base>` is an element, not an attribute of `<html>`; `TagOrigin` has
+    // no dedicated kind for it, so the origin names the element instead.
+    base: htmlFact(page.raw.baseHref, "base")
+  };
+}
+function openGraphFromPage(page) {
+  const og = page.openGraph;
+  return {
+    title: og.title,
+    type: og.type,
+    url: og.url,
+    description: og.description,
+    siteName: og.siteName,
+    locale: og.locale,
+    localeAlternates: og.localeAlternates,
+    images: og.images,
+    other: og.unknown
+  };
+}
+function linksFromPage(page) {
+  return {
+    hreflang: page.links.alternates,
+    icons: page.links.icons,
+    manifest: page.links.manifest ? { href: page.links.manifest.href } : void 0,
+    feeds: page.links.feeds.map(({ type, href, title }) => ({ type, href, title }))
+  };
+}
+function extractionFromPage(page) {
+  return {
+    extractionVersion: EXTRACTION_VERSION,
+    fetchedAt: page.fetchedAt,
+    http: {
+      requestedUrl: page.fetch.requestedUrl,
+      finalUrl: page.fetch.finalUrl,
+      status: page.fetch.status,
+      headers: page.fetch.headers,
+      redirects: page.fetch.redirectCount,
+      contentType: page.fetch.contentType
+    },
+    rendering: {
+      mode: page.extractor.mode,
+      escalated: page.extractor.escalated,
+      escalationReason: page.extractor.escalationReason
+    },
+    document: documentFromPage(page),
+    meta: {
+      description: page.meta.description,
+      viewport: page.meta.viewport,
+      robots: page.meta.robots,
+      googlebot: page.meta.googlebot,
+      canonical: page.meta.canonical,
+      themeColor: page.meta.themeColor,
+      colorScheme: page.meta.colorScheme,
+      referrer: page.meta.referrer,
+      generator: page.meta.generator,
+      applicationName: page.meta.applicationName,
+      author: page.meta.author,
+      keywords: page.meta.keywords
+    },
+    openGraph: openGraphFromPage(page),
+    twitter: {
+      card: page.twitter.card,
+      site: page.twitter.site,
+      creator: page.twitter.creator,
+      title: page.twitter.title,
+      description: page.twitter.description,
+      image: page.twitter.image,
+      imageAlt: page.twitter.imageAlt
+    },
+    links: linksFromPage(page),
+    jsonLd: page.jsonLd.map(({ index, types, data, parseError, raw }) => ({
+      index,
+      types,
+      data,
+      parseError,
+      raw
+    }))
+  };
 }
 
 // src/lib/core/lint.ts
@@ -1478,37 +1772,6 @@ var SEVERITY_RANK = {
   warning: 1,
   info: 2
 };
-function lint(page, rules = RULES) {
-  const issues = [];
-  for (const rule of rules) {
-    if (rule.appliesTo && !rule.appliesTo(page)) continue;
-    let result;
-    try {
-      result = rule.check({
-        page,
-        issue: (input) => ({
-          ruleId: rule.id,
-          severity: input.severity ?? rule.severity,
-          message: input.message,
-          origin: input.origin,
-          fix: input.fix,
-          suggestion: input.suggestion
-        })
-      });
-    } catch (err) {
-      issues.push({
-        ruleId: "engine.rule-crashed",
-        severity: "info",
-        message: `Rule \`${rule.id}\` threw: ${err instanceof Error ? err.message : String(err)}`
-      });
-      continue;
-    }
-    if (!result) continue;
-    if (Array.isArray(result)) issues.push(...result);
-    else issues.push(result);
-  }
-  return sortIssues(issues);
-}
 function sortIssues(issues) {
   return [...issues].sort((a, b) => {
     const sev = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
@@ -2222,6 +2485,168 @@ function relaxTlsIfRequested2(enabled) {
   };
 }
 
+// src/lib/rules/advisory.ts
+function resolveEvidencePath(extraction, path) {
+  let current = extraction;
+  for (const segment of path.split(".")) {
+    if (current === null || current === void 0) return null;
+    if (typeof current !== "object") return null;
+    current = current[segment];
+  }
+  return current ?? null;
+}
+function evidenceFor(extraction, paths) {
+  const bundle = {};
+  for (const path of paths) bundle[path] = resolveEvidencePath(extraction, path);
+  return bundle;
+}
+function collectAdvisories(extraction, rules) {
+  return rules.filter((rule) => rule.appliesTo?.(extraction) ?? true).map((rule) => ({
+    ruleId: rule.id,
+    kind: "prose",
+    prose: rule.prose,
+    rigor: rule.rigor,
+    sources: rule.sources,
+    evidence: evidenceFor(extraction, rule.reads),
+    verdict: "needs-judgment"
+  }));
+}
+
+// src/lib/rules/profiles/index.ts
+var DEFAULT_PROFILE = "default";
+var PROFILES = {
+  default: {
+    name: "default",
+    description: "rule severities exactly as authored"
+  },
+  strict: {
+    name: "strict",
+    description: "every spec-backed rule fails the build",
+    // The line is drawn at "is there a document that says so", not at "does
+    // it feel important". Heuristics stay warnings even here — promoting
+    // SERP-length folklore to an error would be exactly the dishonesty the
+    // rigor axis exists to prevent.
+    byRigor: {
+      "spec-required": { severity: "error" },
+      "spec-recommended": { severity: "error" },
+      "vendor-spec": { severity: "error" },
+      guideline: { severity: "warning" },
+      heuristic: { severity: "warning" }
+    }
+  },
+  "spec-only": {
+    name: "spec-only",
+    description: "heuristic rules switched off entirely",
+    // Not a severity change: a heuristic finding is switched off, so it is
+    // absent from the conformance view rather than sitting there as a
+    // suspiciously quiet `pass`.
+    byRigor: {
+      heuristic: { enabled: false }
+    }
+  },
+  marketing: {
+    name: "marketing",
+    description: "snippet and unfurl metadata gaps are errors",
+    // The recommended/optional distinction inverts for a page whose job is
+    // to be shared: a missing description or preview image costs a click,
+    // whatever the spec calls it.
+    rules: {
+      "description.missing": { severity: "error" },
+      "description.length": { severity: "warning" },
+      "og.title.missing": { severity: "error" },
+      "og.image.missing": { severity: "error" },
+      "og.description.missing": { severity: "warning" }
+    }
+  }
+};
+var PROFILE_NAMES = Object.keys(PROFILES);
+function resolveProfile(name = DEFAULT_PROFILE) {
+  const profile = PROFILES[name];
+  if (!profile) {
+    throw new Error(`unknown profile "${name}" \u2014 expected one of: ${PROFILE_NAMES.join(", ")}`);
+  }
+  return profile;
+}
+function overrideFor(rule, profile) {
+  return { ...profile.byRigor?.[rule.rigor], ...profile.rules?.[rule.id] };
+}
+function withSeverity(rule, severity) {
+  if (rule.kind === "boolean") return { ...rule, severity };
+  return { ...rule, severityByBand: { acceptable: severity, poor: severity } };
+}
+function applyProfile(rules, profile) {
+  const effective = [];
+  for (const rule of rules) {
+    const override = overrideFor(rule, profile);
+    if (override.enabled === false) continue;
+    effective.push(override.severity ? withSeverity(rule, override.severity) : rule);
+  }
+  return effective;
+}
+function rulesForProfile(name, rules = RULES) {
+  return applyProfile(rules, resolveProfile(name));
+}
+
+// src/lib/rules/prose.ts
+var titleDescriptive = {
+  id: "title.descriptive",
+  kind: "prose",
+  category: "document",
+  title: "The `<title>` describes this specific page",
+  why: "A title that repeats the site name, or describes the section rather than the page, gives a searcher no way to tell two results apart \u2014 and gives Google a reason to rewrite it into something you did not choose.",
+  rigor: "guideline",
+  sources: ["google-title-link", "bing-webmaster-guidelines"],
+  reads: ["document.title", "meta.description", "openGraph.title", "http.finalUrl"],
+  relates: ["title.missing", "title.length"],
+  appliesTo: (ex) => Boolean(ex.document.title?.value?.trim()),
+  prose: "Does the title describe what is on THIS page specifically \u2014 not the site, not the section \u2014 and would it be distinguishable from the other pages of this site in a list of search results?"
+};
+var descriptionAccurate = {
+  id: "description.accurate",
+  kind: "prose",
+  category: "meta",
+  title: "The meta description summarizes this page truthfully",
+  why: "The description is the one sentence you get to write in a search result. A boilerplate line repeated site-wide, or one that promises something the page does not deliver, gets replaced by improvised page text \u2014 or gets the click and loses the visitor.",
+  rigor: "guideline",
+  sources: ["google-snippet", "moz-meta-description"],
+  reads: ["meta.description", "document.title", "http.finalUrl"],
+  relates: ["description.missing", "description.length"],
+  appliesTo: (ex) => Boolean(ex.meta.description?.value?.trim()),
+  prose: "Does the description accurately summarize this page's content, and is it written for this page rather than copied across the site?"
+};
+var langMatchesContent = {
+  id: "lang.matches-content",
+  kind: "prose",
+  category: "i18n",
+  title: "The declared `lang` is the language the page is actually written in",
+  why: "A wrong `lang` is worse than a missing one: screen readers switch to the wrong pronunciation rules, browsers offer to translate a page that is already in the reader's language, and search engines file the page under the wrong audience. Nothing in the markup contradicts it, so no mechanical check can catch it.",
+  rigor: "spec-required",
+  sources: ["whatwg-html-lang", "w3c-i18n-language-tags"],
+  reads: ["document.lang", "document.title", "meta.description", "openGraph.locale"],
+  appliesTo: (ex) => Boolean(ex.document.lang?.value?.trim()),
+  prose: "Is the text of this page actually written in the language its `lang` attribute declares?"
+};
+var ogImageRepresentative = {
+  id: "og.image.representative",
+  kind: "prose",
+  category: "opengraph",
+  title: "The `og:image` represents this page and survives the unfurl crop",
+  why: "The preview image is the whole payload of a shared link. A generic site-wide banner, or artwork whose subject sits outside the ~1.91:1 crop, is present enough to pass every mechanical check and still communicate nothing.",
+  rigor: "guideline",
+  sources: ["ogp", "meta-og-sharing"],
+  reads: ["openGraph.images", "openGraph.title", "document.title", "http.finalUrl"],
+  relates: ["og.image.missing"],
+  appliesTo: (ex) => ex.openGraph.images.length > 0,
+  prose: "Does the og:image represent what this page is about, rather than being a site-wide default, and does its subject survive being cropped to the 1.91:1 aspect ratio consumers render?"
+};
+var PROSE_RULES = [
+  descriptionAccurate,
+  langMatchesContent,
+  ogImageRepresentative,
+  titleDescriptive
+];
+var PROSE_RULE_BY_ID = new Map(PROSE_RULES.map((r) => [r.id, r]));
+
 // src/lib/core/net/fetch-url.ts
 var DEFAULT_USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0.0.0 Safari/537.36";
 var DEFAULT_TIMEOUT_MS = 8e3;
@@ -2858,6 +3283,38 @@ function normalizeInputUrl(input) {
   return { ok: true, url: candidate };
 }
 
+// src/report/conformance.ts
+function buildConformance(rules, rows) {
+  const totals = new Map(
+    rules.map((rule) => [rule.id, { pass: 0, fail: 0, warn: 0, na: 0, crashed: 0 }])
+  );
+  const pages = rows.map((row) => {
+    const statuses = {};
+    const seen = /* @__PURE__ */ new Set();
+    for (const finding of row.findings) {
+      const tally = totals.get(finding.ruleId);
+      if (!tally) continue;
+      statuses[finding.ruleId] = finding.status;
+      tally[finding.status] += 1;
+      seen.add(finding.ruleId);
+    }
+    for (const rule of rules) if (!seen.has(rule.id)) totals.get(rule.id).crashed += 1;
+    return { url: row.pageUrl, statuses };
+  });
+  return {
+    rules: rules.map((rule) => ({
+      ruleId: rule.id,
+      kind: rule.kind,
+      title: rule.title,
+      rigor: rule.rigor,
+      sources: rule.sources,
+      expected: rule.expected,
+      totals: totals.get(rule.id)
+    })),
+    pages
+  };
+}
+
 // src/report/build.ts
 function isOkStatus(status) {
   return status >= 200 && status < 300;
@@ -2933,6 +3390,8 @@ async function runAudit(inputUrl, options = {}) {
   const depth = options.depth ?? 2;
   const maxPages = options.maxPages ?? 200;
   const checkExternal = options.checkExternal !== false;
+  const profile = options.profile ?? DEFAULT_PROFILE;
+  const rules = rulesForProfile(profile);
   const discovery = options.noSitemap ? void 0 : await discoverSitemap(entry, {
     signal: options.signal,
     timeoutMs: options.timeoutMs,
@@ -2977,20 +3436,37 @@ async function runAudit(inputUrl, options = {}) {
     status: p.fetch.status
   }));
   const seoIssues = [];
+  const conformanceRows = [];
+  const advisories = [];
+  const ruleById = new Map(rules.map((rule) => [rule.id, rule]));
   for (const page of htmlPages) {
     const pageUrl = page.fetch.finalUrl;
+    const extraction = extractionFromPage(page);
+    const evaluation = evaluateRules(extraction, rules);
+    if (options.conformance) {
+      conformanceRows.push({ pageUrl, findings: evaluation.findings });
+    }
+    if (options.advisories) {
+      for (const advisory of collectAdvisories(extraction, PROSE_RULES)) {
+        advisories.push({
+          ...advisory,
+          id: fingerprint("advisory", advisory.ruleId, routeKey(pageUrl)),
+          pageUrl
+        });
+      }
+    }
     const occurrence = /* @__PURE__ */ new Map();
-    for (const issue of lint(page)) {
+    for (const issue of sortIssues(findingsToIssues(evaluation, rules))) {
       const n = occurrence.get(issue.ruleId) ?? 0;
       occurrence.set(issue.ruleId, n + 1);
-      const rule = getRule(issue.ruleId);
+      const rule = ruleById.get(issue.ruleId);
       seoIssues.push({
         id: fingerprint("seo", issue.ruleId, routeKey(pageUrl), String(n)),
         pageUrl,
         ruleId: issue.ruleId,
         severity: issue.severity,
         message: issue.message,
-        why: rule?.summary,
+        why: rule?.title,
         fix: issue.fix?.snippet
       });
     }
@@ -3104,6 +3580,7 @@ async function runAudit(inputUrl, options = {}) {
   return {
     url: entry,
     finishedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    profile,
     summary: {
       brokenLinks: brokenCount,
       missingTranslations,
@@ -3128,6 +3605,12 @@ async function runAudit(inputUrl, options = {}) {
     missingTranslations: { holes, reciprocity },
     seoIssues,
     siteIssues,
+    // Both sections are omitted entirely when not asked for, rather than
+    // emitted empty: an empty `advisories: []` would read as "no prose rule
+    // has anything to ask about this site", which is a claim goflag has not
+    // made.
+    ...options.conformance ? { conformance: buildConformance(rules, conformanceRows) } : {},
+    ...options.advisories ? { advisories } : {},
     diagnostics: {
       pagesCrawled: pages.length,
       pagesScanned: linkReport.pagesScanned,
@@ -3206,7 +3689,10 @@ function renderTerminal(report, options = {}) {
   lines.push(
     `${c(verdictColor(report.summary.verdict), VERDICT_FLAG[report.summary.verdict].toUpperCase())}  ` + c(
       ANSI.dim,
-      `${report.diagnostics.pagesCrawled} pages crawled, ${report.diagnostics.pagesScanned} scanned`
+      `${report.diagnostics.pagesCrawled} pages crawled, ${report.diagnostics.pagesScanned} scanned` + // Named only when it is not the default. A run under `spec-only`
+      // that prints "0 SEO issues" without saying so reads as a clean
+      // site rather than a narrowed one.
+      (report.profile === DEFAULT_PROFILE ? "" : `, profile ${report.profile}`)
     )
   );
   lines.push("");
@@ -3276,6 +3762,36 @@ function renderTerminal(report, options = {}) {
     lines.push(...renderIssuesByPage(report.siteIssues, c));
     lines.push("");
   }
+  if (report.conformance) {
+    lines.push(c(ANSI.bold, "Conformance"));
+    const judged = report.conformance.pages.length;
+    lines.push(c(ANSI.dim, `  ${judged} page${judged === 1 ? "" : "s"} judged \xD7 every rule`));
+    for (const rule of report.conformance.rules) {
+      const { pass, fail, warn, na, crashed } = rule.totals;
+      const tally = [
+        fail > 0 ? c(ANSI.red, `${fail} fail`) : null,
+        warn > 0 ? c(ANSI.yellow, `${warn} warn`) : null,
+        pass > 0 ? c(ANSI.green, `${pass} pass`) : null,
+        na > 0 ? c(ANSI.dim, `${na} n/a`) : null,
+        crashed > 0 ? c(ANSI.red, `${crashed} crashed`) : null
+      ].filter(Boolean);
+      lines.push(
+        `  ${c(ANSI.cyan, rule.ruleId.padEnd(24))} ${tally.join(c(ANSI.dim, " \xB7 "))}` + c(ANSI.dim, `  [${rule.rigor}]`)
+      );
+    }
+    lines.push("");
+  }
+  if (report.advisories && report.advisories.length > 0) {
+    lines.push(c(ANSI.bold, "Needs judgment"));
+    lines.push(c(ANSI.dim, "  goflag states these; it will not guess the answer."));
+    for (const [ruleId, group] of groupBy([...report.advisories], (a) => a.ruleId)) {
+      lines.push(
+        `  ${c(ANSI.cyan, ruleId)} ${c(ANSI.dim, `(${group.length} page${group.length === 1 ? "" : "s"})`)}`
+      );
+      lines.push(`    ${group[0].prose}`);
+    }
+    lines.push("");
+  }
   if (report.summary.verdict === "green") {
     lines.push(c(ANSI.green, "No problems found."));
     lines.push("");
@@ -3346,7 +3862,9 @@ function renderSummaryTerminal(summary, options = {}) {
   lines.push(
     `${c(verdictColor2(summary.verdict), VERDICT_FLAG2[summary.verdict])}  ` + c(
       ANSI2.dim,
-      `${summary.totals.pagesCrawled} pages crawled, ${summary.totals.pagesScanned} scanned`
+      `${summary.totals.pagesCrawled} pages crawled, ${summary.totals.pagesScanned} scanned` + // Same reasoning as `renderTerminal`: a narrowed run must say so,
+      // or its low finding count reads as a clean site.
+      (summary.profile === DEFAULT_PROFILE ? "" : `, profile ${summary.profile}`)
     )
   );
   lines.push("");
@@ -3401,6 +3919,37 @@ function renderSummaryTerminal(summary, options = {}) {
     lines.push(...rollupRows(summary.siteIssues, c));
     lines.push("");
   }
+  if (summary.conformance) {
+    lines.push(c(ANSI2.bold, "Conformance"));
+    for (const rule of summary.conformance.rules) {
+      const { pass, fail, warn, na, crashed } = rule.totals;
+      const tally = [
+        fail > 0 ? c(ANSI2.red, `${fail} fail`) : null,
+        warn > 0 ? c(ANSI2.yellow, `${warn} warn`) : null,
+        pass > 0 ? c(ANSI2.green, `${pass} pass`) : null,
+        na > 0 ? c(ANSI2.dim, `${na} n/a`) : null,
+        crashed > 0 ? c(ANSI2.red, `${crashed} crashed`) : null
+      ].filter(Boolean);
+      lines.push(`  ${c(ANSI2.cyan, rule.ruleId.padEnd(24))} ${tally.join(c(ANSI2.dim, " \xB7 "))}`);
+    }
+    lines.push("");
+  }
+  if (summary.advisories && summary.advisories.length > 0) {
+    lines.push(c(ANSI2.bold, "Needs judgment"));
+    const byRule = /* @__PURE__ */ new Map();
+    for (const advisory of summary.advisories) {
+      const entry = byRule.get(advisory.ruleId);
+      if (entry) entry.pages += 1;
+      else byRule.set(advisory.ruleId, { prose: advisory.prose, pages: 1 });
+    }
+    for (const [ruleId, { prose, pages }] of byRule) {
+      lines.push(
+        `  ${c(ANSI2.cyan, ruleId)} ${c(ANSI2.dim, `(${pages} page${pages === 1 ? "" : "s"})`)}`
+      );
+      lines.push(`    ${prose}`);
+    }
+    lines.push("");
+  }
   if (summary.verdict === "green") {
     lines.push(c(ANSI2.green, "No problems found."));
     lines.push("");
@@ -3446,6 +3995,7 @@ function summarize(report) {
   return {
     url: report.url,
     finishedAt: report.finishedAt,
+    profile: report.profile,
     verdict: report.summary.verdict,
     totals: {
       brokenLinks: report.summary.brokenLinks,
@@ -3465,6 +4015,8 @@ function summarize(report) {
     },
     seoIssues: rollupByRule(report.seoIssues),
     siteIssues: rollupByRule(report.siteIssues),
+    ...report.conformance ? { conformance: { rules: report.conformance.rules } } : {},
+    ...report.advisories ? { advisories: report.advisories } : {},
     truncated: report.diagnostics.truncated,
     warnings: report.diagnostics.warnings
   };
@@ -3704,6 +4256,9 @@ var Logger = class {
 };
 
 export {
+  DEFAULT_PROFILE,
+  PROFILES,
+  PROFILE_NAMES,
   routeKey,
   targetKey,
   fingerprint,
@@ -3716,4 +4271,4 @@ export {
   summarize,
   Logger
 };
-//# sourceMappingURL=chunk-3777NRM4.js.map
+//# sourceMappingURL=chunk-GFM3YN5N.js.map