@goflag/cli 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -1,3 +1,52 @@
+/**
+ * Canonical Goflag data model.
+ *
+ * Everything the engine, rules, suggestions, previews, snapshots, diff, and
+ * report layers consume comes from this single shape. The `Page` is the
+ * entire deterministic output of fetching + parsing one URL — no behavior,
+ * no side effects, fully serializable to JSON.
+ *
+ * Design constraints (see PLAN.md "Architectural non-negotiables"):
+ *
+ *  - **No DOM, no React, no Next.js types here.** This module must be safely
+ *    importable from a Node CLI, a browser bundle, an edge worker, or a
+ *    future `@goflag/core` package consumed by a hosted SaaS.
+ *  - **Stable contract.** Adding fields is fine; removing or renaming is a
+ *    semver-major event. Snapshot files (Phase 9) and `--json` consumers
+ *    (Phase 11.5) depend on this shape.
+ *  - **Origins, not just values.** For most metadata we record both the
+ *    parsed value AND where it came from (which raw tag, attribute, or
+ *    JSON-LD path). This is what powers Phase 4's "what if I remove
+ *    `og:image`?" toggle and the Phase 9 diff classifier.
+ */
+/**
+ * Where a parsed value originated. Used by previews to highlight which tag a
+ * given preview consumed and by rules/suggestions to point the user back at
+ * the exact line in the source.
+ */
+type TagOrigin = {
+    kind: "title";
+} | {
+    kind: "meta";
+    name?: string;
+    property?: string;
+    httpEquiv?: string;
+} | {
+    kind: "link";
+    rel: string;
+} | {
+    kind: "html";
+    attribute: string;
+} | {
+    kind: "json-ld";
+    path: string;
+    index: number;
+} | {
+    kind: "header";
+    name: string;
+} | {
+    kind: "computed";
+};
 type Severity = "error" | "warning" | "info";
 
 /**
@@ -57,6 +106,424 @@ interface I18nMatrix {
 /** The outcome of probing a single URL. */
 type LinkVerdict = "ok" | "redirect" | "broken" | "blocked" | "warning" | "skipped";
 
+/**
+ * The extraction model — goflag's per-page observation contract.
+ *
+ * This is the single normalized snapshot that deterministic rules and AI
+ * agents both read (rules-catalog plan §7). Rules never touch raw HTML;
+ * they read the documented fields below, which makes them testable in
+ * isolation and makes run-to-run diffing tractable.
+ *
+ * Design constraints:
+ *
+ * - **Versioned.** `extractionVersion` is bumped whenever a field is removed
+ *   or reshaped. Adding optional fields is not a bump.
+ * - **Provenance-carrying.** Scalar observations are `Fact`s: value + which
+ *   tag produced it + the literal string before normalization. An agent can
+ *   always answer "says who?" from the extraction alone.
+ * - **Self-contained and serializable.** Plain JSON data, no methods, no
+ *   references back into the engine. The shapes mirror `core/types.ts`
+ *   (`Page`) deliberately — the adapter in `./from-page.ts` is mostly a
+ *   projection — but they are declared here so the contract can hold still
+ *   while the engine's internal `Page` evolves.
+ * - **Per-page.** Site-level artefacts (robots.txt, the sitemap tree) get
+ *   their own observation models — `RobotsExtraction` / `SitemapExtraction`,
+ *   specified in `docs/sitemap-robots-plan.md` — in Phase G. Site-computed
+ *   i18n knowledge (locale cluster, reciprocity) and document structure
+ *   (headings, landmarks) are reserved for future additive fields.
+ */
+
+/**
+ * Bumped whenever the shape changes incompatibly (field removed or
+ * reshaped). Consumers that persist extractions (baselines, fingerprints)
+ * key on it.
+ */
+declare const EXTRACTION_VERSION: 1;
+/**
+ * One observed value and where it came from. `raw` is the literal string as
+ * it appeared in the source, kept whenever normalization (trimming, URL
+ * resolution, number parsing) changed it.
+ */
+interface Fact<T> {
+    value: T;
+    origin: TagOrigin;
+    raw?: string;
+}
+/** The network-level observation: what the server said, before any parsing. */
+interface ExtractionHttp {
+    /** The URL the audit asked for. */
+    requestedUrl: string;
+    /** The URL after following redirects (equals `requestedUrl` when none). */
+    finalUrl: string;
+    status: number;
+    /** Lowercased response headers from the final response. */
+    headers: Record<string, string>;
+    /** Number of redirects followed to reach `finalUrl`. */
+    redirects: number;
+    /** From `content-type`, lowercased, parameters stripped. */
+    contentType?: string;
+}
+/**
+ * How the observed DOM was produced. `static` is what a non-JS crawler sees;
+ * `headless` is the post-hydration DOM a JS-aware crawler sees. `escalated`
+ * means goflag started static, found the head suspiciously empty, and re-ran
+ * in headless mode — itself evidence that the page client-renders its
+ * metadata.
+ */
+interface ExtractionRendering {
+    mode: "static" | "headless";
+    escalated: boolean;
+    escalationReason?: string;
+}
+/** Document-level observations: the root element and head-wide declarations. */
+interface ExtractionDocument {
+    /** `<title>` text, trimmed. */
+    title?: Fact<string>;
+    /** `lang` attribute on `<html>`. */
+    lang?: Fact<string>;
+    /** `dir` attribute on `<html>`. */
+    dir?: Fact<string>;
+    /** Declared character encoding (`<meta charset>` or http-equiv). */
+    charset?: Fact<string>;
+    /** `<base href>`, when present. */
+    base?: Fact<string>;
+}
+/**
+ * Named metadata: `<meta name="…">` values plus the canonical link, which
+ * lives here (not under `links`) because rules consume it as a single
+ * page-level declaration. `canonical` is resolved to an absolute URL when
+ * possible; `raw` keeps what the tag literally said.
+ */
+interface ExtractionMeta {
+    description?: Fact<string>;
+    viewport?: Fact<string>;
+    robots?: Fact<string>;
+    googlebot?: Fact<string>;
+    canonical?: Fact<string>;
+    themeColor?: Fact<string>;
+    colorScheme?: Fact<string>;
+    referrer?: Fact<string>;
+    generator?: Fact<string>;
+    applicationName?: Fact<string>;
+    author?: Fact<string>;
+    keywords?: Fact<string[]>;
+}
+/** One `og:image` structured object with its sub-properties. */
+interface ExtractionOpenGraphImage {
+    url: Fact<string>;
+    secureUrl?: Fact<string>;
+    type?: Fact<string>;
+    width?: Fact<number>;
+    height?: Fact<number>;
+    alt?: Fact<string>;
+}
+/** The `og:*` surface (ogp.me vocabulary). */
+interface ExtractionOpenGraph {
+    title?: Fact<string>;
+    type?: Fact<string>;
+    url?: Fact<string>;
+    description?: Fact<string>;
+    siteName?: Fact<string>;
+    locale?: Fact<string>;
+    localeAlternates: Fact<string>[];
+    images: ExtractionOpenGraphImage[];
+    /** Any `og:*` property not mapped above, kept verbatim. */
+    other: Array<{
+        property: string;
+        value: Fact<string>;
+    }>;
+}
+/** The `twitter:*` card surface. X falls back to `og:*` for absent fields. */
+interface ExtractionTwitter {
+    card?: Fact<string>;
+    site?: Fact<string>;
+    creator?: Fact<string>;
+    title?: Fact<string>;
+    description?: Fact<string>;
+    image?: Fact<string>;
+    imageAlt?: Fact<string>;
+}
+/** One `<link rel="alternate" hreflang>` annotation, href resolved. */
+interface ExtractionHreflang {
+    hreflang: string;
+    href: string;
+    isXDefault: boolean;
+}
+/** One icon link (`icon`, `apple-touch-icon`, …). */
+interface ExtractionIcon {
+    rel: string;
+    href: string;
+    sizes?: string;
+    type?: string;
+    /** Parsed `sizes` entries; empty for unparseable values. */
+    parsedSizes: Array<{
+        width: number;
+        height: number;
+    } | "any">;
+}
+/** One feed advertisement (`rel="alternate"` with a feed content type). */
+interface ExtractionFeed {
+    type: string;
+    href: string;
+    title?: string;
+}
+/**
+ * Head link observations other than canonical (which lives under `meta`).
+ * These are already-normalized collections rather than `Fact`s: their origin
+ * is unambiguous (the `link` tag their `rel` names).
+ */
+interface ExtractionLinks {
+    hreflang: ExtractionHreflang[];
+    icons: ExtractionIcon[];
+    manifest?: {
+        href: string;
+    };
+    feeds: ExtractionFeed[];
+}
+/** One `<script type="application/ld+json">` block. */
+interface ExtractionJsonLd {
+    /** Position in document order (0-based). */
+    index: number;
+    /** Top-level `@type` values found in the block (covers `@graph`). */
+    types: string[];
+    /** Parsed JSON, or `null` when parsing failed (see `parseError`). */
+    data: unknown;
+    parseError?: string;
+    /** Verbatim script content — the evidence, especially on parse errors. */
+    raw: string;
+}
+/**
+ * The per-page observation. Everything a page rule (or an agent judging a
+ * prose rule) may read; nothing else.
+ */
+interface Extraction {
+    extractionVersion: typeof EXTRACTION_VERSION;
+    /** When the underlying fetch happened (ISO string, UTC). */
+    fetchedAt: string;
+    http: ExtractionHttp;
+    rendering: ExtractionRendering;
+    document: ExtractionDocument;
+    meta: ExtractionMeta;
+    openGraph: ExtractionOpenGraph;
+    twitter: ExtractionTwitter;
+    links: ExtractionLinks;
+    jsonLd: ExtractionJsonLd[];
+}
+
+/**
+ * The goflag rule descriptor contract (rules-catalog plan §6).
+ *
+ * A rule is a declarative descriptor — id, rigor, cited sources, which
+ * extraction paths it reads — plus a thin pure evaluator over the
+ * `Extraction` observation model. Rules never touch raw HTML and never see
+ * the engine's `Page`; the adapter in `../extraction/from-page.ts` is the
+ * only bridge. Every verdict is uniform and self-explaining: **observed vs
+ * expected vs source**.
+ *
+ * Two axes matter and are deliberately separate:
+ *
+ * - **kind** (how we evaluate): `boolean` rules pass or fail mechanically;
+ *   `scored` rules place a measurement in a band (`ideal` / `acceptable` /
+ *   `poor`). Both may answer `na` when the rule does not apply to this page
+ *   — absence of an optional subject is not a failure. `prose` rules
+ *   (`ProseRule`, below) evaluate to nothing at all: they carry evidence to
+ *   an agent instead of guessing, and are kept out of the deterministic
+ *   `Rule` union so no consumer can mistake one for a verdict.
+ * - **rigor** (how authoritative the requirement is): `spec-required` ›
+ *   `spec-recommended` › `vendor-spec` › `guideline` › `heuristic`. This is
+ *   the honest expression of "source of truth" — an agent must never fix a
+ *   `heuristic` as if it were `spec-required`. Every rule cites ≥1 `Source`
+ *   from `./sources` (CI-enforced in `rules.test.ts`).
+ *
+ * The `Issue` shape still lives in `../core/types` because it crosses the
+ * engine → report → CLI `--json` boundary; `./evaluate.ts` converts
+ * findings into issues at that boundary.
+ */
+
+/** How authoritative the requirement behind a rule is. */
+type Rigor = "spec-required" | "spec-recommended" | "vendor-spec" | "guideline" | "heuristic";
+/** A band a scored measurement can land in. */
+type Band = "ideal" | "acceptable" | "poor";
+/** Everything a rule declares about itself, before any evaluation. */
+interface RuleBase {
+    /** Stable identifier in `category.short-name` form (e.g. `title.missing`). */
+    id: string;
+    /** Grouping key: `document`, `meta`, `opengraph`, `robots`, … */
+    category: string;
+    /** One-line statement of the policy (shown in docs and `why`). */
+    title: string;
+    /** Rationale: why honoring this rule matters. */
+    why: string;
+    rigor: Rigor;
+    /** Ids into the source catalog (`./sources`). ≥1, CI-enforced. */
+    sources: string[];
+    /** Dotted paths into `Extraction` this rule reads (e.g. `meta.canonical`). */
+    reads: string[];
+    /** Related rule ids, when useful. */
+    relates?: string[];
+    /**
+     * Copy-pasteable remediation snippet, attached to failing findings.
+     * Deliberately minimal — real fix generation is the M2 work.
+     */
+    fix?: {
+        title: string;
+        snippet: string;
+        language: string;
+    };
+}
+/** What a boolean rule's evaluator returns. */
+interface BooleanVerdict {
+    /** `na` means the rule does not apply to this page (not a pass). */
+    status: "pass" | "fail" | "na";
+    /** The relevant observed value, JSON-serializable. */
+    observed: unknown;
+    /** Human sentence describing failure (only read when `status === "fail"`). */
+    message?: string;
+    /** Pointer back into the page for highlighting. */
+    origin?: TagOrigin;
+}
+/** A rule that passes or fails mechanically. */
+interface BooleanRule extends RuleBase {
+    kind: "boolean";
+    /** Severity of a failing finding. */
+    severity: Severity;
+    /** One sentence stating what a passing page looks like. */
+    expected: string;
+    evaluate: (extraction: Extraction) => BooleanVerdict;
+}
+/** What a scored rule's evaluator returns. */
+interface ScoredVerdict {
+    /** `na` when the measured subject is absent; `warn` outside the ideal band. */
+    status: "pass" | "warn" | "na";
+    band?: Band;
+    observed: number | string;
+    message?: string;
+    origin?: TagOrigin;
+}
+/** A rule that places a measurement in a band instead of pass/fail. */
+interface ScoredRule extends RuleBase {
+    kind: "scored";
+    /** Inclusive `[min, max]` windows; `acceptable` should contain `ideal`. */
+    bands: {
+        ideal: [number, number];
+        acceptable: [number, number];
+    };
+    /** Severity of a finding landing in each non-ideal band. */
+    severityByBand: Record<"acceptable" | "poor", Severity>;
+    /** One sentence stating the ideal window. */
+    expected: string;
+    evaluate: (extraction: Extraction) => ScoredVerdict;
+}
+/**
+ * One prose rule's evidence bundle for one page. Deliberately *not* a
+ * verdict: `needs-judgment` is the only value `verdict` ever takes here.
+ * Nothing downstream may read an advisory as a finding — it never affects
+ * severity counts, the verdict, or the exit code, because no one has judged
+ * it yet.
+ */
+interface AdvisoryFinding {
+    ruleId: string;
+    kind: "prose";
+    prose: string;
+    rigor: Rigor;
+    sources: string[];
+    /**
+     * Extraction path → the observed value there, one entry per declared
+     * path. An absent observation is present as `null` rather than missing:
+     * "the page has no `og:image`" is evidence, and a missing key could not be
+     * told apart from a path that resolved to nothing.
+     */
+    evidence: Record<string, unknown>;
+    verdict: "needs-judgment";
+}
+type Rule = BooleanRule | ScoredRule;
+/**
+ * One rule's verdict on one page — the uniform result every consumer
+ * (report, conformance view, agents) reads. Produced by `./evaluate.ts`
+ * for **every** rule, passing ones included, so the conformance matrix
+ * (plan §10) is just this list unfiltered.
+ */
+interface RuleFinding {
+    ruleId: string;
+    kind: Rule["kind"];
+    status: "pass" | "fail" | "warn" | "na";
+    band?: Band;
+    /** Set when `status` is `fail` or `warn`. */
+    severity?: Severity;
+    observed: unknown;
+    expected: string;
+    /** Human sentence; present on failing/warning findings. */
+    message?: string;
+    origin?: TagOrigin;
+    rigor: Rigor;
+    sources: string[];
+}
+
+/**
+ * The conformance view (plan §10) — every rule's status on every page, not
+ * just the violations.
+ *
+ * `seoIssues` answers "what is wrong here". That is the right default for a
+ * human fixing a site, and the wrong shape for the question the plan calls
+ * point #2: *where do we stand against the catalog?* A list of violations
+ * cannot distinguish "this rule passes everywhere" from "this rule never
+ * applied to a single page" — and an agent deciding what to work on needs
+ * exactly that distinction.
+ *
+ * So this is the same evaluation, unfiltered: a rule × page matrix of
+ * `pass` / `fail` / `warn` / `na`, plus per-rule totals. Opt-in, because on
+ * a 200-page crawl it is the largest thing in the report and nobody reading
+ * a terminal asked for it.
+ *
+ * Shape note: rule metadata (rigor, sources, expected) is carried once in
+ * `rules`, not repeated per cell. A 200-page × 11-rule matrix with inline
+ * metadata is ~2,200 copies of the same eight fields; the legend + status
+ * grid says the same thing at a fraction of the size, which matters when
+ * the consumer is a context window.
+ */
+
+/** A rule's verdict on one page. Mirrors `RuleFinding["status"]`. */
+type ConformanceStatus = RuleFinding["status"];
+/** Per-rule legend entry and tally across every scanned page. */
+interface ConformanceRule {
+    ruleId: string;
+    kind: Rule["kind"];
+    title: string;
+    rigor: Rigor;
+    sources: string[];
+    /** One sentence stating what a passing page looks like. */
+    expected: string;
+    /**
+     * How the rule landed across the run. `crashed` counts pages where the
+     * evaluator threw, so the five buckets always sum to the number of pages
+     * — a matrix whose arithmetic does not close is worse than no matrix.
+     */
+    totals: {
+        pass: number;
+        fail: number;
+        warn: number;
+        na: number;
+        crashed: number;
+    };
+}
+/** One page's row of the matrix. Rules that crashed on it are absent. */
+interface ConformancePage {
+    url: string;
+    /** Rule id → status. Keyed, not positional, so it survives rule reordering. */
+    statuses: Record<string, ConformanceStatus>;
+}
+interface ConformanceView {
+    /** Legend + totals, in registry order. */
+    rules: ConformanceRule[];
+    /**
+     * One row per **linted** page, in crawl order — which is a smaller set than
+     * `report.pages`: unreachable pages, non-HTML resources, and pages the site
+     * itself declared duplicate via canonical never reach the rule layer. Read
+     * `pages.length` for the denominator; every rule's totals sum to it.
+     */
+    pages: ConformancePage[];
+}
+
 /**
  * Baseline comparison.
  *
@@ -93,10 +560,23 @@ interface DiffEntry {
     pageUrl?: string;
 }
 interface ReportDiff {
-    /** Where and when the baseline was taken, echoed for the report header. */
+    /** Where, when, and under which rule profile the baseline was taken. */
     baseline: {
         url: string;
         finishedAt: string;
+        profile: string;
+    };
+    /**
+     * Set when this run was judged under a different profile than the baseline
+     * was captured under. Not an error — comparing `spec-only` against a
+     * `default` baseline is legitimate, it is just not like-for-like, and
+     * "0 new findings" means less than it appears. So it is reported loudly
+     * and gates nothing: silently diffing across two policies is the failure
+     * mode worth preventing.
+     */
+    profileMismatch?: {
+        baseline: string;
+        current: string;
     };
     /** Findings present now and absent from the baseline — what should fail CI. */
     added: DiffEntry[];
@@ -211,11 +691,28 @@ interface SeoIssue {
     /** A copy-pasteable fix snippet, when the rule offers one. */
     fix?: string;
 }
+/**
+ * One prose rule's evidence bundle, attributed to a page. The `id` is a
+ * fingerprint on the same scheme as `SeoIssue`, so an agent's judgment can
+ * be recorded against it and diffed across runs (M1) once judgments exist.
+ */
+interface ReportAdvisory extends AdvisoryFinding {
+    id: string;
+    pageUrl: string;
+}
 interface GoflagReport {
     /** The base URL the audit started from (normalized). */
     url: string;
     /** ISO timestamp when the audit finished. */
     finishedAt: string;
+    /**
+     * The rule profile the run was judged under (`--profile`, default
+     * `default`). Recorded because it changes what "clean" means: a baseline
+     * captured under `spec-only` is not comparable to one captured under
+     * `strict`, and a green run says nothing about the rules the profile
+     * switched off.
+     */
+    profile: string;
     summary: {
         brokenLinks: number;
         missingTranslations: number;
@@ -240,6 +737,20 @@ interface GoflagReport {
     seoIssues: SeoIssue[];
     /** Findings from the cross-page rule registry (`SITE_RULES`). */
     siteIssues: SiteIssue[];
+    /**
+     * Every rule's status on every page, passing ones included. Present only
+     * when asked for (`--conformance`): on a large crawl it dwarfs the rest
+     * of the report, and it answers a question — "where do we stand against
+     * the catalog?" — that a violations list cannot.
+     */
+    conformance?: ConformanceView;
+    /**
+     * Prose rules with their evidence, for an agent to judge. Present only
+     * when asked for (`--advisories`). Every entry's verdict is
+     * `needs-judgment`: these are questions, not findings, and they never
+     * touch the summary counts, the verdict, or the exit code.
+     */
+    advisories?: ReportAdvisory[];
     /** Comparison against a stored baseline, when `--baseline` was given. */
     diff?: ReportDiff;
     diagnostics: {
@@ -336,6 +847,24 @@ interface AuditOptions {
      * what made hreflang checks silently vacuous.
      */
     noSitemap?: boolean;
+    /**
+     * Named policy overlay applied to the rule registry (`--profile`), e.g.
+     * `strict` or `spec-only`. Defaults to `default` (no overlay). Throws on
+     * an unknown name rather than auditing under a policy nobody asked for.
+     */
+    profile?: string;
+    /**
+     * Emit the rule × page conformance matrix (`--conformance`): every rule's
+     * status on every page, passing ones included. Off by default because it
+     * is the largest section of the report and only an agent (or a coverage
+     * question) wants it.
+     */
+    conformance?: boolean;
+    /**
+     * Emit prose rules with their evidence bundles (`--advisories`). These
+     * carry no verdict and never affect the gate.
+     */
+    advisories?: boolean;
 }
 /**
  * Routes present in some locales but absent in others. A "hole" is exactly
@@ -444,6 +973,8 @@ interface RollupReciprocity {
 interface GoflagSummary {
     url: string;
     finishedAt: string;
+    /** The rule profile the run was judged under. See `GoflagReport.profile`. */
+    profile: string;
     verdict: Verdict;
     totals: {
         brokenLinks: number;
@@ -464,6 +995,22 @@ interface GoflagSummary {
     seoIssues: RollupSeo[];
     /** Cross-page findings, rolled up by rule exactly like `seoIssues`. */
     siteIssues: RollupSeo[];
+    /**
+     * Per-rule conformance totals, when `--conformance` was asked for. The
+     * per-page matrix is dropped here on purpose — it is precisely the
+     * page-by-page repetition summary mode exists to collapse, and the totals
+     * answer the same question. Use the full report for the grid.
+     */
+    conformance?: {
+        rules: ConformanceRule[];
+    };
+    /**
+     * Prose rules needing judgment, when `--advisories` was asked for, carried
+     * verbatim. Not rolled up: each page's evidence bundle is different, and
+     * collapsing them would throw away the only thing that makes an advisory
+     * answerable.
+     */
+    advisories?: ReportAdvisory[];
     truncated: boolean;
     warnings: string[];
 }

package/dist/index.js

@@ -11,7 +11,7 @@ import {
   runAudit,
   summarize,
   targetKey
-} from "./chunk-3777NRM4.js";
+} from "./chunk-GFM3YN5N.js";
 export {
   Logger,
   SAMPLE_LIMIT,

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@goflag/cli",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "type": "module",
-  "description": "A lean CLI that audits a site for broken links, missing translation pages, and missing/misconfigured SEO metadata. JSON-first.",
+  "description": "Audits a site for broken links, missing translation pages, a robots.txt that contradicts your pages, and missing or misconfigured SEO metadata. JSON-first.",
   "keywords": [
     "seo",
     "hreflang",
@@ -28,7 +28,7 @@
     "url": "https://github.com/tancredesimonin/goflag/issues"
   },
   "engines": {
-    "node": ">=20.11"
+    "node": ">=22"
   },
   "bin": {
     "goflag": "dist/cli.js"
@@ -58,6 +58,7 @@
     "test:unit": "vitest run src test/unit",
     "test:integration": "vitest run test/integration",
     "test:coverage": "vitest run --coverage",
+    "validate:sources": "tsx scripts/validate-sources.ts",
     "prepack": "node ../../scripts/stage-package-docs.mjs",
     "prepublishOnly": "pnpm build",
     "release": "commit-and-tag-version"