crawlemon 0.1.0 → 0.3.0

package/README.md

@@ -1,14 +1,42 @@
 # Crawlemon
 
-**Deterministic SEO checks for Next.js projects.**
+**SEO CI for modern web apps — catch SEO regressions before you merge.**
 
-Crawlemon is a developer-first SEO audit and safe-fix CLI. It works like a lightweight ESLint for SEO: run it inside a Next.js repository, find issues before they reach production, and automatically repair changes that are deterministic and safe.
+Crawlemon is the SEO safety layer between code and production. It works like an ESLint / Dependabot for SEO: run it locally or in CI, evaluate the SEO Quality Gate, prevent search regressions from merging, and automatically apply safe deterministic fixes.
 
 No account, cloud connection, browser, AI provider, or API key is required.
 
+## What is new in 0.3.0
+
+- Production-grade static resolution for Next.js: site config, `metadataBase`, title objects (`default`/`template`/`absolute`), and layout inheritance.
+- Relative canonical URLs are resolved (not flagged) when a site origin is known.
+- Dynamic metadata from `generateMetadata` is no longer reported as missing, and duplicate-title findings only fire for statically declared, indexable titles.
+- Internal links and sitemaps are validated against dynamic routes and `generateStaticParams`.
+- `<h1>` headings inside locally-imported components are detected; redirect-only pages are exempted.
+
+## What is new in 0.2.0
+
+- Stable deterministic audit and graph ordering.
+- Clean-As-You-Code confidence enforcement: unverified AI hypotheses cannot block.
+- Independent evidence and rejected-claim recording for semantic AI resolution.
+- Safer AI fix boundaries and zero-new-regression sandbox verification.
+- Expanded adversarial, integration, and high-cardinality coverage.
+
 ## Quick start
 
-Run an audit from the root of a Next.js project:
+Compare your current branch/working tree against `main` and evaluate the SEO Quality Gate:
+
+```bash
+npx crawlemon diff
+```
+
+Or compare against a specific git base ref:
+
+```bash
+npx crawlemon diff --base origin/main
+```
+
+Run a full local audit:
 
 ```bash
 npx crawlemon audit
@@ -29,14 +57,20 @@ npx crawlemon fix
 ## Requirements
 
 - Node.js 20 or newer
-- A Next.js project using the App Router or Pages Router
+- Supported framework: Next.js, Nuxt, SvelteKit, Astro, Remix, Vite, or static HTML
 - Run the command from the project root
 
 Crawlemon uses static source analysis. It does not run your application, install its dependencies, or execute repository scripts.
 
 ## Commands
 
-### `audit`
+### `diff`
+
+Compare code changes vs base ref, compute blast radius, and evaluate the SEO Quality Gate:
+
+```bash
+npx crawlemon diff [--base <ref>] [--json]
+```
 
 Discover routes and run deterministic SEO checks:
 
@@ -149,6 +183,62 @@ npx crawlemon --help
 npx crawlemon --version
 ```
 
+## GitHub Actions
+
+Run Crawlemon on every pull request and every push to `main` by creating
+`.github/workflows/crawlemon.yml` in your Next.js repository:
+
+```yaml
+name: SEO audit
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  crawlemon:
+    name: Crawlemon
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Audit SEO
+        env:
+          CI: true
+        run: npx --yes crawlemon@0.3.0 audit
+```
+
+The exact package version is pinned so an upstream release cannot unexpectedly
+change your CI result. Update `crawlemon@0.3.0` deliberately when you are ready
+to adopt a newer version.
+
+With `CI=true`, the workflow fails when Crawlemon finds at least one error-level
+issue. Warnings and notices remain visible in the report without failing the job.
+No repository secret, API key, dependency installation, or build step is required.
+
+If the Next.js application is inside a monorepo subdirectory, set the step's
+working directory:
+
+```yaml
+      - name: Audit SEO
+        working-directory: apps/web
+        env:
+          CI: true
+        run: npx --yes crawlemon@0.3.0 audit
+```
+
 ## Zero-configuration detection
 
 Crawlemon automatically detects:

package/dist/index.d.ts

@@ -1 +1,6 @@
+import type { AuditResult } from "@crawlemon/shared";
+/**
+ * Safely audits a base git ref without running untrusted scripts or executing builds.
+ */
+export declare function auditGitRef(projectRoot: string, ref: string): Promise<AuditResult>;
 export declare function runCli(args: string[]): Promise<void>;