pagegraph 0.5.0 → 0.6.0

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import { a as SeoGraph } from "./graph-BlLoEOw2.js";
+import { d as SeoGraph, t as CoverageRule } from "./checks-BfsQtKga.js";
 import { PluginOption } from "vite";
 //#region src/config/vite-graph-loader.d.ts
 /** A graph, plus the release of whatever producing it acquired. */
@@ -67,6 +67,12 @@ interface SeoCliConfig {
    * Runs for indexable and preview hosts.
    */
   readonly transform?: ((robots: string) => string) | undefined;
+  /**
+   * Contextual-link coverage policy for `pagegraph check`: every sitemap-eligible
+   * page matching a rule's `path` glob needs at least `minInbound` incoming
+   * `related` edges. A `--require-inbound` flag overrides this per invocation.
+   */
+  readonly coverage?: ReadonlyArray<CoverageRule> | undefined;
   /** How the CLI gets the graph. {@link viteGraphLoader} covers the Vite-app case. */
   readonly loadGraph: SeoGraphLoader;
 }

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","names":[],"sources":["../src/config/vite-graph-loader.ts","../src/config/index.ts"],"sourcesContent":["/**\n * A graph loader that evaluates the host app's own graph module inside a\n * headless Vite server.\n *\n * The SEO graph is built *by the app*: its module reads the generated route\n * tree and whatever content collections it owns, so it pulls in the app's real\n * module graph — path aliases, virtual modules from content plugins, bare\n * imports that only exist inside a server runtime. A CLI cannot just `import()`\n * that from Node or Bun.\n *\n * So this boots a scoped, in-process Vite server (middleware mode, no HMR, no\n * watcher, no HTTP listener), `ssrLoadModule`s the app's graph module, and calls\n * its exported loader. The graph comes back as a live in-process object — there\n * is no serialization boundary for the commands to cross — and the server is\n * closed by {@link LoadedSeoGraph.dispose}.\n *\n * Everything host-shaped is an option: the app supplies its own {@link\n * ViteGraphLoaderOptions.plugins} (a content plugin, an MDX loader), {@link\n * ViteGraphLoaderOptions.stubs} for bare modules that only resolve inside its\n * server runtime, and {@link ViteGraphLoaderOptions.env} for variables its\n * modules parse at import. This file knows about none of them.\n */\n\nimport { createServer, type InlineConfig, type PluginOption } from \"vite\";\n\nimport type { SeoGraph } from \"../core/graph\";\n\n/** A graph, plus the release of whatever producing it acquired. */\nexport interface LoadedSeoGraph {\n  readonly graph: SeoGraph;\n  /** Called once the command is done with the graph, on success or failure. */\n  readonly dispose: () => Promise<void>;\n}\n\n/**\n * Produces the SEO graph for the `pagegraph` CLI. A plain promise on purpose: a\n * config file must be writable without Effect, which the CLI keeps behind its\n * `bin` (an optional peer dependency).\n */\nexport type SeoGraphLoader = () => Promise<LoadedSeoGraph>;\n\nexport interface ViteGraphLoaderOptions {\n  /** The app's Vite root — the directory its aliases and plugins resolve against. */\n  readonly root: string;\n  /** Module exporting the graph loader, root-relative (e.g. `/lib/seo/graph.ts`). */\n  readonly entry: string;\n  /** Named export on `entry` returning `Promise<SeoGraph>`. Defaults to `loadSeoGraph`. */\n  readonly exportName?: string | undefined;\n  /** Vite plugins the app's module graph needs — a content/MDX plugin, say. */\n  readonly plugins?: ReadonlyArray<PluginOption> | undefined;\n  /**\n   * Bare or virtual module ids to replace with inert source, so a module that\n   * only resolves inside the app's server runtime does not break the load.\n   */\n  readonly stubs?: Readonly<Record<string, string>> | undefined;\n  /**\n   * Variables to seed on `process.env` before the app's modules parse it. Vite\n   * exposes prefixed values through `import.meta.env`, so this is how a module\n   * that demands an env var at import time is satisfied. Existing values win —\n   * a real `.env` is never clobbered.\n   */\n  readonly env?: Readonly<Record<string, string>> | undefined;\n}\n\nconst messageOf = (cause: unknown): string =>\n  cause instanceof Error ? cause.message : String(cause);\n\n/**\n * Vite and its plugins write progress to stdout. The CLI reserves stdout for the\n * data plane, so redirect it to stderr for the duration of the load.\n *\n * Both the stream method and `console.log`/`info` are swapped: under Bun,\n * `console.log` writes to fd 1 natively rather than going through\n * `process.stdout.write`, so the stream swap alone would miss a plugin that\n * logs through the console.\n */\nconst withCleanStdout = async <A>(run: () => Promise<A>): Promise<A> => {\n  const originalWrite = process.stdout.write.bind(process.stdout);\n  const originalLog = console.log;\n  const originalInfo = console.info;\n  process.stdout.write = process.stderr.write.bind(process.stderr) as typeof process.stdout.write;\n  console.log = (...args: Array<unknown>) => console.error(...args);\n  console.info = (...args: Array<unknown>) => console.error(...args);\n  try {\n    return await run();\n  } finally {\n    process.stdout.write = originalWrite;\n    console.log = originalLog;\n    console.info = originalInfo;\n  }\n};\n\n/** Turn `{ id: source }` into a Vite plugin that resolves and loads each id. */\nconst stubPlugin = (stubs: Readonly<Record<string, string>>): PluginOption => {\n  const virtualIdOf = (id: string) => `\\0seo-cli-stub:${id}`;\n  const sourceByVirtualId = new Map(\n    Object.entries(stubs).map(([id, source]) => [virtualIdOf(id), source]),\n  );\n  return {\n    name: \"seo:stubs\",\n    resolveId: (id) => (id in stubs ? virtualIdOf(id) : null),\n    load: (id) => sourceByVirtualId.get(id) ?? null,\n  };\n};\n\nconst seedEnv = (env: Readonly<Record<string, string>>): void => {\n  for (const [key, value] of Object.entries(env)) {\n    // oxlint-disable-next-line node/no-process-env -- CLI boundary: seeds the raw env BEFORE the app's own env module parses it; that module is the consumer here, not an option\n    process.env[key] ??= value;\n  }\n};\n\nconst inlineConfigFor = (options: ViteGraphLoaderOptions): InlineConfig => ({\n  configFile: false,\n  root: options.root,\n  mode: \"production\",\n  logLevel: \"error\",\n  appType: \"custom\",\n  clearScreen: false,\n  server: { middlewareMode: true, hmr: false, watch: null },\n  resolve: { tsconfigPaths: true },\n  plugins: [\n    ...(options.stubs === undefined ? [] : [stubPlugin(options.stubs)]),\n    ...(options.plugins ?? []),\n  ],\n});\n\n/**\n * Build a {@link SeoGraphLoader} that evaluates `entry` in a headless Vite\n * server rooted at `root`, and returns what its `exportName` export resolves to.\n */\nexport const viteGraphLoader =\n  (options: ViteGraphLoaderOptions): SeoGraphLoader =>\n  async () => {\n    const exportName = options.exportName ?? \"loadSeoGraph\";\n    if (options.env) seedEnv(options.env);\n\n    const server = await withCleanStdout(() => createServer(inlineConfigFor(options))).catch(\n      (cause: unknown) => {\n        throw new Error(`Could not start the Vite loader: ${messageOf(cause)}`);\n      },\n    );\n\n    // The server is a resource from here on: a failed load must still close it,\n    // and a successful one hands the close to the caller as `dispose`.\n    const graph = await withCleanStdout(async () => {\n      const module = (await server.ssrLoadModule(options.entry)) as Record<string, unknown>;\n      const load = module[exportName];\n      if (typeof load !== \"function\") {\n        throw new Error(\n          `${options.entry} has no \\`${exportName}\\` export (found: ${Object.keys(module).join(\", \") || \"nothing\"}).`,\n        );\n      }\n      return (await load()) as SeoGraph;\n    }).catch(async (cause: unknown) => {\n      // Close on the way out, but never let a close failure bury the real\n      // error: the reason the graph did not build is the useful one.\n      await withCleanStdout(() => server.close()).catch(() => {});\n      throw new Error(`Could not build the SEO graph: ${messageOf(cause)}`);\n    });\n\n    return { graph, dispose: () => withCleanStdout(() => server.close()) };\n  };\n","/**\n * `pagegraph/config` — the `pagegraph` CLI's configuration surface.\n *\n * The CLI is a set of pure views over one graph, but *acquiring* that graph is\n * host knowledge: only the app knows where its graph module lives and what its\n * module needs to evaluate. So the app declares it once in a `seo.config.ts` at\n * its root, which the CLI discovers from the working directory:\n *\n * ```ts\n * // seo.config.ts\n * import { defineSeoConfig, viteGraphLoader } from \"pagegraph/config\";\n * import { routeConfig } from \"./lib/route-config\";\n *\n * export default defineSeoConfig({\n *   origin: \"https://example.com\",\n *   disallow: routeConfig.robotsExclusions,\n *   contentSignal: \"search=yes, ai-input=yes, ai-train=yes\",\n *   loadGraph: viteGraphLoader({ root: import.meta.dirname, entry: \"/lib/seo/graph.ts\" }),\n * });\n * ```\n *\n * Nothing here imports Effect. The CLI needs it (an optional peer dependency),\n * but a config file must not: it is the app's file, and the app may not be an\n * Effect app.\n */\n\nexport type { LoadedSeoGraph, SeoGraphLoader, ViteGraphLoaderOptions } from \"./vite-graph-loader\";\nexport { viteGraphLoader } from \"./vite-graph-loader\";\n\nimport type { SeoGraphLoader } from \"./vite-graph-loader\";\n\nexport interface SeoCliConfig {\n  /**\n   * Canonical origin the sitemap and robots projections render under, no\n   * trailing slash. The `--origin` flag overrides it per invocation.\n   */\n  readonly origin: string;\n  /**\n   * Path prefixes disallowed in robots.txt. Feed it the generated\n   * `routeConfig.robotsExclusions` if you run the `pagegraph/vite` plugin.\n   */\n  readonly disallow: ReadonlyArray<string>;\n  /**\n   * Origin-wide Content-Signal preferences, forwarded to `renderRobots`.\n   * Omit for none. Preview (`--no-indexable`) never emits the line.\n   */\n  readonly contentSignal?: string | undefined;\n  /**\n   * Extra robots.txt group lines, forwarded to `renderRobots` as `directives`.\n   */\n  readonly directives?: ReadonlyArray<string> | undefined;\n  /**\n   * Last-mile robots.txt override, forwarded to `renderRobots` as `transform`.\n   * Runs for indexable and preview hosts.\n   */\n  readonly transform?: ((robots: string) => string) | undefined;\n  /** How the CLI gets the graph. {@link viteGraphLoader} covers the Vite-app case. */\n  readonly loadGraph: SeoGraphLoader;\n}\n\n/** Identity — it exists for the type inference and the editor completions. */\nexport const defineSeoConfig = (config: SeoCliConfig): SeoCliConfig => config;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAgEA,MAAM,aAAa,UACjB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;;;;;;;;;;AAWvD,MAAM,kBAAkB,OAAU,QAAsC;CACtE,MAAM,gBAAgB,QAAQ,OAAO,MAAM,KAAK,QAAQ,MAAM;CAC9D,MAAM,cAAc,QAAQ;CAC5B,MAAM,eAAe,QAAQ;CAC7B,QAAQ,OAAO,QAAQ,QAAQ,OAAO,MAAM,KAAK,QAAQ,MAAM;CAC/D,QAAQ,OAAO,GAAG,SAAyB,QAAQ,MAAM,GAAG,IAAI;CAChE,QAAQ,QAAQ,GAAG,SAAyB,QAAQ,MAAM,GAAG,IAAI;CACjE,IAAI;EACF,OAAO,MAAM,IAAI;CACnB,UAAU;EACR,QAAQ,OAAO,QAAQ;EACvB,QAAQ,MAAM;EACd,QAAQ,OAAO;CACjB;AACF;;AAGA,MAAM,cAAc,UAA0D;CAC5E,MAAM,eAAe,OAAe,kBAAkB;CACtD,MAAM,oBAAoB,IAAI,IAC5B,OAAO,QAAQ,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,YAAY,EAAE,GAAG,MAAM,CAAC,CACvE;CACA,OAAO;EACL,MAAM;EACN,YAAY,OAAQ,MAAM,QAAQ,YAAY,EAAE,IAAI;EACpD,OAAO,OAAO,kBAAkB,IAAI,EAAE,KAAK;CAC7C;AACF;AAEA,MAAM,WAAW,QAAgD;CAC/D,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,GAAG,GAE3C,QAAQ,IAAI,SAAS;AAEzB;AAEA,MAAM,mBAAmB,aAAmD;CAC1E,YAAY;CACZ,MAAM,QAAQ;CACd,MAAM;CACN,UAAU;CACV,SAAS;CACT,aAAa;CACb,QAAQ;EAAE,gBAAgB;EAAM,KAAK;EAAO,OAAO;CAAK;CACxD,SAAS,EAAE,eAAe,KAAK;CAC/B,SAAS,CACP,GAAI,QAAQ,UAAU,KAAA,IAAY,CAAC,IAAI,CAAC,WAAW,QAAQ,KAAK,CAAC,GACjE,GAAI,QAAQ,WAAW,CAAC,CAC1B;AACF;;;;;AAMA,MAAa,mBACV,YACD,YAAY;CACV,MAAM,aAAa,QAAQ,cAAc;CACzC,IAAI,QAAQ,KAAK,QAAQ,QAAQ,GAAG;CAEpC,MAAM,SAAS,MAAM,sBAAsB,aAAa,gBAAgB,OAAO,CAAC,CAAC,CAAC,CAAC,OAChF,UAAmB;EAClB,MAAM,IAAI,MAAM,oCAAoC,UAAU,KAAK,GAAG;CACxE,CACF;CAoBA,OAAO;EAAE,OAAA,MAhBW,gBAAgB,YAAY;GAC9C,MAAM,SAAU,MAAM,OAAO,cAAc,QAAQ,KAAK;GACxD,MAAM,OAAO,OAAO;GACpB,IAAI,OAAO,SAAS,YAClB,MAAM,IAAI,MACR,GAAG,QAAQ,MAAM,YAAY,WAAW,oBAAoB,OAAO,KAAK,MAAM,CAAC,CAAC,KAAK,IAAI,KAAK,UAAU,GAC1G;GAEF,OAAQ,MAAM,KAAK;EACrB,CAAC,CAAC,CAAC,MAAM,OAAO,UAAmB;GAGjC,MAAM,sBAAsB,OAAO,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;GAC1D,MAAM,IAAI,MAAM,kCAAkC,UAAU,KAAK,GAAG;EACtE,CAAC;EAEe,eAAe,sBAAsB,OAAO,MAAM,CAAC;CAAE;AACvE;;;;ACrGF,MAAa,mBAAmB,WAAuC"}
+{"version":3,"file":"config.js","names":[],"sources":["../src/config/vite-graph-loader.ts","../src/config/index.ts"],"sourcesContent":["/**\n * A graph loader that evaluates the host app's own graph module inside a\n * headless Vite server.\n *\n * The SEO graph is built *by the app*: its module reads the generated route\n * tree and whatever content collections it owns, so it pulls in the app's real\n * module graph — path aliases, virtual modules from content plugins, bare\n * imports that only exist inside a server runtime. A CLI cannot just `import()`\n * that from Node or Bun.\n *\n * So this boots a scoped, in-process Vite server (middleware mode, no HMR, no\n * watcher, no HTTP listener), `ssrLoadModule`s the app's graph module, and calls\n * its exported loader. The graph comes back as a live in-process object — there\n * is no serialization boundary for the commands to cross — and the server is\n * closed by {@link LoadedSeoGraph.dispose}.\n *\n * Everything host-shaped is an option: the app supplies its own {@link\n * ViteGraphLoaderOptions.plugins} (a content plugin, an MDX loader), {@link\n * ViteGraphLoaderOptions.stubs} for bare modules that only resolve inside its\n * server runtime, and {@link ViteGraphLoaderOptions.env} for variables its\n * modules parse at import. This file knows about none of them.\n */\n\nimport { createServer, type InlineConfig, type PluginOption } from \"vite\";\n\nimport type { SeoGraph } from \"../core/graph\";\n\n/** A graph, plus the release of whatever producing it acquired. */\nexport interface LoadedSeoGraph {\n  readonly graph: SeoGraph;\n  /** Called once the command is done with the graph, on success or failure. */\n  readonly dispose: () => Promise<void>;\n}\n\n/**\n * Produces the SEO graph for the `pagegraph` CLI. A plain promise on purpose: a\n * config file must be writable without Effect, which the CLI keeps behind its\n * `bin` (an optional peer dependency).\n */\nexport type SeoGraphLoader = () => Promise<LoadedSeoGraph>;\n\nexport interface ViteGraphLoaderOptions {\n  /** The app's Vite root — the directory its aliases and plugins resolve against. */\n  readonly root: string;\n  /** Module exporting the graph loader, root-relative (e.g. `/lib/seo/graph.ts`). */\n  readonly entry: string;\n  /** Named export on `entry` returning `Promise<SeoGraph>`. Defaults to `loadSeoGraph`. */\n  readonly exportName?: string | undefined;\n  /** Vite plugins the app's module graph needs — a content/MDX plugin, say. */\n  readonly plugins?: ReadonlyArray<PluginOption> | undefined;\n  /**\n   * Bare or virtual module ids to replace with inert source, so a module that\n   * only resolves inside the app's server runtime does not break the load.\n   */\n  readonly stubs?: Readonly<Record<string, string>> | undefined;\n  /**\n   * Variables to seed on `process.env` before the app's modules parse it. Vite\n   * exposes prefixed values through `import.meta.env`, so this is how a module\n   * that demands an env var at import time is satisfied. Existing values win —\n   * a real `.env` is never clobbered.\n   */\n  readonly env?: Readonly<Record<string, string>> | undefined;\n}\n\nconst messageOf = (cause: unknown): string =>\n  cause instanceof Error ? cause.message : String(cause);\n\n/**\n * Vite and its plugins write progress to stdout. The CLI reserves stdout for the\n * data plane, so redirect it to stderr for the duration of the load.\n *\n * Both the stream method and `console.log`/`info` are swapped: under Bun,\n * `console.log` writes to fd 1 natively rather than going through\n * `process.stdout.write`, so the stream swap alone would miss a plugin that\n * logs through the console.\n */\nconst withCleanStdout = async <A>(run: () => Promise<A>): Promise<A> => {\n  const originalWrite = process.stdout.write.bind(process.stdout);\n  const originalLog = console.log;\n  const originalInfo = console.info;\n  process.stdout.write = process.stderr.write.bind(process.stderr) as typeof process.stdout.write;\n  console.log = (...args: Array<unknown>) => console.error(...args);\n  console.info = (...args: Array<unknown>) => console.error(...args);\n  try {\n    return await run();\n  } finally {\n    process.stdout.write = originalWrite;\n    console.log = originalLog;\n    console.info = originalInfo;\n  }\n};\n\n/** Turn `{ id: source }` into a Vite plugin that resolves and loads each id. */\nconst stubPlugin = (stubs: Readonly<Record<string, string>>): PluginOption => {\n  const virtualIdOf = (id: string) => `\\0seo-cli-stub:${id}`;\n  const sourceByVirtualId = new Map(\n    Object.entries(stubs).map(([id, source]) => [virtualIdOf(id), source]),\n  );\n  return {\n    name: \"seo:stubs\",\n    resolveId: (id) => (id in stubs ? virtualIdOf(id) : null),\n    load: (id) => sourceByVirtualId.get(id) ?? null,\n  };\n};\n\nconst seedEnv = (env: Readonly<Record<string, string>>): void => {\n  for (const [key, value] of Object.entries(env)) {\n    // oxlint-disable-next-line node/no-process-env -- CLI boundary: seeds the raw env BEFORE the app's own env module parses it; that module is the consumer here, not an option\n    process.env[key] ??= value;\n  }\n};\n\nconst inlineConfigFor = (options: ViteGraphLoaderOptions): InlineConfig => ({\n  configFile: false,\n  root: options.root,\n  mode: \"production\",\n  logLevel: \"error\",\n  appType: \"custom\",\n  clearScreen: false,\n  server: { middlewareMode: true, hmr: false, watch: null },\n  resolve: { tsconfigPaths: true },\n  plugins: [\n    ...(options.stubs === undefined ? [] : [stubPlugin(options.stubs)]),\n    ...(options.plugins ?? []),\n  ],\n});\n\n/**\n * Build a {@link SeoGraphLoader} that evaluates `entry` in a headless Vite\n * server rooted at `root`, and returns what its `exportName` export resolves to.\n */\nexport const viteGraphLoader =\n  (options: ViteGraphLoaderOptions): SeoGraphLoader =>\n  async () => {\n    const exportName = options.exportName ?? \"loadSeoGraph\";\n    if (options.env) seedEnv(options.env);\n\n    const server = await withCleanStdout(() => createServer(inlineConfigFor(options))).catch(\n      (cause: unknown) => {\n        throw new Error(`Could not start the Vite loader: ${messageOf(cause)}`);\n      },\n    );\n\n    // The server is a resource from here on: a failed load must still close it,\n    // and a successful one hands the close to the caller as `dispose`.\n    const graph = await withCleanStdout(async () => {\n      const module = (await server.ssrLoadModule(options.entry)) as Record<string, unknown>;\n      const load = module[exportName];\n      if (typeof load !== \"function\") {\n        throw new Error(\n          `${options.entry} has no \\`${exportName}\\` export (found: ${Object.keys(module).join(\", \") || \"nothing\"}).`,\n        );\n      }\n      return (await load()) as SeoGraph;\n    }).catch(async (cause: unknown) => {\n      // Close on the way out, but never let a close failure bury the real\n      // error: the reason the graph did not build is the useful one.\n      await withCleanStdout(() => server.close()).catch(() => {});\n      throw new Error(`Could not build the SEO graph: ${messageOf(cause)}`);\n    });\n\n    return { graph, dispose: () => withCleanStdout(() => server.close()) };\n  };\n","/**\n * `pagegraph/config` — the `pagegraph` CLI's configuration surface.\n *\n * The CLI is a set of pure views over one graph, but *acquiring* that graph is\n * host knowledge: only the app knows where its graph module lives and what its\n * module needs to evaluate. So the app declares it once in a `seo.config.ts` at\n * its root, which the CLI discovers from the working directory:\n *\n * ```ts\n * // seo.config.ts\n * import { defineSeoConfig, viteGraphLoader } from \"pagegraph/config\";\n * import { routeConfig } from \"./lib/route-config\";\n *\n * export default defineSeoConfig({\n *   origin: \"https://example.com\",\n *   disallow: routeConfig.robotsExclusions,\n *   contentSignal: \"search=yes, ai-input=yes, ai-train=yes\",\n *   loadGraph: viteGraphLoader({ root: import.meta.dirname, entry: \"/lib/seo/graph.ts\" }),\n * });\n * ```\n *\n * Nothing here imports Effect. The CLI needs it (an optional peer dependency),\n * but a config file must not: it is the app's file, and the app may not be an\n * Effect app.\n */\n\nexport type { LoadedSeoGraph, SeoGraphLoader, ViteGraphLoaderOptions } from \"./vite-graph-loader\";\nexport { viteGraphLoader } from \"./vite-graph-loader\";\n\nimport type { CoverageRule } from \"../core/checks\";\nimport type { SeoGraphLoader } from \"./vite-graph-loader\";\n\nexport interface SeoCliConfig {\n  /**\n   * Canonical origin the sitemap and robots projections render under, no\n   * trailing slash. The `--origin` flag overrides it per invocation.\n   */\n  readonly origin: string;\n  /**\n   * Path prefixes disallowed in robots.txt. Feed it the generated\n   * `routeConfig.robotsExclusions` if you run the `pagegraph/vite` plugin.\n   */\n  readonly disallow: ReadonlyArray<string>;\n  /**\n   * Origin-wide Content-Signal preferences, forwarded to `renderRobots`.\n   * Omit for none. Preview (`--no-indexable`) never emits the line.\n   */\n  readonly contentSignal?: string | undefined;\n  /**\n   * Extra robots.txt group lines, forwarded to `renderRobots` as `directives`.\n   */\n  readonly directives?: ReadonlyArray<string> | undefined;\n  /**\n   * Last-mile robots.txt override, forwarded to `renderRobots` as `transform`.\n   * Runs for indexable and preview hosts.\n   */\n  readonly transform?: ((robots: string) => string) | undefined;\n  /**\n   * Contextual-link coverage policy for `pagegraph check`: every sitemap-eligible\n   * page matching a rule's `path` glob needs at least `minInbound` incoming\n   * `related` edges. A `--require-inbound` flag overrides this per invocation.\n   */\n  readonly coverage?: ReadonlyArray<CoverageRule> | undefined;\n  /** How the CLI gets the graph. {@link viteGraphLoader} covers the Vite-app case. */\n  readonly loadGraph: SeoGraphLoader;\n}\n\n/** Identity — it exists for the type inference and the editor completions. */\nexport const defineSeoConfig = (config: SeoCliConfig): SeoCliConfig => config;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AAgEA,MAAM,aAAa,UACjB,iBAAiB,QAAQ,MAAM,UAAU,OAAO,KAAK;;;;;;;;;;AAWvD,MAAM,kBAAkB,OAAU,QAAsC;CACtE,MAAM,gBAAgB,QAAQ,OAAO,MAAM,KAAK,QAAQ,MAAM;CAC9D,MAAM,cAAc,QAAQ;CAC5B,MAAM,eAAe,QAAQ;CAC7B,QAAQ,OAAO,QAAQ,QAAQ,OAAO,MAAM,KAAK,QAAQ,MAAM;CAC/D,QAAQ,OAAO,GAAG,SAAyB,QAAQ,MAAM,GAAG,IAAI;CAChE,QAAQ,QAAQ,GAAG,SAAyB,QAAQ,MAAM,GAAG,IAAI;CACjE,IAAI;EACF,OAAO,MAAM,IAAI;CACnB,UAAU;EACR,QAAQ,OAAO,QAAQ;EACvB,QAAQ,MAAM;EACd,QAAQ,OAAO;CACjB;AACF;;AAGA,MAAM,cAAc,UAA0D;CAC5E,MAAM,eAAe,OAAe,kBAAkB;CACtD,MAAM,oBAAoB,IAAI,IAC5B,OAAO,QAAQ,KAAK,CAAC,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,YAAY,EAAE,GAAG,MAAM,CAAC,CACvE;CACA,OAAO;EACL,MAAM;EACN,YAAY,OAAQ,MAAM,QAAQ,YAAY,EAAE,IAAI;EACpD,OAAO,OAAO,kBAAkB,IAAI,EAAE,KAAK;CAC7C;AACF;AAEA,MAAM,WAAW,QAAgD;CAC/D,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,GAAG,GAE3C,QAAQ,IAAI,SAAS;AAEzB;AAEA,MAAM,mBAAmB,aAAmD;CAC1E,YAAY;CACZ,MAAM,QAAQ;CACd,MAAM;CACN,UAAU;CACV,SAAS;CACT,aAAa;CACb,QAAQ;EAAE,gBAAgB;EAAM,KAAK;EAAO,OAAO;CAAK;CACxD,SAAS,EAAE,eAAe,KAAK;CAC/B,SAAS,CACP,GAAI,QAAQ,UAAU,KAAA,IAAY,CAAC,IAAI,CAAC,WAAW,QAAQ,KAAK,CAAC,GACjE,GAAI,QAAQ,WAAW,CAAC,CAC1B;AACF;;;;;AAMA,MAAa,mBACV,YACD,YAAY;CACV,MAAM,aAAa,QAAQ,cAAc;CACzC,IAAI,QAAQ,KAAK,QAAQ,QAAQ,GAAG;CAEpC,MAAM,SAAS,MAAM,sBAAsB,aAAa,gBAAgB,OAAO,CAAC,CAAC,CAAC,CAAC,OAChF,UAAmB;EAClB,MAAM,IAAI,MAAM,oCAAoC,UAAU,KAAK,GAAG;CACxE,CACF;CAoBA,OAAO;EAAE,OAAA,MAhBW,gBAAgB,YAAY;GAC9C,MAAM,SAAU,MAAM,OAAO,cAAc,QAAQ,KAAK;GACxD,MAAM,OAAO,OAAO;GACpB,IAAI,OAAO,SAAS,YAClB,MAAM,IAAI,MACR,GAAG,QAAQ,MAAM,YAAY,WAAW,oBAAoB,OAAO,KAAK,MAAM,CAAC,CAAC,KAAK,IAAI,KAAK,UAAU,GAC1G;GAEF,OAAQ,MAAM,KAAK;EACrB,CAAC,CAAC,CAAC,MAAM,OAAO,UAAmB;GAGjC,MAAM,sBAAsB,OAAO,MAAM,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC;GAC1D,MAAM,IAAI,MAAM,kCAAkC,UAAU,KAAK,GAAG;EACtE,CAAC;EAEe,eAAe,sBAAsB,OAAO,MAAM,CAAC;CAAE;AACvE;;;;AC9FF,MAAa,mBAAmB,WAAuC"}

package/dist/index.d.ts

@@ -1,5 +1,78 @@
-import { a as SeoGraph, c as SeoSource, d as Register, f as RouteSeo, i as SeoEdgeType, l as buildSeoGraph, m as SitemapPolicy, n as SeoCollection, o as SeoInstance, p as SeoKind, r as SeoEdge, s as SeoNode, t as BuildSeoGraphInput, u as PublicPath } from "./graph-BlLoEOw2.js";
+import { _ as Register, a as checkGraph, b as SitemapPolicy, c as SeoCollection, d as SeoGraph, f as SeoInstance, g as PublicPath, h as buildSeoGraph, i as checkCoverage, l as SeoEdge, m as SeoSource, n as Severity, o as hasStructuralViolations, p as SeoNode, r as Violation, s as BuildSeoGraphInput, t as CoverageRule, u as SeoEdgeType, v as RouteSeo, y as SeoKind } from "./checks-BfsQtKga.js";
 import { AnyRouter } 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 {
+  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;
+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;
+//#endregion
 //#region src/core/projections.d.ts
 interface ProjectionConfig {
   origin: string;
@@ -35,6 +108,12 @@ interface NodeReport {
   incoming: Array<SeoEdge>;
   outgoing: Array<SeoEdge>;
 }
+/**
+ * A node belongs in the sitemap when it declares a positive sitemap policy, is not
+ * a redirect, is not robots-noindexed, and is not a param template (a route whose
+ * path still contains a `$` segment — those exist only so their instances inherit).
+ */
+declare function isSitemapEligible(node: SeoNode): boolean;
 /**
  * Render sitemap.xml from the graph. Structural route entries emit no `<lastmod>`
  * (a route has no publish date); content instances emit it from their frontmatter.
@@ -62,19 +141,57 @@ declare function renderRobots(_graph: SeoGraph, cfg: RobotsConfig): string;
 /** Inspect a single node: its declaration, sitemap eligibility, and edges. */
 declare function inspectNode(graph: SeoGraph, path: string): NodeReport | undefined;
 //#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;
+//#region src/core/link-candidates.d.ts
+/** One proposed contextual link, in the direction the link would be authored. */
+interface LinkCandidatePair {
+  readonly source: string;
+  readonly destination: string;
+  /** The cluster the pair shares: a top-level section, or `kind:<kind>`. */
+  readonly cluster: string;
+  /** Why the pair is plausible, e.g. `same top-level section "/blog"`. */
+  readonly reason: string;
+}
+interface LinkCandidateOptions {
+  /** Maximum candidates to return after ordering (default 50). */
+  readonly limit?: number;
+  /** Restrict to these clusters; a filter may be a section or a bare kind. */
+  readonly clusters?: ReadonlyArray<string>;
+  /** Anchors already served in HTML; their pairs are excluded when supplied. */
+  readonly renderedEdges?: ReadonlyArray<SimpleEdge>;
+}
+/** One cluster and how many candidate pairs it contributes (before `limit`). */
+interface LinkClusterSummary {
+  readonly key: string;
+  readonly candidates: number;
 }
-/** Run every rule against the graph and return the flat list of violations. */
-declare function checkGraph(graph: SeoGraph): Array<Violation>;
-/** Structural violations fail `pagegraph check`; editorial-only stays green. */
-declare const hasStructuralViolations: (violations: ReadonlyArray<Violation>) => boolean;
+interface LinkCandidateResult {
+  readonly candidates: ReadonlyArray<LinkCandidatePair>;
+  /** Candidate pairs before `limit` was applied (after cluster filters). */
+  readonly total: number;
+  readonly truncated: boolean;
+  readonly clusters: ReadonlyArray<LinkClusterSummary>;
+}
+/** Directionless pair key, so an edge in either direction means "connected". */
+declare const undirectedEdgeKey: (from: string, to: string) => string;
+/** A `--cluster` filter matches a section by name, or a kind via its bare label. */
+declare const matchesClusterFilter: (cluster: string, filter: string) => boolean;
+/** Human reason string for a candidate's source page, used when handing a plan to Jev. */
+declare const candidateSourceText: (node: SeoNode) => string;
+/**
+ * Enumerate reviewable contextual-link candidates from the declared graph.
+ *
+ * Excluded: self-pairs, pages that are not sitemap-eligible, pairs already
+ * declared as a `related` edge, and — when {@link LinkCandidateOptions.renderedEdges}
+ * is supplied — pairs already rendered as an anchor. Queries, hashes, and
+ * trailing slashes are normalized so both sides compare by the graph's path key.
+ */
+declare const generateLinkCandidates: (graph: SeoGraph, options?: LinkCandidateOptions) => LinkCandidateResult;
+/**
+ * Decode a rendered-edge dump supplied to the CLI: either a bare array of
+ * `{ from, to }` edges, or an object carrying `edges` (or `internalEdges`).
+ * Throws on any other shape — this is user input, not a provider payload.
+ */
+declare const decodeRenderedEdges: (input: unknown) => ReadonlyArray<SimpleEdge>;
 //#endregion
 //#region src/core/inspect-html.d.ts
 /**
@@ -137,5 +254,5 @@ declare const hasBlockingIssues: (report: LiveHeadReport) => boolean;
  */
 declare function resolveRouteLink(router: AnyRouter, path: string): RouteSeo["link"];
 //#endregion
-export { type BuildSeoGraphInput, type JsonLdReport, type LiveHeadReport, type NodeReport, type ProjectionConfig, type PublicPath, type Register, type RobotsConfig, type RouteSeo, type SeoCollection, type SeoEdge, type SeoEdgeType, type SeoGraph, type SeoInstance, type SeoKind, type SeoNode, type SeoSource, type Severity, type SitemapPolicy, type Violation, buildSeoGraph, checkGraph, contentSignal, hasBlockingIssues, hasStructuralViolations, inspectHtml, inspectNode, renderRobots, renderSitemap, resolveRouteLink };
+export { type Anchor, type AnchorRegion, type BuildSeoGraphInput, type CoverageRule, type JsonLdReport, type LinkCandidateOptions, type LinkCandidatePair, type LinkCandidateResult, type LinkClusterSummary, type LinkEdge, type LinkGraphDiff, type LiveHeadReport, type NodeReport, type ProjectionConfig, type PublicPath, type Register, type RenderedGraph, type RenderedPage, type RobotsConfig, type RouteSeo, type SeoCollection, type SeoEdge, type SeoEdgeType, type SeoGraph, type SeoInstance, type SeoKind, type SeoNode, type SeoSource, type Severity, type SimpleEdge, type SitemapPolicy, type Violation, buildRenderedGraph, buildSeoGraph, candidateSourceText, checkCoverage, checkGraph, contentSignal, decodeRenderedEdges, diffLinkGraph, extractAnchors, generateLinkCandidates, hasBlockingIssues, hasStructuralViolations, inspectHtml, inspectNode, isSitemapEligible, matchesClusterFilter, normalizePath, renderRobots, renderSitemap, resolveRouteLink, undirectedEdgeKey };
 //# sourceMappingURL=index.d.ts.map