@nurkamol/seo-audit 1.31.0

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@nurkamol/seo-audit",
+  "version": "1.31.0",
+  "description": "Crawl a site's sitemap and check every page for SEO, metadata and structured-data problems that single-page graders miss. Zero dependencies.",
+  "type": "module",
+  "bin": {
+    "seo-audit": "bin/seo-audit.mjs"
+  },
+  "exports": {
+    ".": "./src/audit.mjs",
+    "./causes": "./src/causes.mjs",
+    "./report": "./src/report.mjs",
+    "./sitemap": "./src/sitemap.mjs",
+    "./areas": "./src/areas.mjs",
+    "./agents": "./src/agents.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "action.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "pretest": "node scripts/link-engine.mjs",
+    "test": "node --test test/*.test.mjs",
+    "audit": "node bin/seo-audit.mjs"
+  },
+  "keywords": [
+    "seo",
+    "audit",
+    "crawler",
+    "sitemap",
+    "metadata",
+    "open-graph",
+    "hreflang",
+    "cli"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nurkamol/seo-audit.git"
+  },
+  "homepage": "https://nurkamol.github.io/seo-audit/",
+  "bugs": {
+    "url": "https://github.com/nurkamol/seo-audit/issues"
+  }
+}

package/src/agents.mjs

@@ -0,0 +1,122 @@
+// Presenting as something other than this tool.
+//
+// Three reasons a real audit needs it, and none of them is dressing up:
+//
+//   - A site that answers a browser and blocks everything else is common, and
+//     the report from a blocked crawl is a report about the block.
+//   - Some sites serve different HTML to a crawler than to a person. Fetching
+//     as Googlebot is the only way to see what Google is given.
+//   - Google indexes what its smartphone crawler sees. On a site that serves a
+//     different page to phones, that is the page that matters.
+//
+// The strings below are a snapshot and will age; browser versions move every
+// few weeks and nothing here can know that. They are close enough for a server
+// deciding whether to answer, and `--user-agent` still takes a literal string
+// for anything that has to be exact.
+
+// Googlebot's two user agents, quoted from Google's own crawler documentation.
+// Google publishes the Chrome version as the placeholder `W.X.Y.Z`; the real
+// crawler sends a concrete one, so a plausible version is substituted here.
+const GOOGLEBOT_CHROME = '131.0.6778.264';
+
+const BOTS = {
+  googlebot:
+    `Mozilla/5.0 (Linux; Android 6.0.1; Nexus 5X Build/MMB29P) AppleWebKit/537.36 (KHTML, like Gecko) ` +
+    `Chrome/${GOOGLEBOT_CHROME} Mobile Safari/537.36 (compatible; Googlebot/2.1; +http://www.google.com/bot.html)`,
+  'googlebot-desktop':
+    `Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; Googlebot/2.1; ` +
+    `+http://www.google.com/bot.html) Chrome/${GOOGLEBOT_CHROME} Safari/537.36`,
+  bingbot: 'Mozilla/5.0 (compatible; bingbot/2.0; +http://www.bing.com/bingbot.htm)',
+};
+
+// What each system calls itself in a user agent. Chrome and Firefox both froze
+// these years ago — the macOS one says 10_15_7 on every Mac made since, and
+// that is correct rather than stale.
+const SYSTEM = {
+  macos: { chromium: 'Macintosh; Intel Mac OS X 10_15_7', gecko: 'Macintosh; Intel Mac OS X 10.15' },
+  windows: { chromium: 'Windows NT 10.0; Win64; x64', gecko: 'Windows NT 10.0; Win64; x64' },
+  linux: { chromium: 'X11; Linux x86_64', gecko: 'X11; Linux x86_64' },
+  android: { chromium: 'Linux; Android 10; K', gecko: 'Android 15; Mobile' },
+  ios: { chromium: 'iPhone; CPU iPhone OS 18_5 like Mac OS X', gecko: 'iPhone; CPU iPhone OS 18_5 like Mac OS X' },
+};
+
+const CHROME = '141.0.0.0';
+const FIREFOX = '143.0';
+const SAFARI = '18.6';
+const EDGE = '141.0.0.0';
+
+/** Every browser that can run on a system, and what it says when it does.
+ *
+ *  Absent combinations are absent on purpose: Safari does not run on Windows or
+ *  Linux, and inventing a user agent for one would be describing a machine that
+ *  does not exist. */
+const BROWSERS = {
+  chrome: {
+    macos: (s) => `Mozilla/5.0 (${s}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${CHROME} Safari/537.36`,
+    windows: null, // filled below — the string is identical bar the system
+    linux: null,
+    android: (s) => `Mozilla/5.0 (${s}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${CHROME} Mobile Safari/537.36`,
+    ios: (s) =>
+      `Mozilla/5.0 (${s}) AppleWebKit/605.1.15 (KHTML, like Gecko) CriOS/${CHROME} Mobile/15E148 Safari/604.1`,
+  },
+  firefox: {
+    macos: (s) => `Mozilla/5.0 (${s}; rv:${FIREFOX}) Gecko/20100101 Firefox/${FIREFOX}`,
+    windows: null,
+    linux: null,
+    android: (s) => `Mozilla/5.0 (${s}; rv:${FIREFOX}) Gecko/${FIREFOX} Firefox/${FIREFOX}`,
+    ios: (s) => `Mozilla/5.0 (${s}) AppleWebKit/605.1.15 (KHTML, like Gecko) FxiOS/${FIREFOX} Mobile/15E148 Safari/605.1.15`,
+  },
+  safari: {
+    macos: (s) => `Mozilla/5.0 (${s}) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/${SAFARI} Safari/605.1.15`,
+    ios: (s) => `Mozilla/5.0 (${s}) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/${SAFARI} Mobile/15E148 Safari/604.1`,
+  },
+  edge: {
+    macos: (s) =>
+      `Mozilla/5.0 (${s}) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/${CHROME} Safari/537.36 Edg/${EDGE}`,
+    windows: null,
+    linux: null,
+  },
+};
+for (const browser of ['chrome', 'firefox', 'edge']) {
+  for (const os of ['windows', 'linux']) {
+    if (BROWSERS[browser][os] === null) BROWSERS[browser][os] = BROWSERS[browser].macos;
+  }
+}
+
+export const BROWSER_NAMES = [...Object.keys(BROWSERS), ...Object.keys(BOTS)];
+export const OS_NAMES = Object.keys(SYSTEM);
+
+/** The system this is running on, so `--browser chrome` alone means "as a
+ *  browser on this machine" rather than making everyone name their own OS. */
+export function thisPlatform(platform = process.platform) {
+  return { darwin: 'macos', win32: 'windows' }[platform] ?? 'linux';
+}
+
+/** A user agent for a browser and a system, or an explanation of why not.
+ *
+ *  Returns `{ ua }` or `{ error }`. Never guesses: a combination that does not
+ *  exist in the world is refused rather than approximated, because the whole
+ *  point of the flag is to be believed by a server. */
+export function userAgentFor(browser, os = thisPlatform()) {
+  const name = String(browser ?? '').toLowerCase();
+  const system = String(os ?? '').toLowerCase();
+
+  if (BOTS[name]) {
+    // A crawler's user agent says nothing about a machine, so an --os alongside
+    // it is a question with no answer rather than a conflict worth refusing.
+    return { ua: BOTS[name], ignoredOs: Boolean(os) && os !== thisPlatform() };
+  }
+  if (!BROWSERS[name]) {
+    return { error: `Unknown browser "${browser}". Try one of: ${BROWSER_NAMES.join(', ')}.` };
+  }
+  if (!SYSTEM[system]) {
+    return { error: `Unknown system "${os}". Try one of: ${OS_NAMES.join(', ')}.` };
+  }
+  const build = BROWSERS[name][system];
+  if (!build) {
+    const runs = Object.keys(BROWSERS[name]).join(', ');
+    return { error: `${browser} does not run on ${os}. It runs on: ${runs}.` };
+  }
+  const engine = name === 'firefox' ? 'gecko' : 'chromium';
+  return { ua: build(SYSTEM[system][engine]) };
+}

package/src/areas.mjs

@@ -0,0 +1,135 @@
+// Which area of the site a check belongs to.
+//
+// Its own module because two things need it and neither can import the other:
+// `report.mjs` groups the HTML report by area, and `causes.mjs` puts the area
+// into the JSON payload so a native client can group its own report the same
+// way without carrying a second copy of this table in another language.
+
+// --- Categories -------------------------------------------------------------
+// Severity says how loudly to complain; a category says who fixes it. Thirty
+// findings sorted only by severity is a list you read once. The same thirty
+// under "Images" and "Multilingual" is a list somebody can divide up.
+//
+// Ordered by what a crawler hits first: whether the page can be indexed at all,
+// then what it says, then what it links to, then everything else.
+export const CATEGORIES = [
+  'Indexability',
+  'Content',
+  'Links',
+  'Redirects',
+  'Images',
+  'Social',
+  'Structured data',
+  'Multilingual',
+  'Sitemap & robots',
+  'Site & security',
+  'Performance',
+];
+
+const CATEGORY_OF = {
+  // Indexability
+  noindex: 'Indexability', 'x-robots-noindex': 'Indexability', 'nofollow-page': 'Indexability',
+  'page-status': 'Indexability', unreachable: 'Indexability', 'nothing-crawlable': 'Indexability',
+  'crawl-rate-limited': 'Indexability',
+  'rate-limited': 'Indexability',
+  'canonical-missing': 'Indexability', 'canonical-multiple': 'Indexability',
+  'canonical-other': 'Indexability', 'canonical-dead': 'Indexability',
+  'canonical-redirects': 'Indexability', 'soft-404': 'Indexability',
+  'canonical-chain': 'Indexability', 'robots-conflict': 'Indexability',
+  'canonical-noindex': 'Indexability', 'canonical-paginated': 'Indexability',
+
+  // Content
+  'title-missing': 'Content', 'title-long': 'Content', 'title-short': 'Content',
+  'desc-missing': 'Content', 'desc-long': 'Content', 'desc-short': 'Content',
+  'h1-missing': 'Content', 'h1-multiple': 'Content', 'heading-skip': 'Content',
+  'thin-content': 'Content', 'duplicate-title': 'Content', 'duplicate-description': 'Content',
+  'duplicate-content': 'Content', 'duplicate-content-not-checked': 'Content',
+  'lang-missing': 'Content', 'charset-missing': 'Content', 'viewport-missing': 'Content',
+  'viewport-locked': 'Content', 'viewport-fixed-width': 'Content',
+
+  // Links
+  'broken-link': 'Links', 'orphan-page': 'Links', 'no-editorial-links': 'Links',
+  'deep-page': 'Links', 'deep-page-more': 'Links', 'no-path-from-home': 'Links',
+  'click-depth-skipped': 'Links', 'orphan-check-skipped': 'Links', 'link-no-text': 'Links', 'link-no-text-more': 'Links',
+  'anchor-generic': 'Links', 'anchor-generic-more': 'Links',
+  'anchor-ambiguous': 'Links', 'anchor-ambiguous-more': 'Links',
+  'link-redirects': 'Links', 'link-sweep-capped': 'Links', 'internal-nofollow': 'Links',
+  'missing-from-sitemap': 'Links', 'missing-from-sitemap-more': 'Links',
+  'external-broken': 'Links', 'external-redirects': 'Links', 'external-sweep-capped': 'Links',
+
+  // Redirects
+  'sitemap-redirect': 'Redirects', 'redirect-chain': 'Redirects', 'host-variant-dead': 'Redirects',
+  'host-variant-not-checked': 'Redirects',
+  'origin-redirected': 'Redirects',
+  'serves-differently': 'Indexability', 'compare-sampled': 'Indexability',
+  'search-console': 'Site & security', 'search-console-unconfigured': 'Site & security',
+  'search-console-failed': 'Site & security',
+  'trailing-slash': 'Redirects', 'meta-refresh': 'Redirects',
+  'redirect-dead': 'Redirects', 'redirect-broken': 'Redirects',
+  'redirect-not-applied': 'Redirects', 'redirect-hops': 'Redirects',
+  'redirect-elsewhere': 'Redirects', 'redirect-temporary': 'Redirects',
+  'redirect-pattern-skipped': 'Redirects', 'redirect-map-capped': 'Redirects',
+
+  // Images
+  'img-alt': 'Images', 'img-alt-filename': 'Images', 'img-alt-placeholder': 'Images',
+  'img-alt-duplicate': 'Images', 'img-alt-long': 'Images', 'img-dimensions': 'Images',
+  'img-srcset': 'Images', 'broken-image': 'Images', 'image-sweep-capped': 'Images',
+  'img-title-duplicates-alt': 'Images', 'img-title-on-decorative': 'Images',
+  'img-lazy-priority': 'Images',
+
+  // Social
+  'og-missing': 'Social', 'og-webp': 'Social', 'og-no-dimensions': 'Social',
+  'og-image-relative': 'Social', 'og-image-broken': 'Social', 'og-image-heavy': 'Social',
+
+  // Structured data
+  'jsonld-invalid': 'Structured data', 'jsonld-no-type': 'Structured data',
+  'schema-expected': 'Structured data', 'schema-incomplete': 'Structured data',
+  'schema-date-order': 'Structured data', 'schema-date-future': 'Structured data',
+  'schema-image-broken': 'Structured data',
+
+  // Multilingual
+  'hreflang-one-way': 'Multilingual', 'hreflang-no-self': 'Multilingual',
+  'hreflang-lang-mismatch': 'Multilingual', 'hreflang-invalid': 'Multilingual',
+  'hreflang-no-x-default': 'Multilingual', 'hreflang-dead': 'Multilingual',
+  'content-language-mismatch': 'Multilingual',
+
+  // Sitemap & robots
+  'no-sitemap': 'Sitemap & robots', truncated: 'Sitemap & robots',
+  // What the run was told to leave out. Facts about the crawl rather than
+  // about the site, and they sit beside `truncated` for that reason.
+  since: 'Sitemap & robots', 'since-not-usable': 'Sitemap & robots',
+  excluded: 'Sitemap & robots',
+  'sitemap-not-checked': 'Sitemap & robots',
+  'rate-limit-slowed': 'Sitemap & robots',
+  'robots-missing': 'Sitemap & robots', 'robots-blocks-all': 'Sitemap & robots',
+  'robots-no-sitemap': 'Sitemap & robots', 'robots-blocks-sitemap-url': 'Sitemap & robots',
+  'sitemap-lastmod-missing': 'Sitemap & robots', 'sitemap-lastmod-identical': 'Sitemap & robots',
+  'sitemap-lastmod-future': 'Sitemap & robots', 'llms-missing': 'Sitemap & robots',
+  'sitemap-duplicate-url': 'Sitemap & robots',
+  'sitemap-not-indexable': 'Sitemap & robots', 'sitemap-too-many-urls': 'Sitemap & robots',
+  'sitemap-too-large': 'Sitemap & robots',
+
+  // Site & security
+  'favicon-broken': 'Site & security', 'favicon-missing': 'Site & security',
+  'mixed-content': 'Site & security', 'tls-not-checked': 'Site & security',
+  // The note the hosted Worker leaves where the certificate checks would
+  // have been. It belongs beside them, not in Other.
+  'tls-expiring': 'Site & security',
+  'tls-expired': 'Site & security', 'url-uppercase': 'Site & security',
+  'url-underscore': 'Site & security', 'url-space': 'Site & security',
+  'header-strict-transport-security': 'Site & security',
+  'header-x-content-type-options': 'Site & security',
+  'header-referrer-policy': 'Site & security',
+  'header-content-security-policy': 'Site & security',
+
+  // Performance
+  slow: 'Performance', uncompressed: 'Performance', 'huge-html': 'Performance', 'psi-score': 'Performance', 'psi-lcp': 'Performance',
+  'psi-cls': 'Performance', 'psi-inp': 'Performance', 'psi-opportunity': 'Performance',
+  'psi-failed': 'Performance', 'psi-no-field-data': 'Performance',
+  'psi-field-lcp': 'Performance', 'psi-field-cls': 'Performance', 'psi-field-inp': 'Performance',
+  'psi-sampled': 'Performance', 'psi-no-match': 'Performance',
+};
+
+/** The category a check belongs to. Unknown ids fall to "Other" rather than
+ *  disappearing — and a test asserts nothing in src/ ever lands there. */
+export const categoryOf = (id) => CATEGORY_OF[id] ?? 'Other';