@se-studio/site-check 2.6.1 → 2.6.3

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.6.3
+
+### Patch Changes
+
+- Updated dependencies
+  - @se-studio/contentful-rest-api@1.11.0
+
+## 2.6.2
+
+### Patch Changes
+
+- f2de9ba: Document CMS smoke integrity (`cmsIntegrity`, `runStaticSmokeTestWithIntegrity`), Vercel `VERCEL_FORCE_NO_BUILD_CACHE`, and update `se-marketing-sites-smoke-test-setup` skill plus `example-empty` reference.
+
 ## 2.6.1
 
 ### Patch Changes

package/README.md

@@ -103,10 +103,14 @@ Programmatic module for live production SEO audits (used by per-app `pnpm seo:au
 
 Curated local smoke tests for marketing sites: verify HTML and `.md` for URLs listed in **`smoke.cases.json`** (generated once from a live sitemap — see skill `se-marketing-sites-smoke-test-setup`).
 
+Optional **`cmsIntegrity`** in `smoke.cases.json` adds a **local-only** Contentful article-link check (parallel with `pnpm smoke-test` server boot). Deployment / live smoke remains HTTP-only.
+
+Requires **^2.6.1** when using `cmsIntegrity` or `pnpm smoke-test` with integrity enabled.
+
 Import from `@se-studio/site-check/smoke-test`:
 
-- `loadStaticSmokeConfig`, `runStaticSmokeTest`, `runPreviewStaticSmokeTest`, `runSmokeTest`
-- `formatSmokeTestReport`, `getSmokeTestExitCode`
+- `loadStaticSmokeConfig`, `runStaticSmokeTest`, `runStaticSmokeTestWithIntegrity`, `runPreviewStaticSmokeTest`, `runSmokeTest`
+- `formatSmokeTestReport`, `formatCombinedSmokeReport`, `getSmokeTestExitCode`, `getCombinedSmokeExitCode`
 
 **Per-app usage** (see `apps/example-empty`):
 
@@ -133,9 +137,43 @@ Add `smoke.cases.json`, `scripts/smoke-test-run.ts`, and optionally `scripts/smo
 | `SMOKE_TEST_CACHE_SKIP_SEVERITY=warn` | `warn` or `error` for cache-skip log lines (default `warn`) |
 | `SMOKE_TEST_READY_PATH=/` | Path polled until the server responds |
 | `SMOKE_TEST_USE_RUNNING_SERVER=false` | Force a fresh server (default `true` for local dev) |
+| `SMOKE_TEST_SKIP_INTEGRITY=true` | HTTP smoke only (set by `smoke-test-one` when `cmsIntegrity` runs in parallel) |
 
 `LOG_CMS_FETCH=1` is set when verify-cache or audit-cache-logs is enabled. The smoke HTTP client never sends `Cache-Control: no-cache`.
 
+### CMS article-link integrity (`cmsIntegrity` in `smoke.cases.json`)
+
+```json
+{
+  "cmsIntegrity": {
+    "enabled": true,
+    "routing": {
+      "articleTypesBasePath": "/resources",
+      "tagsBasePath": "/topics",
+      "peopleBasePath": "/team",
+      "defaultTopic": "other",
+      "enablePrimaryTagPartOfSlug": true,
+      "topiclessArticleTypeSlugs": ["ebooks"]
+    }
+  }
+}
+```
+
+Map `routing` from the app’s `constants.ts` / URL rules. Use `runStaticSmokeTestWithIntegrity` in `scripts/smoke-test-run.ts` (see `apps/example-empty`).
+
+Import from `@se-studio/site-check/cms-integrity` for standalone checks: `runArticleLinkIntegrityFromSmokeConfig`, `evaluateArticleLinkIntegrity`, `getArticleLinkIntegrityExitCode`.
+
+### Vercel build cache (`VERCEL_FORCE_NO_BUILD_CACHE`)
+
+Not a smoke variable — set on the **Vercel project** when `next build` fails intermittently with webpack `WasmHash` errors (often with stale remote build cache; local `pnpm build` may still pass).
+
+```bash
+vercel env add VERCEL_FORCE_NO_BUILD_CACHE preview develop --value 1 --yes
+vercel env add VERCEL_FORCE_NO_BUILD_CACHE production --value 1 --yes
+```
+
+Cannot be set in `vercel.json` — Vercel restores cache before install/build commands. Tradeoff: slower cold builds, more reliable compiles.
+
 **Deploy check** (`smoke-test-deploy-check`): post-build gate for Vercel — starts `pnpm start` without rebuilding, runs `pnpm smoke-test:run`, exits non-zero on failure. Port defaults from `smoke.cases.json`. Set `SMOKE_TEST_IGNORE=true` in Vercel env to bypass in an emergency.
 
 ```json

package/docs/llms.md

@@ -0,0 +1,99 @@
+# @se-studio/site-check — LLM Reference
+
+Site validation CLI, production SEO audits, and curated smoke tests for SE marketing sites.
+
+## Subpath exports
+
+| Import | Purpose |
+|--------|---------|
+| `@se-studio/site-check` | CLI: sitemap / llms.txt / markdown export |
+| `@se-studio/site-check/smoke-test` | HTTP smoke + optional CMS integrity orchestration |
+| `@se-studio/site-check/cms-integrity` | Article-link integrity (Node-safe; no Next barrel) |
+| `@se-studio/site-check/production-audit` | Live production SEO audit |
+| `@se-studio/site-check/screaming-frog` | Screaming Frog export analysis |
+
+## Smoke test (HTTP)
+
+Apps commit `smoke.cases.json`. Requires **^2.0.0** for static smoke; **^2.6.1** when `cmsIntegrity` is enabled.
+
+```ts
+import {
+  runStaticSmokeTest,
+  runStaticSmokeTestWithIntegrity,
+  formatSmokeTestReport,
+  formatCombinedSmokeReport,
+  getSmokeTestExitCode,
+  getCombinedSmokeExitCode,
+} from '@se-studio/site-check/smoke-test';
+```
+
+**Per-app scripts:**
+
+```json
+"smoke-test": "smoke-test-one 3012",
+"smoke-test:run": "tsx scripts/smoke-test-run.ts",
+"smoke-test:live": "smoke-test-live"
+```
+
+**`smoke-test-run.ts` with optional integrity:**
+
+```ts
+const skipIntegrity = (process.env.SMOKE_TEST_SKIP_INTEGRITY ?? '').toLowerCase() === 'true';
+const { integrity, http } = await runStaticSmokeTestWithIntegrity('smoke.cases.json', {
+  skipIntegrity,
+});
+```
+
+## CMS article-link integrity (local only)
+
+Opt-in via `cmsIntegrity` in `smoke.cases.json`. Fetches all article links from Contentful once; validates `href` for entries with body content. **Not** used on deployment / live smoke.
+
+```json
+{
+  "cmsIntegrity": {
+    "enabled": true,
+    "routing": {
+      "articleTypesBasePath": "/resources",
+      "tagsBasePath": "/topics",
+      "peopleBasePath": "/team",
+      "defaultTopic": "other",
+      "enablePrimaryTagPartOfSlug": true,
+      "topiclessArticleTypeSlugs": ["ebooks"]
+    }
+  }
+}
+```
+
+```ts
+import { runArticleLinkIntegrityFromSmokeConfig } from '@se-studio/site-check/cms-integrity';
+// or from smoke-test barrel: runArticleLinkIntegrityFromSmokeConfig
+```
+
+**Deps when enabled:** `@se-studio/contentful-rest-api@^1.10.0`, `@se-studio/core-data-types@^1.5.1`, Contentful env in `.env.local`.
+
+**`pnpm smoke-test`:** `smoke-test-one` runs integrity in parallel with dev server boot; sets `SMOKE_TEST_SKIP_INTEGRITY=true` on the HTTP child run.
+
+## Smoke env vars
+
+| Variable | Purpose |
+|----------|---------|
+| `SMOKE_TEST_IGNORE=true` | Skip smoke entirely |
+| `SMOKE_TEST_SERVER_SCRIPT` | `dev:dev` (default) or `start` |
+| `SMOKE_TEST_SKIP_INTEGRITY` | HTTP-only (set by smoke-test-one when integrity parallel) |
+| `PREVIEW_SITE_URL` | Preview smoke base URL |
+| `DEPLOYMENT_URL` | Live deployment smoke URL |
+| `VERCEL_PROTECTION_BYPASS_TOKEN` | Deployment Protection bypass |
+
+## Vercel build cache (not smoke)
+
+Set on **Vercel project** env (not app `.env.local`, not `vercel.json`):
+
+| Variable | Value | Purpose |
+|----------|-------|---------|
+| `VERCEL_FORCE_NO_BUILD_CACHE` | `1` | Skip remote build cache when webpack `WasmHash` fails on Vercel |
+
+Mitigates intermittent `WasmHash._updateWithBuffer` / `Cannot read properties of undefined (reading 'length')` during `next build`. Local builds may still pass.
+
+## Skill
+
+Setup and regeneration: `se-marketing-sites-smoke-test-setup` (`@se-studio/skills`). Example app: `apps/example-empty`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@se-studio/site-check",
-  "version": "2.6.1",
+  "version": "2.6.3",
   "description": "Validate SE marketing sites (sitemap, llms.txt) and download markdown files preserving structure",
   "repository": {
     "type": "git",
@@ -49,6 +49,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "*.md",
     "smoke-test-one.mjs",
     "smoke-test-deploy-check.mjs",
@@ -70,7 +71,7 @@
     "url": "https://github.com/Something-Else-Studio/se-core-product/issues"
   },
   "dependencies": {
-    "@se-studio/contentful-rest-api": "1.10.0",
+    "@se-studio/contentful-rest-api": "1.11.0",
     "@se-studio/core-data-types": "1.5.1"
   },
   "devDependencies": {