local-seo-lint 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Clicks Dynasty
+
+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

@@ -0,0 +1,233 @@
+# local-seo-lint
+
+**Catch local SEO and AI-search mistakes before they go live.**
+
+`local-seo-lint` scans a static website folder and flags the problems that quietly hurt local rankings: a phone number that's different on one page, schema that disagrees with the page, two pages fighting for the same search, pages Google can't find, and more.
+
+- Zero dependencies. Node 18+.
+- Works on any static site: plain HTML, Hugo, Jekyll, Eleventy, Astro, Next.js static export.
+- Runs locally, in CI, or as a GitHub Action with inline annotations on pull requests.
+- Nothing is sent anywhere. It only reads your files.
+
+## Why this exists
+
+General SEO linters check one page at a time: is there a title, is there a meta description. Local SEO problems usually live **between** pages:
+
+- Your homepage schema says one phone number, your contact page shows another.
+- The footer says "Suite 4" on most pages and leaves it out on one.
+- Four pages all target "Bakersfield digital marketing agency", so Google splits the credit and none of them rank.
+- A new landing page was never linked from anywhere, so Google never finds it.
+
+We built this at [Clicks Dynasty](https://www.clicksdynasty.com), a local SEO agency, after finding exactly these problems on real sites, including our own. Running it against an older version of our site flagged the four pages that were all competing for "Bakersfield digital marketing agency", the same problem we had found by hand.
+
+## Quick start
+
+```bash
+# Run straight from GitHub, no install
+npx github:clicksdynastyincali/local-seo-lint ./my-site
+
+# Or clone and run
+git clone https://github.com/clicksdynastyincali/local-seo-lint.git
+node local-seo-lint/bin/local-seo-lint.js ./my-site
+```
+
+Point it at the folder that contains your HTML files (for generated sites, the build output such as `public/` or `dist/`).
+
+### Example output
+
+```text
+local-seo-lint  5 pages scanned
+Business: Oak Street Plumbing | 123 Example Ave, Suite 4 | +1-661-555-0123  (from schema on index.html)
+
+error broken-link (1)  Internal link points to a page that does not exist.
+   index.html  Link to "pricing.html" goes nowhere.
+
+error json-ld-syntax (1)  JSON-LD blocks must be valid JSON, or search engines ignore them.
+   services.html  JSON-LD block #1 is invalid: Expected double-quoted property name in JSON at position 77 (line 1 column 78)
+
+error nap-schema-mismatch (1)  Business schema on a page disagrees with your business name, address or phone.
+   contact.html  Schema phone +1-661-555-0100 differs from your business phone +1-661-555-0123.
+
+error sitemap-dead-url (1)  sitemap.xml lists a URL with no matching page.
+   sitemap.xml  Lists https://www.example.com/deleted-page.html, but no such page exists.
+
+warn  canonical-missing (1)  Page has no canonical tag.
+   contact.html  Add <link rel="canonical" href="https://www.example.com/contact.html">.
+
+warn  description-duplicate (2)  Several pages share the same meta description.
+   drain-cleaning-bakersfield.html  Same meta description as services.html.
+   services.html  Same meta description as drain-cleaning-bakersfield.html.
+
+warn  keyword-overlap (1)  Two pages target nearly the same search, so they compete with each other.
+   drain-cleaning-bakersfield.html  "Drain Cleaning Services in Bakersfield" competes with services.html ("Drain Cleaning Services in Bakersfield"), 100% overlap. Pick one page for this search.
+
+warn  nap-address-mismatch (1)  Your address is written differently on this page.
+   contact.html  Address written as "123 Example Ave, Bakersfield anytime. Oak Str"; standard form is "123 Example Ave, Suite 4".
+
+warn  nap-phone-mismatch (1)  A phone number on the page differs from your business phone.
+   services.html  Shows (661) 555-0199; your business phone is +1-661-555-0123.
+
+warn  orphan-page (1)  No other page links here, so crawlers struggle to find it.
+   drain-cleaning-bakersfield.html  No other page links to this page.
+
+warn  schema-not-visible (1)  Schema says something the visitor cannot see on the page.
+   contact.html  Schema phone +1-661-555-0100 is not visible on the page.
+
+warn  sitemap-page-missing (1)  Indexable page is not listed in sitemap.xml.
+   drain-cleaning-bakersfield.html  Not listed in sitemap.xml.
+
+warn  title-duplicate (2)  Several pages share the same title.
+   drain-cleaning-bakersfield.html  Same title as services.html.
+   services.html  Same title as drain-cleaning-bakersfield.html.
+
+4 errors, 11 warnings
+```
+
+This is the output for the small demo site in [`test/fixtures/site`](test/fixtures/site).
+
+## What it checks
+
+| Rule | Default | What it catches |
+|---|---|---|
+| `nap-schema-mismatch` | error | Business schema on a page has a different phone, street or ZIP than your business |
+| `nap-phone-mismatch` | warn | A phone number shown on a page isn't your business number |
+| `nap-address-mismatch` | warn | Your street address is written differently (knows that "Avenue #4" = "Ave, Suite 4") |
+| `schema-not-visible` | warn | Schema claims a name or phone that visitors can't see on the page |
+| `json-ld-syntax` | error | A JSON-LD block is invalid JSON, so search engines ignore it |
+| `keyword-overlap` | warn | Two pages target nearly the same search (keyword cannibalization) |
+| `orphan-page` | warn | No other page links to this page |
+| `broken-link` | error | Internal link to a page or file that doesn't exist |
+| `sitemap-page-missing` | warn | Indexable page not listed in `sitemap.xml` |
+| `sitemap-dead-url` | error | `sitemap.xml` lists a page that doesn't exist |
+| `sitemap-noindex` | error | `sitemap.xml` lists a page marked `noindex` |
+| `sitemap-missing` | warn | No `sitemap.xml` at all |
+| `canonical-missing` | warn | Page has no canonical tag |
+| `canonical-multiple` | error | More than one canonical tag |
+| `canonical-relative` | warn | Canonical URL isn't absolute |
+| `canonical-other-page` | warn | Canonical points to a different page (so this one won't rank) |
+| `canonical-broken` | error | Canonical points to a page that doesn't exist |
+| `title-missing` / `title-duplicate` | error / warn | Missing or repeated `<title>` |
+| `description-missing` / `description-duplicate` | warn | Missing or repeated meta description |
+| `h1-missing` | warn | Page has no `<h1>` |
+| `ai-crawler-blocked` | error | `robots.txt` blocks an AI search crawler (OAI-SearchBot, ChatGPT-User, PerplexityBot, Claude-SearchBot, Bingbot, Applebot), so the business can't appear in AI answers |
+| `ai-entity-links-missing` | warn | Homepage business schema has no `sameAs` links (Google Business Profile, Facebook, LinkedIn, Yelp), so AI tools can't confirm which business it is |
+
+Pages marked `noindex`, `404.html`, and pages that are 301-redirected in `.htaccess` or `_redirects` are skipped where it makes sense.
+
+### How business details are found
+
+NAP checks compare every page against one "source of truth":
+
+1. The `business` block in `.localseorc.json`, if you have one, or
+2. The first LocalBusiness/Organization schema with an address or phone on your homepage.
+
+### How keyword overlap works
+
+Each page's "target phrases" are its title segments (split on `|`, `-`, `:`) plus its `<h1>`, with your brand name removed. Phrases are compared using overlap weighted by how rare each word is on your site, so words used everywhere (your city, "services") count less than distinctive ones. A title suffix repeated on many pages (like "| Bakersfield & Central Valley, CA") is treated as boilerplate, not a target.
+
+## Configuration
+
+Optional. Create `.localseorc.json` in your site folder:
+
+```json
+{
+  "siteUrl": "https://www.example.com",
+  "business": {
+    "name": "Oak Street Plumbing",
+    "phone": "+1-661-555-0123",
+    "address": { "street": "123 Example Ave, Suite 4", "postalCode": "93301" }
+  },
+  "ignore": ["drafts/**", "backup/**"],
+  "overlap": { "threshold": 0.8 },
+  "rules": {
+    "description-duplicate": "off",
+    "orphan-page": "error"
+  }
+}
+```
+
+Every rule can be set to `"off"`, `"warn"` or `"error"`.
+
+## CLI options
+
+```text
+Usage: local-seo-lint [folder] [options]
+
+Checks a static website folder for local SEO problems.
+
+Options:
+  --config <file>        Config file (default: .localseorc.json in the folder)
+  --ignore <glob>        Skip files/folders (repeatable), e.g. --ignore "drafts/**"
+  --format <pretty|json|github>   Output format (default: pretty)
+  --limit <n>            Max findings shown per rule in pretty output (0 = all, default 10)
+  --max-warnings <n>     Fail if there are more than n warnings (default: no limit)
+  --no-color             Disable colors
+  --no-footer            Hide the "need help?" line under the results
+  -h, --help             Show this help
+  -v, --version          Show version
+
+Exit code: 1 if any errors (or too many warnings), otherwise 0.
+```
+
+## GitHub Action
+
+Add [`examples/local-seo-lint.yml`](examples/local-seo-lint.yml) to `.github/workflows/` in your website repository:
+
+```yaml
+# Save as .github/workflows/local-seo-lint.yml in your website repository.
+name: Local SEO Lint
+on:
+  push:
+  pull_request:
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - uses: clicksdynastyincali/local-seo-lint@main
+        with:
+          path: .            # or your build output folder, e.g. public/ or dist/
+          ignore: "drafts/**"
+```
+
+Problems appear as annotations on the changed files in pull requests, and errors fail the check.
+
+### AI search checks
+
+More customers now ask ChatGPT and Perplexity to recommend local businesses. In our [California AI Visibility Index](https://www.clicksdynasty.com/california-ai-visibility-index.html), the two tools agreed on only about 1 in 4 of the businesses they recommended. Two things on your own site decide whether you can show up at all:
+
+- **Crawler access.** If `robots.txt` blocks the crawlers that fetch pages for AI answers, those tools can't read your site. Blocking *training* crawlers such as `GPTBot` or `ClaudeBot` is your choice and is not flagged.
+- **Entity links.** `sameAs` links in your business schema tie your website to your Google, Yelp and social profiles, which is how AI tools check they have the right business.
+
+## Limitations
+
+- Built for static HTML. It does not run JavaScript, so content injected client-side isn't seen.
+- Phone detection is tuned for US/Canada formats.
+- It checks your own files, not third-party listings (Google Business Profile, Yelp and so on).
+- Redirect detection understands simple `.htaccess` `Redirect`/`RewriteRule [R=301]` lines and Netlify-style `_redirects`; complex regex rules are ignored.
+
+## Roadmap
+
+- Opening-hours consistency between schema and visible text
+- Compare site details with a Google Business Profile export
+- Near-duplicate location page detection (doorway pages)
+- International phone formats
+
+Issues and pull requests are welcome.
+
+## For agencies
+
+Running this on client sites and finding more than your team has time to fix? [Clicks Dynasty](https://www.clicksdynasty.com) fixes local SEO and AI-visibility issues white-label, under your brand, and never contacts your clients. [Book a free call](https://www.clicksdynasty.com/book.html?service=strategy).
+
+## Development
+
+```bash
+npm test
+```
+
+## License
+
+MIT. Built by [Clicks Dynasty](https://www.clicksdynasty.com), a local SEO and digital marketing agency in Bakersfield, California.

package/action.yml

@@ -0,0 +1,40 @@
+name: 'Local SEO Lint'
+description: 'Catch local SEO and AI-search mistakes: blocked AI crawlers, NAP mismatches, schema, canonicals and sitemaps.'
+author: 'Clicks Dynasty'
+branding:
+  icon: 'map-pin'
+  color: 'green'
+inputs:
+  path:
+    description: 'Folder containing your built HTML site'
+    required: false
+    default: '.'
+  config:
+    description: 'Path to a config file (default: .localseorc.json inside the folder)'
+    required: false
+    default: ''
+  ignore:
+    description: 'Comma-separated globs to skip, e.g. "drafts/**,backup/**"'
+    required: false
+    default: ''
+  max-warnings:
+    description: 'Fail the job if there are more warnings than this (leave empty for no limit)'
+    required: false
+    default: ''
+runs:
+  using: 'composite'
+  steps:
+    - name: Run local-seo-lint
+      shell: bash
+      env:
+        LSL_PATH: ${{ inputs.path }}
+        LSL_CONFIG: ${{ inputs.config }}
+        LSL_IGNORE: ${{ inputs.ignore }}
+        LSL_MAXW: ${{ inputs.max-warnings }}
+      run: |
+        args=("$LSL_PATH" --format github --limit 0)
+        [ -n "$LSL_CONFIG" ] && args+=(--config "$LSL_CONFIG")
+        [ -n "$LSL_MAXW" ] && args+=(--max-warnings "$LSL_MAXW")
+        IFS=',' read -ra globs <<< "$LSL_IGNORE"
+        for g in "${globs[@]}"; do g="$(echo "$g" | xargs)"; [ -n "$g" ] && args+=(--ignore "$g"); done
+        node "${{ github.action_path }}/bin/local-seo-lint.js" "${args[@]}"

package/bin/local-seo-lint.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+'use strict';
+const path = require('path');
+const { lint } = require('../src');
+const { pretty, github } = require('../src/report');
+
+const HELP = `Usage: local-seo-lint [folder] [options]
+
+Checks a static website folder for local SEO problems.
+
+Options:
+  --config <file>        Config file (default: .localseorc.json in the folder)
+  --ignore <glob>        Skip files/folders (repeatable), e.g. --ignore "drafts/**"
+  --format <pretty|json|github>   Output format (default: pretty)
+  --limit <n>            Max findings shown per rule in pretty output (0 = all, default 10)
+  --max-warnings <n>     Fail if there are more than n warnings (default: no limit)
+  --no-color             Disable colors
+  --no-footer            Hide the "need help?" line under the results
+  -h, --help             Show this help
+  -v, --version          Show version
+
+Exit code: 1 if any errors (or too many warnings), otherwise 0.`;
+
+function main(argv) {
+  const args = { ignore: [], format: 'pretty', limit: 10, color: process.stdout.isTTY, footer: true };
+  let dir = '.';
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const val = () => { if (i + 1 >= argv.length) throw new Error(`${a} needs a value`); return argv[++i]; };
+    if (a === '-h' || a === '--help') { console.log(HELP); return 0; }
+    else if (a === '-v' || a === '--version') { console.log(require('../package.json').version); return 0; }
+    else if (a === '--config') args.config = val();
+    else if (a === '--ignore') args.ignore.push(val());
+    else if (a === '--format') args.format = val();
+    else if (a === '--limit') args.limit = parseInt(val(), 10) || Infinity;
+    else if (a === '--max-warnings') args.maxWarnings = parseInt(val(), 10);
+    else if (a === '--no-color') args.color = false;
+    else if (a === '--no-footer') args.footer = false;
+    else if (a.startsWith('-')) throw new Error(`Unknown option ${a}`);
+    else dir = a;
+  }
+  const root = path.resolve(dir);
+  const res = lint(root, { config: args.config, ignore: args.ignore });
+  if (args.format === 'json') console.log(JSON.stringify(res, null, 2));
+  else if (args.format === 'github') { const g = github(res, path.relative(process.cwd(), root)); if (g) console.log(g); console.log(pretty(res, { color: false, limit: args.limit, footer: args.footer })); }
+  else console.log(pretty(res, { color: args.color, limit: args.limit, footer: args.footer }));
+  if (res.errors > 0) return 1;
+  if (Number.isFinite(args.maxWarnings) && res.warnings > args.maxWarnings) return 1;
+  return 0;
+}
+
+try { process.exitCode = main(process.argv.slice(2)); }
+catch (e) { console.error('local-seo-lint: ' + e.message); process.exitCode = 2; }

package/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "local-seo-lint",
+  "version": "0.2.0",
+  "description": "Catch local SEO and AI-search mistakes before they go live: AI crawler access, NAP consistency, schema vs. page, canonicals, sitemap coverage, orphan pages and keyword overlap for static websites.",
+  "bin": { "local-seo-lint": "bin/local-seo-lint.js" },
+  "main": "src/index.js",
+  "files": ["bin", "src", "action.yml"],
+  "scripts": { "test": "node --test" },
+  "engines": { "node": ">=18" },
+  "keywords": ["seo", "local-seo", "lint", "schema", "json-ld", "nap", "static-site", "github-action", "sitemap", "canonical", "ai-search", "chatgpt", "perplexity", "robots-txt"],
+  "author": "Clicks Dynasty (https://www.clicksdynasty.com)",
+  "license": "MIT",
+  "repository": { "type": "git", "url": "https://github.com/clicksdynastyincali/local-seo-lint.git" },
+  "homepage": "https://github.com/clicksdynastyincali/local-seo-lint#readme"
+}

package/src/checks.js

@@ -0,0 +1,257 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { phoneDigits, findPhones, normAddress, normName, businessEntities } = require('./nap');
+
+const RULES = {
+  'json-ld-syntax': { severity: 'error', about: 'JSON-LD blocks must be valid JSON, or search engines ignore them.' },
+  'nap-schema-mismatch': { severity: 'error', about: 'Business schema on a page disagrees with your business name, address or phone.' },
+  'nap-phone-mismatch': { severity: 'warn', about: 'A phone number on the page differs from your business phone.' },
+  'nap-address-mismatch': { severity: 'warn', about: 'Your address is written differently on this page.' },
+  'schema-not-visible': { severity: 'warn', about: 'Schema says something the visitor cannot see on the page.' },
+  'canonical-missing': { severity: 'warn', about: 'Page has no canonical tag.' },
+  'canonical-multiple': { severity: 'error', about: 'Page has more than one canonical tag.' },
+  'canonical-relative': { severity: 'warn', about: 'Canonical URL should be absolute (https://...).' },
+  'canonical-other-page': { severity: 'warn', about: 'Canonical points to a different page, so this page will not rank.' },
+  'canonical-broken': { severity: 'error', about: 'Canonical points to a page that does not exist.' },
+  'sitemap-missing': { severity: 'warn', about: 'No sitemap.xml found.' },
+  'sitemap-page-missing': { severity: 'warn', about: 'Indexable page is not listed in sitemap.xml.' },
+  'sitemap-dead-url': { severity: 'error', about: 'sitemap.xml lists a URL with no matching page.' },
+  'sitemap-noindex': { severity: 'error', about: 'sitemap.xml lists a page marked noindex.' },
+  'orphan-page': { severity: 'warn', about: 'No other page links here, so crawlers struggle to find it.' },
+  'broken-link': { severity: 'error', about: 'Internal link points to a page that does not exist.' },
+  'title-missing': { severity: 'error', about: 'Page has no <title>.' },
+  'title-duplicate': { severity: 'warn', about: 'Several pages share the same title.' },
+  'description-missing': { severity: 'warn', about: 'Page has no meta description.' },
+  'description-duplicate': { severity: 'warn', about: 'Several pages share the same meta description.' },
+  'h1-missing': { severity: 'warn', about: 'Page has no <h1>.' },
+  'keyword-overlap': { severity: 'warn', about: 'Two pages target nearly the same search, so they compete with each other.' },
+  'ai-crawler-blocked': { severity: 'error', about: 'robots.txt blocks an AI search crawler, so ChatGPT, Perplexity or Claude cannot read or recommend the site.' },
+  'ai-entity-links-missing': { severity: 'warn', about: 'Business schema has no sameAs profile links, so AI tools cannot confirm which business this is.' },
+};
+
+// Crawlers that fetch pages for AI search answers (not model training). Blocking these hides a business from AI recommendations.
+const AI_SEARCH_BOTS = ['OAI-SearchBot', 'ChatGPT-User', 'PerplexityBot', 'Perplexity-User', 'Claude-SearchBot', 'Claude-User', 'Bingbot', 'Applebot'];
+
+// Minimal robots.txt reader: returns true if `agent` may not fetch "/".
+function robotsBlocksRoot(txt, agent) {
+  const groups = []; let cur = null, lastWasAgent = false;
+  txt.split(/\r?\n/).forEach((raw) => {
+    const line = raw.replace(/#.*/, '').trim();
+    const m = line.match(/^([A-Za-z-]+)\s*:\s*(.*)$/);
+    if (!m) return;
+    const key = m[1].toLowerCase(), val = m[2].trim();
+    if (key === 'user-agent') { if (!lastWasAgent) { cur = { agents: [], rules: [] }; groups.push(cur); } cur.agents.push(val.toLowerCase()); lastWasAgent = true; return; }
+    lastWasAgent = false;
+    if (cur && (key === 'allow' || key === 'disallow')) cur.rules.push({ allow: key === 'allow', path: val });
+  });
+  const a = agent.toLowerCase();
+  let rules = groups.filter((g) => g.agents.includes(a)).flatMap((g) => g.rules);
+  if (!groups.some((g) => g.agents.includes(a))) rules = groups.filter((g) => g.agents.includes('*')).flatMap((g) => g.rules);
+  const hits = rules.filter((r) => r.path && '/'.startsWith(r.path.replace(/\*$/, '').replace(/\$$/, '')));
+  if (!hits.length) return false;
+  const best = hits.reduce((x, y) => (y.path.length > x.path.length || (y.path.length === x.path.length && y.allow) ? y : x));
+  return !best.allow;
+}
+
+const STOP = new Set('a an and or the of in on for to with by at from your our you we is are be as it this that best top free near me vs & | - – — : , ca usa us'.split(' '));
+
+function resolver(site, siteOrigin) {
+  const hosts = new Set();
+  if (siteOrigin) { const h = new URL(siteOrigin).host.replace(/^www\./, ''); hosts.add(h); hosts.add('www.' + h); }
+  const lookup = (p) => {
+    let dp; try { dp = decodeURIComponent(p); } catch (e) { dp = p; }
+    return site.byPath.get(dp) || site.byPath.get(dp + (dp.endsWith('/') ? 'index.html' : '/index.html')) || site.byPath.get(dp + '.html') || site.byPath.get(dp.replace(/\/$/, '')) || null;
+  };
+  const resolve = (fromPath, href) => {
+    if (!href) return { skip: true };
+    const h = href.trim();
+    if (/^(mailto:|tel:|javascript:|data:|sms:|#)/i.test(h)) return { skip: true };
+    let u;
+    try { u = new URL(h, 'https://local.invalid' + fromPath); } catch (e) { return { skip: true }; }
+    const local = u.host === 'local.invalid' || hosts.has(u.host);
+    if (!local) return { external: true };
+    const page = lookup(u.pathname);
+    let asset = false;
+    if (!page) { let dp; try { dp = decodeURIComponent(u.pathname); } catch (e) { dp = u.pathname; } const f = path.join(site.root, dp); asset = dp !== '/' && fs.existsSync(f) && fs.statSync(f).isFile(); }
+    return { path: u.pathname, page, asset, absolute: u.host !== 'local.invalid' };
+  };
+  return { resolve, lookup };
+}
+
+function detectBusiness(site, cfg) {
+  if (cfg.business && (cfg.business.name || cfg.business.phone || cfg.business.address)) {
+    const b = cfg.business;
+    return { source: 'config', name: b.name || null, phone: b.phone || null, street: (b.address && b.address.street) || b.street || null, postalCode: (b.address && b.address.postalCode) || b.postalCode || null };
+  }
+  const home = site.byPath.get('/') || site.pages[0];
+  if (!home) return null;
+  const ents = businessEntities(home.jsonldParsed).filter((e) => e.street || e.telephone);
+  if (!ents.length) return null;
+  const e = ents[0];
+  return { source: 'schema on ' + home.file, name: e.name, phone: e.telephone, street: e.street, postalCode: e.postalCode };
+}
+
+const GENERIC_SEG = new Set(['about us', 'about', 'contact us', 'contact', 'home', 'homepage', 'blog', 'faq', 'faqs', 'services', 'privacy policy', 'terms of service', 'careers', 'press', 'login', 'client login']);
+
+// Each title segment (split on | – — :) plus the H1 is a "target phrase".
+function targetPhrases(p, brand) {
+  const brandWords = new Set(brand ? normName(brand).split(' ') : []);
+  const segs = (p.title || '').split(/\s[|–—:-]\s|\s\|\s?|\s[–—]\s?/).map((x) => x.trim()).filter(Boolean);
+  if (p.h1[0]) segs.push(p.h1[0]);
+  return segs
+    .map((seg, i) => ({ seg, first: i === 0, h1: i === segs.length - 1 && !!p.h1[0] }))
+    .filter(({ seg }) => !(brand && normName(seg) === normName(brand)) && !GENERIC_SEG.has(seg.toLowerCase()))
+    .map(({ seg, first, h1 }) => ({ seg, first, h1, key: normName(seg), t: new Set(seg.toLowerCase().replace(/[^a-z0-9 ]+/g, ' ').split(/\s+/).filter((w) => w && !STOP.has(w) && w.length > 1 && !brandWords.has(w))) }))
+    .filter((x) => x.t.size >= 2);
+}
+
+function run(site, cfg = {}) {
+  const findings = [];
+  const add = (rule, file, message) => findings.push({ rule, severity: RULES[rule].severity, file, message });
+  const pages = site.pages;
+  const home = site.byPath.get('/');
+  const siteOrigin = cfg.siteUrl || (home && home.canonicals[0] && /^https?:\/\//.test(home.canonicals[0]) ? new URL(home.canonicals[0]).origin : null);
+  const { resolve } = resolver(site, siteOrigin);
+  const business = detectBusiness(site, cfg);
+  const bizPhone = business && business.phone ? phoneDigits(business.phone) : null;
+  const bizStreet = business && business.street ? normAddress(business.street) : null;
+  const bizZip = business && business.postalCode ? String(business.postalCode).trim() : null;
+  const bizStreetNum = bizStreet ? (bizStreet.match(/^\d+/) || [null])[0] : null;
+  const indexable = pages.filter((p) => !p.noindex && !p.redirected && !/(^|\/)404\.html?$/i.test(p.file));
+
+  // Links, orphans
+  const inbound = new Map(pages.map((p) => [p.file, 0]));
+  pages.forEach((p) => {
+    const seen = new Set();
+    p.hrefs.forEach((href) => {
+      const r = resolve(p.urlPath, href);
+      if (r.skip || r.external) return;
+      if (!r.page && r.asset) return;
+      if (!r.page) { if (!seen.has('x' + r.path)) add('broken-link', p.file, `Link to "${href}" goes nowhere.`); seen.add('x' + r.path); return; }
+      if (r.page !== p && !seen.has(r.page.file)) { inbound.set(r.page.file, inbound.get(r.page.file) + 1); seen.add(r.page.file); }
+    });
+  });
+  indexable.forEach((p) => { if (p.urlPath !== '/' && inbound.get(p.file) === 0) add('orphan-page', p.file, 'No other page links to this page.'); });
+
+  // Canonicals
+  pages.forEach((p) => {
+    if (p.noindex || p.redirected) return;
+    if (!p.canonicals.length) return add('canonical-missing', p.file, 'Add <link rel="canonical" href="' + (siteOrigin || 'https://your-site') + p.urlPath + '">.');
+    if (p.canonicals.length > 1) add('canonical-multiple', p.file, `Found ${p.canonicals.length} canonical tags; keep one.`);
+    const c = p.canonicals[0];
+    if (!/^https?:\/\//i.test(c)) add('canonical-relative', p.file, `Canonical "${c}" is relative; use the full https:// URL.`);
+    const r = resolve(p.urlPath, c);
+    if (r.external) return;
+    if (!r.skip && !r.page) add('canonical-broken', p.file, `Canonical "${c}" points to a page that does not exist.`);
+    else if (r.page && r.page !== p) add('canonical-other-page', p.file, `Canonical points to ${r.page.file}, so this page is hidden from search. Intended?`);
+  });
+
+  // Sitemap
+  if (!site.sitemap) add('sitemap-missing', 'sitemap.xml', 'Create a sitemap.xml listing every page you want indexed.');
+  else {
+    const listed = new Set();
+    site.sitemap.urls.forEach((u) => {
+      const r = resolve('/', u);
+      if (r.external) return;
+      if (!r.page) add('sitemap-dead-url', site.sitemap.file, `Lists ${u}, but no such page exists.`);
+      else { listed.add(r.page.file); if (r.page.noindex) add('sitemap-noindex', site.sitemap.file, `Lists ${u}, but that page is marked noindex.`); }
+    });
+    indexable.forEach((p) => {
+      const canonicalElsewhere = p.canonicals[0] && (() => { const r = resolve(p.urlPath, p.canonicals[0]); return r.page && r.page !== p; })();
+      if (!listed.has(p.file) && !canonicalElsewhere) add('sitemap-page-missing', p.file, 'Not listed in sitemap.xml.');
+    });
+  }
+
+  // Titles, descriptions, h1
+  const dupes = (key, rule, label) => {
+    const m = new Map();
+    indexable.forEach((p) => { const v = (p[key] || '').trim().toLowerCase(); if (v) m.set(v, (m.get(v) || []).concat(p)); });
+    m.forEach((list) => { if (list.length > 1) list.forEach((p) => add(rule, p.file, `Same ${label} as ${list.filter((x) => x !== p).map((x) => x.file).slice(0, 3).join(', ')}.`)); });
+  };
+  indexable.forEach((p) => {
+    if (!p.title) add('title-missing', p.file, 'Add a <title> that says what the page offers and where.');
+    if (!p.description) add('description-missing', p.file, 'Add a meta description (about 150 characters).');
+    if (!p.h1.length) add('h1-missing', p.file, 'Add one <h1> heading.');
+  });
+  dupes('title', 'title-duplicate', 'title');
+  dupes('description', 'description-duplicate', 'meta description');
+
+  // Keyword overlap (cannibalization): compare target phrases with IDF-weighted overlap,
+  // so words used everywhere (city names, "services") count less than distinctive ones.
+  const brand = business && business.name;
+  const phr = indexable.map((p) => ({ p, list: targetPhrases(p, brand) })).filter((x) => x.list.length);
+  const df = new Map();
+  phr.forEach(({ list }) => { const u = new Set(); list.forEach((x) => x.t.forEach((w) => u.add(w))); u.forEach((w) => df.set(w, (df.get(w) || 0) + 1)); });
+  const N = phr.length;
+  // Boilerplate title parts (the same suffix on 3+ pages, never used as the lead phrase) are not targets.
+  const segPages = new Map(), leadSegs = new Set();
+  phr.forEach(({ list }) => list.forEach((x) => { if (x.h1) return; segPages.set(x.key, (segPages.get(x.key) || 0) + 1); if (x.first) leadSegs.add(x.key); }));
+  phr.forEach((x) => { x.list = x.list.filter((A) => A.h1 || !(segPages.get(A.key) >= 3 && !leadSegs.has(A.key))); });
+  const wt = (w) => Math.log((N + 1) / ((df.get(w) || 0) + 1)) + 0.15;
+  const threshold = cfg.overlap && cfg.overlap.threshold ? cfg.overlap.threshold : 0.8;
+  for (let i = 0; i < phr.length; i++) for (let j = i + 1; j < phr.length; j++) {
+    let best = null;
+    phr[i].list.forEach((A) => phr[j].list.forEach((B) => {
+      let inter = 0, uni = 0, shared = [];
+      new Set([...A.t, ...B.t]).forEach((w) => { const x = wt(w); uni += x; if (A.t.has(w) && B.t.has(w)) { inter += x; shared.push(w); } });
+      const score = uni ? inter / uni : 0;
+      if (shared.length >= 3 && (!best || score > best.score)) best = { score, a: A.seg, b: B.seg };
+    }));
+    if (best && best.score >= threshold) add('keyword-overlap', phr[i].p.file, `"${best.a}" competes with ${phr[j].p.file} ("${best.b}"), ${Math.round(best.score * 100)}% overlap. Pick one page for this search.`);
+  }
+
+  // JSON-LD + NAP
+  pages.forEach((p) => {
+    p.jsonldErrors.forEach((e) => add('json-ld-syntax', p.file, `JSON-LD block #${e.index + 1} is invalid: ${e.message}`));
+    const digitsText = p.text.replace(/\D/g, '');
+    const ents = businessEntities(p.jsonldParsed);
+    ents.forEach((e) => {
+      const same = business && business.name && normName(e.name) === normName(business.name);
+      if (same) {
+        if (bizPhone && e.telephone && phoneDigits(e.telephone) !== bizPhone) add('nap-schema-mismatch', p.file, `Schema phone ${e.telephone} differs from your business phone ${business.phone}.`);
+        if (bizStreet && e.street && normAddress(e.street) !== bizStreet) add('nap-schema-mismatch', p.file, `Schema street "${e.street}" differs from "${business.street}".`);
+        if (bizZip && e.postalCode && String(e.postalCode).trim() !== bizZip) add('nap-schema-mismatch', p.file, `Schema ZIP ${e.postalCode} differs from ${bizZip}.`);
+      }
+      if (e.name && !normName(p.text).includes(normName(e.name))) add('schema-not-visible', p.file, `Schema names "${e.name}", but that name is not visible on the page.`);
+      if (e.telephone && phoneDigits(e.telephone).length >= 10 && !digitsText.includes(phoneDigits(e.telephone))) add('schema-not-visible', p.file, `Schema phone ${e.telephone} is not visible on the page.`);
+    });
+    if (bizPhone) {
+      const seen = new Set();
+      findPhones(p.text).forEach((ph) => { if (ph.digits !== bizPhone && !seen.has(ph.digits)) { seen.add(ph.digits); add('nap-phone-mismatch', p.file, `Shows ${ph.raw}; your business phone is ${business.phone}.`); } });
+    }
+    if (bizStreet && bizStreetNum) {
+      const t = p.text;
+      const re = new RegExp('\\b' + bizStreetNum + '\\s+[A-Za-z][^\\n]{0,40}', 'g');
+      let m; const seen = new Set();
+      while ((m = re.exec(t))) {
+        const cand = normAddress(m[0]);
+        const firstWord = bizStreet.split(' ')[1];
+        if (!firstWord || !cand.split(' ').slice(1, 3).includes(firstWord)) continue; // not our street
+        if (!cand.startsWith(bizStreet) && !seen.has(cand)) { seen.add(cand); add('nap-address-mismatch', p.file, `Address written as "${m[0].trim().slice(0, 45)}"; standard form is "${business.street}".`); }
+      }
+    }
+  });
+
+  // AI search readiness
+  const robotsFile = require('path').join(site.root, 'robots.txt');
+  if (fs.existsSync(robotsFile)) {
+    const txt = fs.readFileSync(robotsFile, 'utf8');
+    const blocked = AI_SEARCH_BOTS.filter((b) => robotsBlocksRoot(txt, b));
+    if (blocked.length) add('ai-crawler-blocked', 'robots.txt', `Blocks ${blocked.join(', ')}. Add "User-agent: ${blocked[0]}" with "Allow: /" if you want to appear in AI answers.`);
+  }
+  if (home && business && business.source !== 'config') {
+    const ents = businessEntities(home.jsonldParsed).filter((e) => normName(e.name) === normName(business.name));
+    if (ents.length && !ents.some((e) => e.sameAs.length)) add('ai-entity-links-missing', home.file, 'Add "sameAs" links to your Google Business Profile, Facebook, LinkedIn and Yelp pages in the business schema.');
+  }
+
+  const off = cfg.rules || {};
+  return {
+    business, siteOrigin,
+    findings: findings
+      .filter((f) => off[f.rule] !== 'off')
+      .map((f) => (off[f.rule] === 'warn' || off[f.rule] === 'error' ? Object.assign(f, { severity: off[f.rule] }) : f)),
+  };
+}
+
+module.exports = { run, RULES, robotsBlocksRoot, AI_SEARCH_BOTS };

package/src/html.js

@@ -0,0 +1,85 @@
+'use strict';
+// Minimal, dependency-free HTML helpers. Good enough for linting static sites;
+// not a full HTML5 parser.
+
+const ENT = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', ndash: '-', mdash: '-', middot: '·', rarr: '→', larr: '←', copy: '©' };
+
+function decode(s) {
+  return String(s)
+    .replace(/&#x([0-9a-f]+);/gi, (_, h) => String.fromCodePoint(parseInt(h, 16)))
+    .replace(/&#(\d+);/g, (_, d) => String.fromCodePoint(+d))
+    .replace(/&([a-z]+);/gi, (m, n) => (ENT[n.toLowerCase()] !== undefined ? ENT[n.toLowerCase()] : m));
+}
+
+function attrs(tag) {
+  const out = {};
+  const re = /([a-zA-Z_:][-a-zA-Z0-9_:.]*)\s*(?:=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+  const body = tag.replace(/^<\s*[a-zA-Z0-9-]+/, '').replace(/\/?>$/, '');
+  let m;
+  while ((m = re.exec(body))) {
+    const v = m[2] !== undefined ? m[2] : m[3] !== undefined ? m[3] : m[4] !== undefined ? m[4] : '';
+    out[m[1].toLowerCase()] = decode(v);
+  }
+  return out;
+}
+
+function tags(html, name) {
+  const re = new RegExp('<' + name + '\\b[^>]*>', 'gi');
+  return (html.match(re) || []).map(attrs);
+}
+
+function stripComments(html) {
+  return html.replace(/<!--[\s\S]*?-->/g, '');
+}
+
+function inner(html, name) {
+  const re = new RegExp('<' + name + '\\b[^>]*>([\\s\\S]*?)</' + name + '>', 'gi');
+  const out = [];
+  let m;
+  while ((m = re.exec(html))) out.push(m[1]);
+  return out;
+}
+
+function text(fragment) {
+  return decode(String(fragment).replace(/<[^>]+>/g, ' ')).replace(/\s+/g, ' ').trim();
+}
+
+function visibleText(html) {
+  const body = (html.match(/<body\b[^>]*>([\s\S]*)<\/body>/i) || [null, html])[1];
+  return text(
+    stripComments(body)
+      .replace(/<(script|style|noscript|template|svg)\b[\s\S]*?<\/\1>/gi, ' ')
+  );
+}
+
+function parse(html) {
+  html = stripComments(html);
+  const metas = tags(html, 'meta');
+  const meta = (key) => {
+    const t = metas.find((a) => (a.name || a.property || '').toLowerCase() === key);
+    return t ? (t.content || '').trim() : null;
+  };
+  const links = tags(html, 'link');
+  const jsonld = [];
+  const scriptRe = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
+  let m;
+  while ((m = scriptRe.exec(html))) {
+    const a = attrs('<script ' + m[1] + '>');
+    if ((a.type || '').toLowerCase() === 'application/ld+json') jsonld.push(m[2].trim());
+  }
+  const titles = inner(html, 'title').map(text);
+  const h1 = inner(html, 'h1').map(text);
+  return {
+    title: titles[0] || null,
+    titleCount: titles.length,
+    description: meta('description'),
+    robots: (meta('robots') || '').toLowerCase(),
+    canonicals: links.filter((l) => (l.rel || '').toLowerCase().split(/\s+/).includes('canonical')).map((l) => l.href || ''),
+    hrefs: tags(html, 'a').map((a) => a.href).filter((h) => h !== undefined),
+    h1,
+    jsonld,
+    text: visibleText(html),
+  };
+}
+
+module.exports = { parse, decode, text };

package/src/index.js

@@ -0,0 +1,23 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { loadSite } = require('./site');
+const { run, RULES } = require('./checks');
+
+function loadConfig(root, file) {
+  const candidates = file ? [file] : ['.localseorc.json', 'localseo.config.json'].map((f) => path.join(root, f));
+  for (const f of candidates) if (fs.existsSync(f)) return Object.assign({ _file: f }, JSON.parse(fs.readFileSync(f, 'utf8')));
+  return {};
+}
+
+function lint(root, options = {}) {
+  const cfg = Object.assign({}, loadConfig(root, options.config), options.overrides || {});
+  const ignore = [].concat(cfg.ignore || [], options.ignore || []);
+  const site = loadSite(root, { ignore, sitemap: cfg.sitemap });
+  const res = run(site, cfg);
+  const errors = res.findings.filter((f) => f.severity === 'error').length;
+  const warnings = res.findings.filter((f) => f.severity === 'warn').length;
+  return Object.assign(res, { pages: site.pages.length, errors, warnings, config: cfg._file || null });
+}
+
+module.exports = { lint, RULES };

package/src/nap.js

@@ -0,0 +1,66 @@
+'use strict';
+// Name / Address / Phone helpers.
+
+function phoneDigits(s) {
+  let d = String(s || '').replace(/\D/g, '');
+  if (d.length === 11 && d[0] === '1') d = d.slice(1);
+  return d;
+}
+
+// US/CA-style numbers: (661) 555-0123, 661-555-0123, +1 661 555 0123, 661.555.0123
+const PHONE_RE = /(?:\+?1[\s.-]?)?\(?\b[2-9]\d{2}\)?[\s.-]?\d{3}[\s.-]\d{4}\b/g;
+
+function findPhones(text) {
+  return (String(text).match(PHONE_RE) || []).map((raw) => ({ raw: raw.trim(), digits: phoneDigits(raw) }));
+}
+
+const ABBR = [
+  [/\bstreet\b/g, 'st'], [/\bavenue\b/g, 'ave'], [/\bav\b/g, 'ave'], [/\blane\b/g, 'ln'], [/\broad\b/g, 'rd'],
+  [/\bboulevard\b/g, 'blvd'], [/\bdrive\b/g, 'dr'], [/\bhighway\b/g, 'hwy'], [/\bparkway\b/g, 'pkwy'],
+  [/\bcourt\b/g, 'ct'], [/\bplace\b/g, 'pl'], [/\bcircle\b/g, 'cir'], [/\bsquare\b/g, 'sq'],
+  [/\bnorth\b/g, 'n'], [/\bsouth\b/g, 's'], [/\beast\b/g, 'e'], [/\bwest\b/g, 'w'],
+  [/\bsuite\b/g, 'ste'], [/\bunit\b/g, 'ste'], [/\bapartment\b/g, 'ste'], [/\bapt\b/g, 'ste'], [/#\s*/g, 'ste '], [/\bno\.?\s*(?=\d)/g, 'ste ']
+];
+
+function normAddress(s) {
+  let t = String(s || '').toLowerCase();
+  ABBR.forEach(([re, rep]) => { t = t.replace(re, rep); });
+  return t.replace(/[^a-z0-9 ]+/g, ' ').replace(/\s+/g, ' ').trim();
+}
+
+function normName(s) {
+  return String(s || '').toLowerCase().replace(/&/g, 'and').replace(/[^a-z0-9]+/g, ' ').replace(/\b(llc|inc|co|ltd|corp|the)\b/g, '').replace(/\s+/g, ' ').trim();
+}
+
+// Pull business-like entities out of parsed JSON-LD (handles arrays and @graph).
+function businessEntities(jsonldValues) {
+  const out = [];
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node)) return node.forEach(walk);
+    if (node['@graph']) walk(node['@graph']);
+    const addr = node.address;
+    const hasAddr = addr && (typeof addr === 'string' || typeof addr === 'object');
+    if (node.name && (hasAddr || node.telephone)) {
+      const a = Array.isArray(addr) ? addr[0] : addr;
+      out.push({
+        type: [].concat(node['@type'] || []).join(','),
+        name: node.name,
+        telephone: node.telephone || null,
+        street: a && typeof a === 'object' ? a.streetAddress || null : typeof a === 'string' ? a : null,
+        locality: a && typeof a === 'object' ? a.addressLocality || null : null,
+        region: a && typeof a === 'object' ? a.addressRegion || null : null,
+        postalCode: a && typeof a === 'object' ? a.postalCode || null : null,
+        openingHours: node.openingHoursSpecification || node.openingHours || null,
+        sameAs: [].concat(node.sameAs || []).filter((u) => typeof u === 'string' && /^https?:\/\//i.test(u)),
+      });
+    }
+    Object.keys(node).forEach((k) => { if (k !== '@graph' && typeof node[k] === 'object') walk(node[k]); });
+  };
+  jsonldValues.forEach(walk);
+  // de-duplicate identical entities found through nesting
+  const seen = new Set();
+  return out.filter((e) => { const k = JSON.stringify(e); if (seen.has(k)) return false; seen.add(k); return true; });
+}
+
+module.exports = { phoneDigits, findPhones, normAddress, normName, businessEntities };

package/src/report.js

@@ -0,0 +1,44 @@
+'use strict';
+const { RULES } = require('./checks');
+
+function color(enabled) {
+  const c = (n) => (s) => (enabled ? `\x1b[${n}m${s}\x1b[0m` : s);
+  return { red: c(31), yellow: c(33), green: c(32), dim: c(2), bold: c(1), cyan: c(36) };
+}
+
+function pretty(res, opts = {}) {
+  const k = color(opts.color !== false);
+  const out = [];
+  out.push(k.bold('local-seo-lint') + k.dim(`  ${res.pages} pages scanned`));
+  if (res.business) out.push(k.dim(`Business: ${res.business.name || '?'} | ${res.business.street || 'no street'} | ${res.business.phone || 'no phone'}  (from ${res.business.source})`));
+  else out.push(k.yellow('No business details found. Add LocalBusiness schema to your homepage or a "business" block to .localseorc.json to enable NAP checks.'));
+  out.push('');
+  const byRule = new Map();
+  res.findings.forEach((f) => byRule.set(f.rule, (byRule.get(f.rule) || []).concat(f)));
+  const order = [...byRule.keys()].sort((a, b) => (RULES[a].severity === RULES[b].severity ? a.localeCompare(b) : RULES[a].severity === 'error' ? -1 : 1));
+  const limit = opts.limit || 10;
+  order.forEach((rule) => {
+    const list = byRule.get(rule);
+    const sev = list[0].severity === 'error' ? k.red('error') : k.yellow('warn ');
+    out.push(`${sev} ${k.bold(rule)} ${k.dim('(' + list.length + ')')}  ${k.dim(RULES[rule].about)}`);
+    list.slice(0, limit).forEach((f) => out.push(`   ${k.cyan(f.file)}  ${f.message}`));
+    if (list.length > limit) out.push(k.dim(`   ...and ${list.length - limit} more (use --limit 0 to show all)`));
+    out.push('');
+  });
+  const summary = `${res.errors} error${res.errors === 1 ? '' : 's'}, ${res.warnings} warning${res.warnings === 1 ? '' : 's'}`;
+  out.push(res.errors ? k.red(summary) : res.warnings ? k.yellow(summary) : k.green('No problems found. ' + summary));
+  if (opts.footer !== false && (res.errors || res.warnings)) {
+    out.push('');
+    out.push(k.dim('Need these fixed? Clicks Dynasty fixes local SEO and AI-visibility issues, including white-label for agencies:'));
+    out.push(k.dim('https://www.clicksdynasty.com/book.html?service=ai-check  (hide this line with --no-footer)'));
+  }
+  return out.join('\n');
+}
+
+function github(res, prefix = '') {
+  const pre = prefix && prefix !== '.' ? prefix.replace(/\\/g, '/').replace(/\/$/, '') + '/' : '';
+  const esc = (s) => String(s).replace(/%/g, '%25').replace(/\r/g, '%0D').replace(/\n/g, '%0A');
+  return res.findings.map((f) => `::${f.severity === 'error' ? 'error' : 'warning'} file=${esc(pre + f.file)},title=${esc(f.rule)}::${esc(f.message)}`).join('\n');
+}
+
+module.exports = { pretty, github };

package/src/site.js

@@ -0,0 +1,80 @@
+'use strict';
+const fs = require('fs');
+const path = require('path');
+const { parse } = require('./html');
+
+const DEFAULT_IGNORE = ['node_modules/**', '.git/**', '**/node_modules/**'];
+
+function globToRe(g) {
+  g = String(g).replace(/^\.\//, '').replace(/\/$/, '');
+  let s = '';
+  for (let i = 0; i < g.length; i++) {
+    const c = g[i];
+    if (c === '*' && g[i + 1] === '*') { if (g[i + 2] === '/') { s += '(?:.*/)?'; i += 2; } else { s += '.*'; i += 1; } }
+    else if (c === '*') s += '[^/]*';
+    else if (c === '?') s += '[^/]';
+    else s += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  }
+  return new RegExp('^' + s + '(?:/.*)?$');
+}
+
+function walk(dir, root, ignoreRes, out) {
+  for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+    const abs = path.join(dir, ent.name);
+    const rel = path.relative(root, abs).split(path.sep).join('/');
+    if (ignoreRes.some((re) => re.test(rel))) continue;
+    if (ent.isDirectory()) walk(abs, root, ignoreRes, out);
+    else if (/\.html?$/i.test(ent.name)) out.push(rel);
+  }
+  return out;
+}
+
+function urlPathFor(rel) {
+  if (/(^|\/)index\.html?$/i.test(rel)) return '/' + rel.replace(/index\.html?$/i, '');
+  return '/' + rel;
+}
+
+function loadSite(root, opts = {}) {
+  const ignore = DEFAULT_IGNORE.concat(opts.ignore || []);
+  const files = walk(root, root, ignore.map(globToRe), []).sort();
+  const pages = files.map((rel) => {
+    const html = fs.readFileSync(path.join(root, rel), 'utf8');
+    const p = parse(html);
+    p.file = rel;
+    p.urlPath = urlPathFor(rel);
+    p.noindex = /\bnoindex\b/.test(p.robots);
+    p.jsonldParsed = [];
+    p.jsonldErrors = [];
+    p.jsonld.forEach((raw, i) => {
+      try { p.jsonldParsed.push(JSON.parse(raw)); } catch (e) { p.jsonldErrors.push({ index: i, message: e.message }); }
+    });
+    return p;
+  });
+  const byPath = new Map();
+  pages.forEach((p) => {
+    byPath.set(p.urlPath, p);
+    if (p.urlPath.endsWith('/') && p.urlPath !== '/') byPath.set(p.urlPath.slice(0, -1), p);
+  });
+  // Pages that are 301-redirected elsewhere (Apache .htaccess or Netlify/Cloudflare _redirects) are skipped.
+  const redirected = new Set();
+  const addRedirect = (from) => { const f = String(from).replace(/^\^?\/?/, '/').replace(/\$$/, '').replace(/\\\./g, '.'); if (!/[*()[\]|+?]/.test(f)) redirected.add(f.toLowerCase()); };
+  const ht = path.join(root, '.htaccess');
+  if (fs.existsSync(ht)) fs.readFileSync(ht, 'utf8').split(/\r?\n/).forEach((line) => {
+    const l = line.trim(); let m;
+    if ((m = l.match(/^Redirect(?:Permanent|\s+(?:301|permanent))?\s+(\S+)\s+\S+/i))) addRedirect(m[1]);
+    else if ((m = l.match(/^RewriteRule\s+(\S+)\s+\S+\s+\[[^\]]*R=30[18][^\]]*\]/i))) addRedirect(m[1]);
+  });
+  const rd = path.join(root, '_redirects');
+  if (fs.existsSync(rd)) fs.readFileSync(rd, 'utf8').split(/\r?\n/).forEach((line) => { const m = line.trim().match(/^(\/\S+)\s+\S+\s*(30[18])?/); if (m && !line.trim().startsWith('#')) addRedirect(m[1]); });
+  pages.forEach((p) => { p.redirected = redirected.has(p.urlPath.toLowerCase()); });
+
+  let sitemap = null;
+  const smPath = path.join(root, opts.sitemap || 'sitemap.xml');
+  if (fs.existsSync(smPath)) {
+    const xml = fs.readFileSync(smPath, 'utf8');
+    sitemap = { file: path.relative(root, smPath).split(path.sep).join('/'), urls: (xml.match(/<loc>\s*([^<]+?)\s*<\/loc>/gi) || []).map((l) => l.replace(/<\/?loc>/gi, '').trim()) };
+  }
+  return { root, pages, byPath, sitemap, redirected };
+}
+
+module.exports = { loadSite, globToRe };