pagegraph 0.0.0-tegami-trusted-publish-setup → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saatvik Arya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,388 @@
-# Placeholder package
-  
-  This empty package was published by [Tegami](https://tegami.fuma-nama.dev) to configure npm trusted publishing.
-  
-  The real package contents will be published via CI with OIDC.
-  
+# pagegraph
+
+Route-declared SEO for TanStack Router. Each route declares its SEO policy once, in
+`staticData.seo` — the sitemap, `robots.txt`, breadcrumbs, JSON-LD, cross-links, and
+the CI check all derive from that one declaration. There is no second place to update,
+so nothing drifts. A public page that ships without a declaration **fails the build**.
+
+```mermaid
+flowchart LR
+  subgraph declare["declare once"]
+    route["staticData.seo<br/>+ head()"]
+  end
+  route --> seograph["SeoGraph<br/>(nodes + edges)"]
+  seograph --> sitemap["sitemap.xml"]
+  seograph --> robots["robots.txt"]
+  seograph --> check["pagegraph check · CI gate"]
+  route --> head["&lt;head&gt; meta · canonical<br/>Breadcrumbs · JSON-LD"]
+  gate["seoRouteConfig (vite)"] -. "fails undeclared pages" .-> route
+```
+
+## Install
+
+```bash
+bun add pagegraph
+bun add -D effect @effect/platform-bun   # only if you use the CLI
+bun add -D lighthouse                    # only for `pagegraph audit` performance evidence
+```
+
+| Entry                        | Exports                                                                                        | Peers                                       |
+| ---------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| `pagegraph`        | `buildSeoGraph`, `renderSitemap`, `renderRobots`, `contentSignal`, `checkGraph`, `inspectHtml` | —                                           |
+| `pagegraph/react`  | `createSeo` → `seoHead`, `Breadcrumbs`, JSON-LD generators                                     | `react`, `@tanstack/react-router`           |
+| `pagegraph/vite`   | `seoRouteConfig` coverage gate                                                                 | `vite`                                      |
+| `pagegraph/config` | `defineSeoConfig`, `viteGraphLoader`                                                           | `vite`                                      |
+| `pagegraph/audit`  | Audit services, scanner protocol, rules, and report schemas                                    | `effect`                                    |
+| `pagegraph` bin                    | CLI over the same graph                                                                        | `effect`, `@effect/platform-bun` (optional) |
+
+The core and React entries have **zero runtime dependencies** — everything above is a
+peer, and only the entries you import need theirs installed.
+
+## Quick start
+
+**1. Bind your site identity once.** Route files never see an origin or a brand name.
+
+```ts
+// lib/seo.ts
+import { createSeo } from "pagegraph/react";
+
+export const { seoHead } = createSeo({
+  origin: "https://example.com",
+  site: {
+    name: "Example",
+    logo: "/logo.png",
+    publisherLogo: "/publisher.png",
+    defaultImage: "/og.png",
+    defaultAuthor: { name: "Example Team" },
+  },
+  organization: {
+    legalName: "Example, Inc.",
+    description: "What the company does.",
+    sameAs: ["https://github.com/example"],
+    contactPoint: { contactType: "support", email: "hi@example.com" },
+    address: {
+      streetAddress: "123 Example Street",
+      addressLocality: "Example City",
+      addressRegion: "CA",
+      postalCode: "94105",
+      addressCountry: "US",
+    },
+  },
+  website: { searchPath: "/docs?q={search_term_string}" },
+});
+```
+
+**2. Declare on the route.** Policy in `staticData.seo`, per-page content in `head()`.
+
+```tsx
+export const Route = createFileRoute("/pricing")({
+  staticData: {
+    seo: {
+      kind: "page",
+      crumb: "Pricing",
+      sitemap: { priority: 0.9, changeFrequency: "weekly" },
+      related: ["/features", "/docs"],
+      link: { title: "Pricing", description: "Simple volume pricing." },
+    },
+  },
+  head: (ctx) =>
+    seoHead(ctx, {
+      title: "Pricing — Example",
+      description: "Simple volume pricing.",
+    }),
+});
+```
+
+`seoHead` returns the `meta` + canonical `links` TanStack renders into `<head>` —
+title, description, og/twitter cards, robots, and the JSON-LD each page warrants
+(BreadcrumbList always; Article, FAQPage, Service, ItemList when the instance
+declares them).
+
+### Extensible JSON-LD
+
+The built-in generators are conveniences, not a closed schema registry. Define any
+`schema-dts` entity, link it to the plugin's stable site identities, and compose one
+site graph:
+
+```ts
+import {
+  createSeo,
+  defineJsonLd,
+  extendJsonLd,
+  jsonLdRef,
+} from "pagegraph/react";
+
+export const seo = createSeo({
+  // site, organization, and website as above
+  jsonLd: {
+    site: (ids) => [
+      defineJsonLd({
+        "@type": "SoftwareApplication",
+        "@id": "https://example.com/#product",
+        name: "Example",
+        applicationCategory: "DeveloperApplication",
+        operatingSystem: "Web",
+        provider: jsonLdRef(ids.organization),
+      }),
+    ],
+    transform: (entry) => {
+      if (entry.kind === "organization") {
+        return extendJsonLd(entry.document, {
+          slogan: "Ship with confidence.",
+        });
+      }
+      return entry.document;
+    },
+  },
+});
+
+const siteGraph = seo.generateSiteGraphSchema();
+```
+
+`generateSiteGraphSchema()` includes Organization, WebSite, and configured site
+entities in one `@graph`. Organization and WebSite use stable `#organization` and
+`#website` IDs; articles and services provided by the site reference the same
+Organization. Existing individual generators remain available and are not transformed.
+
+Add page-specific entities through `seoHead`:
+
+```ts
+head: (ctx) =>
+  seo.seoHead(ctx, {
+    title: "Example for developers",
+    description: "A focused description of the product.",
+    jsonLd: [
+      defineJsonLd({
+        "@type": "SoftwareApplication",
+        name: "Example",
+        url: "https://example.com/product",
+      }),
+    ],
+  });
+```
+
+The transform sees discriminated generated and custom entries plus `origin`,
+`canonical`, and `entityIds`. Return the document to keep it, no value (or `false`)
+to suppress it, or an array to expand it. Output preserves caller order and never
+silently deduplicates entities.
+
+**3. Serve the projections.** Build the graph from your route tree, render strings.
+
+```ts
+// lib/seo/graph.ts — also the module the CLI loads
+import { buildSeoGraph } from "pagegraph";
+
+export const loadSeoGraph = () =>
+  buildSeoGraph({ routeTree, collections: [blogCollection] });
+```
+
+```ts
+// routes/sitemap[.]xml.ts — robots[.]txt.ts is symmetric
+import { renderRobots, renderSitemap } from "pagegraph";
+
+renderSitemap(loadSeoGraph(), { origin, indexable: true });
+renderRobots(loadSeoGraph(), {
+  origin,
+  indexable: true,
+  disallow: routeConfig.robotsExclusions,
+  contentSignal: "search=yes, ai-input=yes, ai-train=yes",
+});
+```
+
+`renderRobots` does not invent a Content-Signal. Pass `contentSignal` for
+the value (the plugin prefixes `Content-Signal: `), `directives` for extra
+group lines, and `transform` if you need to wrap or replace the whole file.
+Preview hosts (`indexable: false`) drop `contentSignal` and `directives`;
+`transform` still runs.
+
+**4. Gate CI.** The same graph, the same rules, exit 1 on structural violations.
+
+```bash
+pagegraph check
+```
+
+## Typed paths
+
+Augment `Register` (the same pattern TanStack Router uses) and `related` /
+`redirectTo` are typed against your real route tree — a renamed route becomes a
+compile error, not a dead link:
+
+```ts
+declare module "pagegraph" {
+  interface Register {
+    paths: FileRouteTypes["fullPaths"];
+    kinds: "page" | "article" | "hub";
+  }
+}
+```
+
+## The graph
+
+`buildSeoGraph` walks the route tree and produces nodes (one per public URL) and
+typed edges: `crumb-parent` (breadcrumb ancestry), `related` (deliberate
+cross-links), `redirect`, and `collection-member`.
+
+Dynamic pages — blog posts rendering through `/blog/$slug` — enter as
+**collections**. Instances inherit the param route's declared policy, so
+declarations stay the single source of truth:
+
+```ts
+const blogCollection: SeoCollection = {
+  route: "/blog/$slug",
+  source: "blog",
+  instances: posts.map((p) => ({
+    path: `/blog/${p.slug}`,
+    title: p.title,
+    description: p.description,
+    publishedAt: p.date,
+  })),
+};
+```
+
+`checkGraph` runs every rule against the graph and returns violations at two
+severities:
+
+- **structural** — internally broken declarations; these fail `pagegraph check` (exit 1):
+  dead or duplicate edges, path collisions, a redirect in the sitemap, a
+  sitemap/noindex contradiction, a `related` target with no `link` card, an
+  instance without a title.
+- **editorial** — quality smells, reported but non-failing: duplicate or mis-sized
+  titles and descriptions.
+
+## Coverage gate (Vite)
+
+`seoRouteConfig` parses the route tree with `@tanstack/router-generator` (the same
+parser as the router) and fails `vite build` when a page in an enforced group has
+neither `staticData` nor `head`:
+
+```ts
+// vite.config.ts
+import { seoRouteConfig } from "pagegraph/vite";
+
+seoRouteConfig({
+  outputPath: fileURLToPath(new URL("./lib/route-config.ts", import.meta.url)),
+  publicGroups: ["(marketing)", "(docs)"],
+  enforceCoverageIn: ["(marketing)", "(docs)"],
+  alwaysDisallow: ["/dashboard", "/api"],
+});
+```
+
+It also derives a small config module from the route tree: `robotsExclusions`
+(feed to `renderRobots`) and `reservedSegments` (top-level segments an app must
+not hand out as tenant/org slugs).
+
+## CLI
+
+The graph commands acquire your graph through `seo.config.ts` at the app root —
+the `viteGraphLoader` evaluates your graph module inside a headless Vite server,
+so path aliases, content plugins, and virtual modules all resolve:
+
+```ts
+// seo.config.ts
+import { defineSeoConfig, viteGraphLoader } from "pagegraph/config";
+
+export default defineSeoConfig({
+  origin: "https://example.com",
+  disallow: routeConfig.robotsExclusions,
+  contentSignal: "search=yes, ai-input=yes, ai-train=yes",
+  loadGraph: viteGraphLoader({
+    root: import.meta.dirname,
+    entry: "/lib/seo/graph.ts",
+    exportName: "loadSeoGraph",
+  }),
+});
+```
+
+```bash
+pagegraph check                 # CI gate — exit 1 on structural violations
+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 sitemap               # print sitemap.xml
+pagegraph robots                # print robots.txt
+```
+
+Stdout is data, stderr is status — `pagegraph check --json | jq` just works.
+
+### Audit any website
+
+`pagegraph audit` is framework-independent and does not need `seo.config.ts`. It
+validates target URLs before making requests, follows redirects through the same
+validation boundary, inspects the rendered document and discovery files, and
+can collect Lighthouse evidence through a validating proxy.
+
+```bash
+pagegraph audit https://example.com
+pagegraph audit https://example.com https://example.com/docs --json | jq
+pagegraph audit https://localhost:3000 --allow-private --probe-only
+```
+
+The report keeps evidence and findings separate: scanners collect observations;
+pure rules classify structural failures and editorial quality issues. One failed
+scanner does not erase successful evidence from the others. JSON mode emits one
+versioned document on stdout, while diagnostics and artifact paths stay on
+stderr.
+
+Use `--probe-only` when Lighthouse is unavailable or unnecessary. Private and
+reserved destinations are rejected unless `--allow-private` is explicit; that
+flag is intended for local development and CI fixtures.
+
+### Compare audit artifacts
+
+Write timestamped reports from two revisions, then compare their semantic SEO
+outcomes without failing on timestamps, timing, or other raw scanner evidence:
+
+```bash
+pagegraph audit https://example.com --output-dir .audit/before
+# deploy or check out the next revision
+pagegraph audit https://example.com --output-dir .audit/after
+pagegraph diff .audit/before/<report>.json .audit/after/<report>.json
+pagegraph diff .audit/before/<report>.json .audit/after/<report>.json --json | jq
+```
+
+| Change | Outcome | Exit |
+| --- | --- | ---: |
+| Timestamp, warning text, or raw scanner evidence only | `unchanged` | 0 |
+| Editorial finding or improvement | `changed` | 0 |
+| Structural finding, scanner degradation, or lost coverage | `regressed` | 1 |
+
+Inputs must satisfy the published `AuditReport` schema version 1. JSON mode
+emits a separately versioned `audit-diff` document even when a regression makes
+the command exit 1; operational and schema failures write only to stderr.
+
+Raw scanner evidence remains in the source artifacts but is not interpreted by
+the generic comparator. Performance gates should be expressed as scanner
+findings with explicit thresholds rather than inferred from volatile Lighthouse
+measurements. Finding payloads (`message`, `fix`, `observed`, and `expected`)
+remain semantic: same-severity changes are reported as non-blocking `changed`
+outcomes.
+
+## Testing
+
+Everything the CLI checks is a pure function you can call from a test:
+
+```ts
+import {
+  checkGraph,
+  hasStructuralViolations,
+  inspectHtml,
+} from "pagegraph";
+
+expect(hasStructuralViolations(checkGraph(loadSeoGraph()))).toBe(false);
+
+// render a page however you like, then assert the head it actually ships
+const report = inspectHtml(url, 200, html);
+expect(report.issues).toEqual([]);
+```
+
+## TanStack Start example
+
+The [TanStack Start cookbook](./examples/tanstack-start/README.md) shows the complete wiring in
+one place: route-declared metadata, the graph loader, sitemap and robots projections, JSON-LD,
+the Vite coverage gate, and the CLI inspection and `pagegraph diff` workflow. It is intentionally
+framework-neutral beyond the Start route seams, so you can copy the modules into an existing
+Start app and keep your own route tree and content collections.
+
+## License
+
+MIT