fix: enforce docs snapshots and track SPA analytics (#34)

Author: smiggleworth

README.md

@@ -10,21 +10,19 @@ CI therefore validate the same package boundary used by GitHub Pages.
 
 - `npm run dev` starts the Vite development server.
 - `npm run build` builds the client and runs `askr ssg` into `dist/`.
-- `npm run docs:api` refreshes the published declaration snapshot.
-- `npm run docs:cli` refreshes the installed CLI command snapshot.
-- `npm run verify:static` validates the generated route, markup, and assets.
 - `npm run fmt:check` checks formatting without changing files.
-- `npm test` verifies the generated static output after a build.
+- `npm test` runs the unit and generated-output contract tests after a build.
 - `npm run preview` serves `dist/` with `vp preview --outDir dist`.
-- `npm run check` runs lint, typecheck, build, and static verification.
+- `npm run check` runs formatting, lint, typecheck, tests, and the production
+  build.
 
 ## Architecture
 
 - `src/pages/marketing/_layout.tsx` owns the marketing shell and shared Askr
   branding.
-- `src/pages/_routes.tsx` owns the complete docs and SSG route registry, while
-  `src/pages/marketing/_routes.tsx` owns the smaller browser registry used by
-  marketing pages.
+- `src/pages/_routes.tsx` owns the complete browser and SSG route registry plus
+  the persistent route-analytics layout, while
+  `src/pages/marketing/_routes.tsx` registers the marketing leaves.
 - `src/pages/marketing/home.tsx` renders the `/` page.
 - `src/pages/docs/catalog.ts` is the typed source of truth for docs routes,
   metadata, grouped navigation, breadcrumbs, page ordering, search, and SSG.
@@ -46,24 +44,17 @@ SSG. This package does not expose a public API.
 1. `npm run build:client` builds the browser entry and stylesheet into
    `.askr/client/` with hashed asset names.
 2. `npm run build:ssg` renders the marketing routes, authored docs catalog, and
-   generated API reference routes,
-   injects them into the built Vite document, and publishes the result to
-   `dist/`.
-3. `npm run verify:static` checks `dist/metadata.json`, pre-rendered content,
-   and every referenced asset.
+   API reference routes, injects them into the built Vite document, and
+   publishes the result to `dist/`.
 
-The build fails when the checked-in API or CLI snapshot drifts from the exact
-package versions in `package-lock.json`. Reference-only packages are kept as
+The API and CLI snapshots are checked-in documentation data. The unit suite
+derives installed package entrypoints, versions, exported signatures, peer
+metadata, and CLI help directly from `node_modules` and fails on drift before
+the production build starts. Package versions remain internal contract metadata
+and are not rendered on the site. Reference-only packages are kept as
 development dependencies; packages used by live browser examples remain
 runtime dependencies.
 
-`docs:api` also generates `src/pages/docs/package-versions.ts` from the
-installed package manifests. Guide badges and package references read from that
-map instead of repeating version literals. To refresh the site after releases,
-upgrade the relevant `@askrjs/*` dependencies, run `npm install`, then run
-`npm run docs:api` and `npm run docs:cli`. The aggregate check verifies that the
-catalog, CLI snapshot, and every generated API entrypoint agree on versions.
-
 `.github/workflows/ci.yml` runs format, lint/typecheck, build, and test on pull
 requests. Pushes to `main` and manual dispatches use
 `.github/workflows/deploy.yml` to run the aggregate check, upload `dist/`, and

index.html

@@ -6,6 +6,19 @@
     <title data-askr-head>Askr</title>
     <link rel="icon" type="image/png" href="/assets/askr-logo-64.png" />
     <link rel="apple-touch-icon" href="/assets/askr-logo-180.png" />
+    <!-- Google tag (gtag.js) -->
+    <script
+      async
+      src="https://www.googletagmanager.com/gtag/js?id=G-TXZTWQFV59"
+    ></script>
+    <script>
+      window.dataLayer = window.dataLayer || [];
+      function gtag() {
+        dataLayer.push(arguments);
+      }
+      gtag('js', new Date());
+      gtag('config', 'G-TXZTWQFV59', { send_page_view: false });
+    </script>
   </head>
 
   <body>

package-lock.json

@@ -6,23 +6,18 @@
   "type": "module",
   "scripts": {
     "dev": "vp dev",
-    "build": "npm run docs:drift && npm run build:client && npm run build:ssg",
+    "build": "npm run build:client && npm run build:ssg",
     "build:client": "vp build --outDir .askr/client",
     "build:ssg": "askr ssg --config ./ssg.config.ts --output ./dist && cp ./dist/404/index.html ./dist/404.html",
-    "verify:static": "tsx ./scripts/verify-static-output.ts",
-    "docs:api": "tsx ./scripts/generate-api-snapshot.ts",
-    "docs:api:check": "tsx ./scripts/generate-api-snapshot.ts --check",
-    "docs:cli": "tsx ./scripts/generate-cli-reference.ts",
-    "docs:cli:check": "tsx ./scripts/generate-cli-reference.ts --check",
-    "docs:drift": "npm run docs:api:check && npm run docs:cli:check",
     "analyze": "askr analyze --check",
-    "lint": "vp lint src scripts ssg.config.ts vite.config.ts",
+    "lint": "vp lint src tests ssg.config.ts vite.config.ts",
     "fmt": "vp fmt .",
     "fmt:check": "vp fmt . --check",
-    "test:unit": "vp test run",
-    "test": "npm run test:unit && npm run verify:static",
+    "test:unit": "vp test run --exclude tests/generated-output-contract.test.ts",
+    "test:static": "vp test run tests/generated-output-contract.test.ts",
+    "test": "npm run test:unit && npm run test:static",
     "typecheck": "tsc --noEmit",
-    "check": "npm run fmt:check && npm run lint && npm run typecheck && npm run docs:drift && npm run test:unit && npm run build && npm run verify:static",
+    "check": "npm run fmt:check && npm run lint && npm run typecheck && npm run test:unit && npm run build && npm run test:static",
     "preview": "vp preview --outDir dist"
   },
   "dependencies": {
@@ -47,7 +42,6 @@
     "@askrjs/testing": "0.0.3",
     "@askrjs/vite": "0.0.10",
     "@types/node": "^26.1.2",
-    "tsx": "4.23.1",
     "typescript": "^6.0.3",
     "vite-plus": "^0.2.6"
   },