@schemasentry/cli 0.5.0 → 0.6.0

package/README.md

@@ -9,6 +9,17 @@ pnpm add -D @schemasentry/cli
 npm install -D @schemasentry/cli
 ```
 
+## Important: Zero False Positives!
+
+Schema Sentry v0.6.0+ validates **actual built HTML output**, not just JSON configuration files. This eliminates the false positives common in other tools.
+
+**The workflow:**
+1. `init` → Create starter files
+2. `scaffold` → See what code to add (shows copy-paste examples!)
+3. Add Schema components to your pages
+4. `next build` → Build your app
+5. `validate` → Check actual HTML (catches missing schema!)
+
 ## Commands
 
 ### `init`
@@ -25,96 +36,136 @@ With route scanning:
 pnpm schemasentry init --scan
 ```
 
-### `validate`
+### `validate` (Reality Check)
 
-Check schema coverage and validation:
+⚠️ **BREAKING CHANGE in v0.6.0**: Now validates actual HTML output instead of JSON files!
+
+Validate schema by checking built HTML output:
 
 ```bash
-pnpm schemasentry validate --manifest ./schema-sentry.manifest.json --data ./schema-sentry.data.json
+# Build your app first
+next build
+
+# Then validate (catches missing schema with zero false positives!)
+pnpm schemasentry validate \
+  --manifest ./schema-sentry.manifest.json \
+  --root ./.next/server/app
 ```
 
-With GitHub annotations:
+Check static export:
 
 ```bash
-pnpm schemasentry validate --annotations github
+pnpm schemasentry validate \
+  --manifest ./schema-sentry.manifest.json \
+  --root ./out
 ```
 
-### `audit`
+**What it validates:**
+- ✅ Routes with Schema components in source code
+- ✅ Actual JSON-LD rendered in built HTML
+- ✅ Schema types match manifest expectations
+- ❌ Ghost routes (manifest expects schema but no component in source)
+- ❌ Missing schema (component exists but not in HTML - forgot to build?)
 
-Analyze site-wide schema health:
+With GitHub annotations:
 
 ```bash
-pnpm schemasentry audit --data ./schema-sentry.data.json --manifest ./schema-sentry.manifest.json
+pnpm schemasentry validate --annotations github
 ```
 
-With HTML report:
+### `audit`
+
+Analyze site-wide schema health and detect ghost routes:
 
 ```bash
 pnpm schemasentry audit \
-  --data ./schema-sentry.data.json \
-  --format html \
-  --output ./report.html
+  --manifest ./schema-sentry.manifest.json \
+  --root ./app
 ```
 
-### `collect`
+**Ghost routes** are routes in your manifest that don't have Schema components in the source code. They cause false positives in other tools!
 
-Collect JSON-LD blocks from built HTML output and emit schema data JSON:
+With source scanning:
 
 ```bash
-pnpm schemasentry collect --root ./out --output ./schema-sentry.data.json
+pnpm schemasentry audit --manifest ./schema-sentry.manifest.json --root ./app --scan
 ```
 
-Check collected output against your current data file (CI drift guard):
-
-```bash
-pnpm schemasentry collect --root ./out --check --data ./schema-sentry.data.json
-```
+### `scaffold`
 
-Collect and compare only selected routes, failing if any required route is missing:
+See what schema code you need to add to your pages (shows copy-paste examples):
 
 ```bash
-pnpm schemasentry collect \
-  --root ./out \
-  --routes / /blog /faq \
-  --strict-routes \
-  --check \
-  --data ./schema-sentry.data.json
+pnpm schemasentry scaffold --root ./app
 ```
 
-### `scaffold`
+Example output:
+```
+📄 /blog/[slug]
+   File: app/blog/[slug]/page.tsx
+   Types: BlogPosting
+
+   Add this code to your page:
+   ─────────────────────────────────────────
+   import { Schema, BlogPosting } from "@schemasentry/next";
+
+   const blogPosting = BlogPosting({
+     headline: "Blog Post Title",
+     authorName: "Author Name",
+     datePublished: "2026-02-12",
+     url: "https://yoursite.com/blog/[slug]"
+   });
+
+   export default function Page() {
+     return (
+       <>
+         <Schema data={[blogPosting]} />
+         {/* Your existing content */}
+       </>
+     );
+   }
+   ─────────────────────────────────────────
+```
 
-Auto-generate schema stubs for routes without schema (dry-run by default):
+Apply scaffolded schema to JSON files:
 
 ```bash
-pnpm schemasentry scaffold --manifest ./schema-sentry.manifest.json --data ./schema-sentry.data.json
+pnpm schemasentry scaffold --root ./app --write
 ```
 
-Preview what would be generated without writing files:
+**Pattern-based auto-detection** infers schema types from URL patterns:
+- `/blog/*` → BlogPosting
+- `/products/*` → Product
+- `/faq` → FAQPage
+- `/events/*` → Event
+- `/howto/*` → HowTo
+- and more...
+
+### `collect`
+
+Collect JSON-LD blocks from built HTML output:
 
 ```bash
-pnpm schemasentry scaffold
+pnpm schemasentry collect --root ./out --output ./schema-sentry.data.json
 ```
 
-Apply scaffolded schema to your files:
+Check collected output against your current data file (CI drift guard):
 
 ```bash
-pnpm schemasentry scaffold --write
+pnpm schemasentry collect --root ./out --check --data ./schema-sentry.data.json
 ```
 
-Skip confirmation prompts:
+Collect and compare only selected routes, failing if any required route is missing:
 
 ```bash
-pnpm schemasentry scaffold --write --force
+pnpm schemasentry collect \
+  --root ./out \
+  --routes / /blog /faq \
+  --strict-routes \
+  --check \
+  --data ./schema-sentry.data.json
 ```
 
-**Pattern-based auto-detection** infers schema types from URL patterns:
-- `/blog/*` → BlogPosting
-- `/products/*` → Product
-- `/faq` → FAQPage
-- `/events/*` → Event
-- `/howto/*` → HowTo
-- and more...
-
 ## Options
 
 | Option | Description |
@@ -122,7 +173,8 @@ pnpm schemasentry scaffold --write --force
 | `--format json\|html` | Output format |
 | `--annotations none\|github` | CI annotations |
 | `-o, --output <path>` | Write output to file |
-| `--root <path>` | Root directory to scan (`collect`, `scaffold`) |
+| `--root <path>` | Root directory (built output for validate/collect, app dir for scaffold/audit) |
+| `--app-dir <path>` | Path to Next.js app directory (default: ./app) |
 | `--routes <routes...>` | Collect only specific routes (`collect`) |
 | `--strict-routes` | Fail when any route passed to `--routes` is missing (`collect`) |
 | `--check` | Compare collected output with existing data and fail on drift (`collect`) |
@@ -130,6 +182,44 @@ pnpm schemasentry scaffold --write --force
 | `--force` | Skip confirmation prompts (`scaffold`) |
 | `--recommended / --no-recommended` | Enable recommended field checks |
 
+## CI/CD Example
+
+```yaml
+# .github/workflows/schema-check.yml
+name: Schema Check
+
+on: [push, pull_request]
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: pnpm/action-setup@v2
+      - run: pnpm install
+      - run: pnpm build
+      - run: pnpm schemasentry validate \
+          --manifest ./schema-sentry.manifest.json \
+          --root ./.next/server/app \
+          --annotations github
+```
+
+## Migration from v0.5.0
+
+**OLD (v0.5.0 - JSON validation - FALSE POSITIVES):**
+```bash
+schemasentry validate --manifest ./manifest.json --data ./data.json
+```
+
+**NEW (v0.6.0 - Reality check - NO FALSE POSITIVES):**
+```bash
+# 1. Build your app first
+next build
+
+# 2. Validate actual HTML
+schemasentry validate --manifest ./manifest.json --root ./.next/server/app
+```
+
 ## Documentation
 
 See [Schema Sentry Docs](https://github.com/arindamdawn/schema-sentry#readme)