pagegraph 0.6.0 → 0.6.1

package/README.md

@@ -27,7 +27,7 @@ bun add -D lighthouse   # only for `pagegraph audit` performance evidence
 
 | Entry                        | Exports                                                                                        | Peers                                       |
 | ---------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------- |
-| `pagegraph`        | `buildSeoGraph`, `renderSitemap`, `renderRobots`, `contentSignal`, `checkGraph`, `inspectHtml` | —                                           |
+| `pagegraph`        | `buildSeoGraph`, `renderSitemap`, `renderRobots`, `contentSignal`, `checkGraph`, `checkRenderedCoverage`, `decodeRenderedEdgeArtifact`, `inspectHtml` | —                                           |
 | `pagegraph/react`  | `createSeo` → `seoHead`, `Breadcrumbs`, JSON-LD generators                                     | `react`, `@tanstack/react-router`           |
 | `pagegraph/vite`   | `seoRouteConfig` coverage gate                                                                 | `vite`                                      |
 | `pagegraph/config` | `defineSeoConfig`, `viteGraphLoader`                                                           | `vite`                                      |
@@ -305,6 +305,8 @@ pagegraph graph                 # the graph as a tree · --format mermaid | json
 pagegraph inspect /pricing      # one node: policy, sitemap status, in/out edges
 pagegraph inspect <url> --live  # fetch a deployed page, validate its rendered <head>
 pagegraph links verify <url>    # crawl served HTML: depth, orphans, declared-vs-rendered
+pagegraph links verify <url> --assert-coverage  # also assert seo.config.ts coverage on served anchors
+pagegraph links verify <url> --emit-rendered <file>  # save the rendered edge set
 pagegraph links candidates      # propose contextual links from the declared graph
 pagegraph links decide <file>   # answer typed link questions with Jev (TYPESAFE_API_KEY)
 pagegraph sitemap               # print sitemap.xml
@@ -327,6 +329,61 @@ pagegraph links verify https://example.com
 pagegraph links verify https://example.com --limit 25 --json | jq
 ```
 
+`--emit-rendered <path>` writes the crawl's raw edge set as a versioned artifact,
+and `--rendered <path>` replays one instead of crawling — so a single crawl can be
+asserted repeatedly in CI without re-fetching:
+
+```bash
+pagegraph links verify https://example.com --emit-rendered .seo/rendered.json
+pagegraph links verify --rendered .seo/rendered.json --json | jq
+```
+
+The artifact preserves every anchor's `region` (`body` vs `nav`/`footer`/`header`)
+and the provenance a gate needs to trust it:
+
+```jsonc
+{
+  "kind": "links-rendered",
+  "schemaVersion": 1,
+  "origin": "https://example.com",
+  "seed": "https://example.com/",
+  "crawl": {
+    "pages": 42,
+    "root": "/",
+    "limit": 100,
+    "truncated": false,
+    "bodyTruncated": false,
+    "truncatedPages": [],
+    "failures": [],
+  },
+  "nodes": ["/", "/pricing"],
+  "edges": [{ "from": "/", "to": "/pricing", "region": "body" }],
+}
+```
+
+It is also a drop-in input for `pagegraph links candidates --rendered`.
+
+### Assert coverage on the rendered graph
+
+`pagegraph check` evaluates the `seo.config.ts` `coverage` rules against the
+**declared** graph; `pagegraph links verify --assert-coverage` evaluates the same
+rules against the anchors a crawler **actually receives**. Only same-origin
+body-region anchors count — nav, header, and footer links are chrome — which is
+the served analogue of `check` counting `related` edges alone. The rule's target
+universe is still the declared graph's sitemap-eligible pages.
+
+```bash
+pagegraph links verify https://example.com --assert-coverage
+pagegraph links verify --rendered .seo/rendered.json --assert-coverage --json | jq
+```
+
+The command exits non-zero when any rule is unmet, and **refuses to assert** (also
+non-zero) rather than reporting a false pass when the crawl outran `--limit`, a
+page failed to fetch (its anchors are missing), a body hit `--max-body-bytes`, the
+config declares no `coverage`, or the artifact's origin differs from
+`seo.config.ts`. Under `--assert-coverage` the report gains a `coverage` block
+(`{ rules, ok, violations }`); the default `--json` summary is unchanged.
+
 ### Propose contextual links
 
 `pagegraph links candidates` reads the declared graph and proposes
@@ -380,6 +437,10 @@ rule that matches no sitemap-eligible page is itself a violation.
 pagegraph check --require-inbound "/pricing=2" --require-inbound "/features/*=1"
 ```
 
+`pagegraph check` asserts the policy on the declared graph. To prove the links are
+actually served, assert the same policy on the rendered graph — see
+[Assert coverage on the rendered graph](#assert-coverage-on-the-rendered-graph).
+
 ### Audit any website
 
 `pagegraph audit` is framework-independent and does not need `seo.config.ts`. It

package/dist/audit.js

@@ -1,4 +1,4 @@
-import { r as extractAnchors } from "./links-sGbLkl-7.js";
+import { a as extractAnchors } from "./links-BFJc-pJ9.js";
 import { mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import * as Context from "effect/Context";

package/dist/checks-6noG_xTS.d.ts

@@ -0,0 +1,313 @@
+import { AnyRoute, AnyRouteMatch } from "@tanstack/react-router";
+//#region src/core/links.d.ts
+/**
+ * Pure link-graph utilities: read anchors out of rendered HTML, model the
+ * rendered graph, compute homepage depth, and diff it against the declared
+ * graph. Effect- and framework-free so it runs in the CLI, a Worker, or a test
+ * on the same data.
+ *
+ * This is the "served HTML" half of the SEO graph: the declared graph describes
+ * intent, this describes what a crawler actually receives.
+ */
+/** Where an anchor sits in the document, coarsely. */
+type AnchorRegion = "nav" | "footer" | "header" | "body";
+interface Anchor {
+  readonly href: string;
+  readonly text: string;
+  readonly region: AnchorRegion;
+  /** True when the resolved target shares the page's origin. */
+  readonly internal: boolean;
+}
+interface LinkEdge {
+  readonly from: string;
+  readonly to: string;
+  readonly region: AnchorRegion;
+}
+interface RenderedGraph {
+  /** Every same-origin page path the crawl rendered, in first-seen order. */
+  readonly nodes: ReadonlyArray<string>;
+  readonly edges: ReadonlyArray<LinkEdge>;
+  readonly internalEdges: ReadonlyArray<LinkEdge>;
+  /** Same-origin body-region edges: the contextual surface. */
+  readonly contextualEdges: ReadonlyArray<LinkEdge>;
+  /** Same-origin pages with no incoming internal edge ("reachable only via nav" is not implied). */
+  readonly orphans: ReadonlyArray<string>;
+  readonly depthByPath: ReadonlyMap<string, number>;
+  readonly maxDepth: number | null;
+}
+/** Normalize a same-origin URL to the graph's path key (no query/hash; "/" preserved). */
+declare const normalizePath: (url: URL) => string;
+/**
+ * Extract every anchor in document order, tagging each with the region tag it
+ * sits inside. Anchor text keeps only its letters and a coarse entity decode;
+ * this is a classifier input, not a renderer.
+ */
+declare const extractAnchors: (html: string, baseUrl: string) => ReadonlyArray<Anchor>;
+interface RenderedPage {
+  readonly url: string;
+  readonly anchors: ReadonlyArray<Anchor>;
+}
+/**
+ * Build the rendered graph from crawled pages. `origin` fixes the graph's
+ * same-origin boundary — pages and anchors on another origin are dropped, not
+ * silently folded in — and `root` is the normalized path the depth BFS starts
+ * from (the seed's final path when the homepage redirected). Every page path is
+ * keyed the way the declared graph keys its routes.
+ */
+declare const buildRenderedGraph: (origin: string, pages: ReadonlyArray<RenderedPage>, root?: string) => RenderedGraph;
+/**
+ * Rebuild a {@link RenderedGraph} from a rendered-edge set alone — the artifact
+ * `pagegraph links verify --emit-rendered` writes. Path keys are normalized the
+ * same way as a crawl, and `nodes` carries the rendered page paths the artifact
+ * recorded, so an edge-less page (a redirect target with no internal links) stays
+ * a node and its orphan/depth report survives replay. Without `nodes` the node set
+ * falls back to the edge endpoints.
+ */
+declare const renderedGraphFromEdges: (edges: ReadonlyArray<LinkEdge>, root?: string, nodes?: ReadonlyArray<string>) => RenderedGraph;
+interface SimpleEdge {
+  readonly from: string;
+  readonly to: string;
+}
+interface LinkGraphDiff {
+  /** Declared internal edges with no matching rendered anchor. */
+  readonly declaredNotRendered: ReadonlyArray<SimpleEdge>;
+  /** Rendered contextual edges that no declared edge accounts for. */
+  readonly renderedNotDeclared: ReadonlyArray<SimpleEdge>;
+  readonly declaredCount: number;
+  readonly renderedContextualCount: number;
+}
+/**
+ * Diff rendered contextual edges against declared `related`/`crumb` edges. Both
+ * sides are path-keyed; the diff is directional and reports each direction
+ * separately because they call for different fixes.
+ */
+declare const diffLinkGraph: (declared: ReadonlyArray<SimpleEdge>, rendered: RenderedGraph) => LinkGraphDiff;
+/** A page the crawl could not render; its outgoing anchors are absent. */
+interface RenderedEdgeFailure {
+  readonly url: string;
+  readonly error: string;
+}
+/**
+ * Provenance for a rendered-edge artifact: enough to trust the edges and to
+ * refuse a gate that would assert on an incomplete crawl. `root` is the seed's
+ * normalized final path (its post-redirect path), so depth and orphans rebuild
+ * exactly as the crawl computed them.
+ */
+interface RenderedEdgeArtifactCrawl {
+  /** Pages whose HTML was rendered into `edges`. */
+  readonly pages: number;
+  /** Normalized final path of the seed — the depth BFS root. */
+  readonly root: string;
+  /** The crawl's page budget (`--limit`). */
+  readonly limit: number;
+  /** True when discovery outran `limit`; a gate must not assert on this. */
+  readonly truncated: boolean;
+  /** True when any captured body was cut at `--max-body-bytes`. */
+  readonly bodyTruncated: boolean;
+  /** URLs whose captured body was cut; anchors past the cutoff are missing. */
+  readonly truncatedPages: ReadonlyArray<string>;
+  /** Pages that failed to fetch; their outgoing anchors are missing. */
+  readonly failures: ReadonlyArray<RenderedEdgeFailure>;
+}
+/**
+ * The stable, `decodeRenderedEdges`-compatible artifact `pagegraph links verify
+ * --emit-rendered` writes and `--rendered` reads. It carries the raw served edges
+ * (with `region`), the rendered page paths, and the provenance a coverage gate
+ * needs to decide whether the crawl is trustworthy, so one crawl can be asserted
+ * repeatedly without re-fetching.
+ */
+interface RenderedEdgeArtifact {
+  readonly kind: "links-rendered";
+  readonly schemaVersion: 1;
+  readonly origin: string;
+  readonly seed: string;
+  readonly crawl: RenderedEdgeArtifactCrawl;
+  /** Normalized paths of every rendered page — replay's node set. */
+  readonly nodes: ReadonlyArray<string>;
+  readonly edges: ReadonlyArray<LinkEdge>;
+}
+/** The rendered-edge artifact schema this package writes and accepts. */
+declare const RENDERED_EDGE_ARTIFACT_SCHEMA_VERSION: 1;
+/**
+ * Decode a rendered-edge artifact from user input. Throws on any other shape —
+ * this is user input, not a provider payload. `root`, `bodyTruncated`,
+ * `truncatedPages`, `failures`, and `nodes` are optional so a hand-written edge
+ * dump that only carries provenance can still be replayed.
+ */
+declare const decodeRenderedEdgeArtifact: (input: unknown) => RenderedEdgeArtifact;
+//#endregion
+//#region src/core/declare.d.ts
+/**
+ * Consumer-augmented registry.
+ *
+ * ```ts
+ * declare module "pagegraph" {
+ *   interface Register {
+ *     paths: FileRouteTypes["fullPaths"];
+ *     kinds: "page" | "article" | "hub";
+ *   }
+ * }
+ * ```
+ */
+interface Register {}
+/** Every public full path in the consumer's route tree (type-only; erased at runtime). */
+type PublicPath = Register extends {
+  paths: infer P extends string;
+} ? P : string;
+/** The consumer's page taxonomy. A label: nothing in the core branches on it. */
+type SeoKind = Register extends {
+  kinds: infer K extends string;
+} ? K : string;
+interface SitemapPolicy {
+  priority: number;
+  changeFrequency: "weekly" | "monthly";
+}
+interface RouteSeo {
+  kind: SeoKind;
+  /** Breadcrumb label; fn form reads the match (e.g. loaderData frontmatter title). */
+  crumb?: string | ((match: AnyRouteMatch) => string) | undefined;
+  /** false = excluded from sitemap. Absent on non-indexable kinds is fine. */
+  sitemap?: SitemapPolicy | false | undefined;
+  /** meta robots value, e.g. "noindex, follow" on a hub page. */
+  robots?: string | undefined;
+  /** Typed cross-link edges. */
+  related?: ReadonlyArray<PublicPath> | undefined;
+  /** How OTHER pages render a card for this page. */
+  link?: {
+    title: string;
+    description: string;
+  } | undefined;
+  /** This route is a redirect/alias. */
+  redirectTo?: PublicPath | undefined;
+}
+declare module "@tanstack/react-router" {
+  interface StaticDataRouteOption {
+    seo?: RouteSeo | undefined;
+  }
+}
+//#endregion
+//#region src/core/graph.d.ts
+/**
+ * Where a node came from: `"route"` for a structural route declaration, or the
+ * `source` label of the collection that produced the instance (e.g. "blog").
+ */
+type SeoSource = string;
+interface SeoNode {
+  /** Canonical path, no origin (e.g. "/pricing", "/blog/my-post"). */
+  path: string;
+  kind: SeoKind;
+  source: SeoSource;
+  /** Route-declared policy, or synthesized (kind + inherited sitemap) for instances. */
+  policy: RouteSeo;
+  instance?: {
+    title: string;
+    description?: string | undefined;
+    publishedAt?: string | undefined;
+    modifiedAt?: string | undefined;
+  } | undefined;
+}
+type SeoEdgeType = "crumb-parent" | "related" | "redirect" | "collection-member";
+interface SeoEdge {
+  from: string;
+  to: string;
+  type: SeoEdgeType;
+}
+interface SeoGraph {
+  nodes: Map<string, SeoNode>;
+  edges: Array<SeoEdge>;
+  /** Exact-path ownership conflicts encountered while assembling graph sources. */
+  collisions?: ReadonlyArray<{
+    path: string;
+    sources: ReadonlyArray<SeoSource>;
+  }> | undefined;
+}
+/** One concrete page produced by a collection. */
+interface SeoInstance {
+  /** Canonical path of the page (e.g. "/blog/my-post"). */
+  readonly path: string;
+  readonly title: string;
+  readonly description?: string | undefined;
+  readonly publishedAt?: string | undefined;
+  readonly modifiedAt?: string | undefined;
+}
+interface SeoCollection {
+  /**
+   * The param route these instances render through (e.g. "/blog/$slug"). Instances
+   * inherit this route's declared policy (kind + sitemap) — the graph reads it from
+   * the structural node, so declarations stay the single source of truth.
+   */
+  readonly route: PublicPath;
+  /** The `source` stamped on every node this collection produces (e.g. "blog"). */
+  readonly source: SeoSource;
+  readonly instances: ReadonlyArray<SeoInstance>;
+  /** Edges the collection declares between its instances and the rest of the graph. */
+  readonly edges?: ReadonlyArray<SeoEdge> | undefined;
+}
+interface BuildSeoGraphInput {
+  readonly routeTree: AnyRoute;
+  readonly collections?: ReadonlyArray<SeoCollection> | undefined;
+}
+/**
+ * Build the SEO graph from route declarations and content collections.
+ *
+ * Synchronous: the caller materializes its collections before calling, so there is
+ * no async work here. Callers own the origin.
+ */
+declare function buildSeoGraph(input: BuildSeoGraphInput): SeoGraph;
+//#endregion
+//#region src/core/checks.d.ts
+type Severity = "structural" | "editorial";
+interface Violation {
+  severity: Severity;
+  rule: string;
+  path?: string | undefined;
+  message: string;
+  fix?: string | undefined;
+}
+/**
+ * A contextual-link coverage rule: every sitemap-eligible page matching the
+ * `path` glob must have at least `minInbound` incoming contextual links. Unlike
+ * the static rules, these come from project policy (a CLI flag or
+ * `seo.config.ts`), because "which pages are money pages" is app knowledge.
+ *
+ * The same rule shape is evaluated twice: `checkCoverage` counts declared
+ * `related` edges, and `checkRenderedCoverage` counts the contextual anchors a
+ * crawl actually served. The target universe is always the declared graph's
+ * sitemap-eligible pages — the rendered pass only swaps the edge source.
+ */
+interface CoverageRule {
+  /** Path glob: `*` matches within a segment, `**` matches across segments. */
+  readonly path: string;
+  /** Minimum incoming contextual links the matched page needs. */
+  readonly minInbound: number;
+}
+/**
+ * Run every static rule against the graph, then any caller-supplied
+ * {@link CoverageRule}s, and return the flat list of violations. With no
+ * `coverage` option the result is exactly the static rule set.
+ */
+declare function checkGraph(graph: SeoGraph, options?: {
+  readonly coverage?: ReadonlyArray<CoverageRule> | undefined;
+}): Array<Violation>;
+/**
+ * Enforce contextual-link coverage against the *declared* graph: only `related`
+ * edges count — breadcrumb ancestry is navigation, not context.
+ */
+declare function checkCoverage(graph: SeoGraph, rules: ReadonlyArray<CoverageRule>): Array<Violation>;
+/**
+ * Enforce contextual-link coverage against the *rendered* graph: only same-origin
+ * body-region anchors count. Nav, header, and footer anchors are site chrome, so
+ * a page linked solely from them has no contextual inbound link — the same
+ * distinction the declared pass draws by counting `related` edges alone.
+ *
+ * The target universe is the declared graph's sitemap-eligible pages: the globs
+ * in `seo.config.ts` are written against declared paths, and the crawl is what
+ * supplies the served edges. Pass the crawl's `internalEdges` (each edge carries
+ * its `region`).
+ */
+declare function checkRenderedCoverage(graph: SeoGraph, renderedEdges: ReadonlyArray<LinkEdge>, rules: ReadonlyArray<CoverageRule>): Array<Violation>;
+/** Structural violations fail `pagegraph check`; editorial-only stays green. */
+declare const hasStructuralViolations: (violations: ReadonlyArray<Violation>) => boolean;
+//#endregion
+export { RenderedGraph as A, AnchorRegion as C, RenderedEdgeArtifact as D, RENDERED_EDGE_ARTIFACT_SCHEMA_VERSION as E, diffLinkGraph as F, extractAnchors as I, normalizePath as L, SimpleEdge as M, buildRenderedGraph as N, RenderedEdgeArtifactCrawl as O, decodeRenderedEdgeArtifact as P, renderedGraphFromEdges as R, Anchor as S, LinkGraphDiff as T, PublicPath as _, checkGraph as a, SeoKind as b, BuildSeoGraphInput as c, SeoEdgeType as d, SeoGraph as f, buildSeoGraph as g, SeoSource as h, checkCoverage as i, RenderedPage as j, RenderedEdgeFailure as k, SeoCollection as l, SeoNode as m, Severity as n, checkRenderedCoverage as o, SeoInstance as p, Violation as r, hasStructuralViolations as s, CoverageRule as t, SeoEdge as u, Register as v, LinkEdge as w, SitemapPolicy as x, RouteSeo as y };
+//# sourceMappingURL=checks-6noG_xTS.d.ts.map