npm - @qobi/seocode - Versions diffs - 0.1.0 - Mend

@qobi/seocode 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (42) hide show

package/LICENSE +21 -0
package/dist/src/billing/polar.js +127 -0
package/dist/src/billing/repo-limits.js +60 -0
package/dist/src/billing/subscription-service.js +123 -0
package/dist/src/billing/tier.js +14 -0
package/dist/src/billing/types.js +1 -0
package/dist/src/cli/discover.js +62 -0
package/dist/src/cli/fix.js +24 -0
package/dist/src/cli/format-terminal.js +66 -0
package/dist/src/cli/index.js +204 -0
package/dist/src/cli/init.js +48 -0
package/dist/src/cli/staged.js +24 -0
package/dist/src/config/seocode-config.js +97 -0
package/dist/src/engine/page-detector.js +82 -0
package/dist/src/engine/pr-delta.js +31 -0
package/dist/src/engine/rule-engine.js +112 -0
package/dist/src/engine/rule-loader.js +35 -0
package/dist/src/engine/rules/declarative-evaluator.js +105 -0
package/dist/src/engine/rules/heading-rules.js +43 -0
package/dist/src/engine/rules/helpers.js +16 -0
package/dist/src/engine/rules/image-rules.js +82 -0
package/dist/src/engine/rules/index.js +28 -0
package/dist/src/engine/rules/link-rules.js +39 -0
package/dist/src/engine/rules/meta-rules.js +34 -0
package/dist/src/engine/rules/performance-rules.js +24 -0
package/dist/src/engine/rules/schema-rules.js +228 -0
package/dist/src/engine/rules/suggest.js +103 -0
package/dist/src/engine/rules/technical-rules.js +100 -0
package/dist/src/parsers/frameworks/ast-value.js +83 -0
package/dist/src/parsers/frameworks/astro.js +107 -0
package/dist/src/parsers/frameworks/index.js +36 -0
package/dist/src/parsers/frameworks/nextjs.js +170 -0
package/dist/src/parsers/frameworks/remix.js +130 -0
package/dist/src/parsers/frameworks/roles.js +63 -0
package/dist/src/parsers/frameworks/types.js +1 -0
package/dist/src/parsers/html-parser.js +118 -0
package/dist/src/parsers/index.js +62 -0
package/dist/src/parsers/jsx-parser.js +174 -0
package/dist/src/types/index.js +1 -0
package/dist/src/types/worker-env.js +1 -0
package/package.json +75 -0
package/rules/seo-rules.json +3414 -0

package/dist/src/engine/rules/suggest.js ADDED Viewed

@@ -0,0 +1,103 @@
+/**
+ * Helpers that build **provably-correct** single-line fix suggestions from the
+ * document's raw source. The guiding rule: only ever return a suggestion when
+ * the transform is unambiguous on the exact source line. If anything about the
+ * line is unexpected (tag spans lines, attribute already present, token not
+ * found), return `undefined` so the issue stays advisory-only. A wrong 1-click
+ * fix is far worse than no button.
+ */
+/** Returns the 1-based `line` from the document's raw source, or undefined. */
+function sourceLine(doc, line) {
+    if (!line || line < 1)
+        return undefined;
+    const lines = doc.rawContent.split('\n');
+    return lines[line - 1];
+}
+/**
+ * Inserts `attr` (e.g. `loading="lazy"`) immediately after the opening `<tag`
+ * token on the issue line. Safe only when: the line contains exactly one such
+ * tag (unambiguous target), the tag opens and closes on that same line, and the
+ * attribute isn't already present. Otherwise returns undefined (advisory-only).
+ *
+ * `tag` is a bare tag name like `img` or `a`. A word boundary keeps `a` from
+ * matching `article`/`aside`.
+ */
+export function suggestTagAttr(doc, line, tag, attr, attrName) {
+    const src = sourceLine(doc, line);
+    if (src === undefined || line === null)
+        return undefined;
+    const openRe = new RegExp(`<${tag}\\b`, 'gi');
+    const matches = src.match(openRe);
+    if (!matches || matches.length !== 1)
+        return undefined; // 0 or >1 → ambiguous
+    const openIdx = src.search(new RegExp(`<${tag}\\b`, 'i'));
+    const closeIdx = src.indexOf('>', openIdx);
+    if (closeIdx === -1)
+        return undefined; // tag continues on a later line — unsafe
+    // Don't duplicate an attribute that's already there (within this tag).
+    const tagText = src.slice(openIdx, closeIdx + 1);
+    const attrRe = new RegExp(`\\b${attrName}\\s*=`, 'i');
+    if (attrRe.test(tagText))
+        return undefined;
+    const insertAt = openIdx + 1 + tag.length; // just after "<tag"
+    const replacement = src.slice(0, insertAt) + ' ' + attr + src.slice(insertAt);
+    return { startLine: line, endLine: line, replacement };
+}
+/** Convenience wrapper for the common `<img>` case. */
+export function suggestImgAttr(doc, line, attr, attrName) {
+    return suggestTagAttr(doc, line, 'img', attr, attrName);
+}
+/**
+ * Inserts a new line (e.g. `<meta charset="utf-8" />`) as the first child of
+ * `<head>`, by rewriting the `<head>` line to itself + the new line. Safe only
+ * for HTML documents where `<head>` sits alone on its own line exactly once —
+ * JSX/Vue/Svelte have no literal `<head>`, so this returns undefined for them.
+ * The new line inherits the `<head>` line's indentation plus two spaces.
+ */
+export function suggestHeadInsert(doc, newLine) {
+    if (doc.fileType !== 'html')
+        return undefined;
+    const lines = doc.rawContent.split('\n');
+    let headIdx = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (lines[i].trim().toLowerCase() === '<head>') {
+            if (headIdx !== -1)
+                return undefined; // more than one — ambiguous
+            headIdx = i;
+        }
+    }
+    if (headIdx === -1)
+        return undefined;
+    const headLine = lines[headIdx];
+    const indent = (headLine.match(/^\s*/)?.[0] ?? '') + '  ';
+    const replacement = headLine + '\n' + indent + newLine;
+    return { startLine: headIdx + 1, endLine: headIdx + 1, replacement };
+}
+/**
+ * Centralized post-analysis pass: attaches a provably-correct 1-click fix to
+ * issues that don't already carry one, keyed by rule id. Rules whose fix is a
+ * per-element line rewrite (image loading, link rel) attach their suggestion at
+ * detection time where they have the element line; this pass covers the
+ * insertion-style fixes for declarative, file-level rules (`line: null`), where
+ * the fix is a standard tag with a fixed, unambiguous value.
+ *
+ * Mutates and returns the same issues array. Only ever adds a suggestion when
+ * one is provably correct — otherwise the issue stays advisory-only.
+ */
+const HEAD_INSERTS = {
+    'missing-charset': '<meta charset="utf-8" />',
+    'missing-viewport': '<meta name="viewport" content="width=device-width, initial-scale=1" />',
+};
+export function attachSuggestions(doc, issues) {
+    for (const issue of issues) {
+        if (issue.suggestion)
+            continue;
+        const headTag = HEAD_INSERTS[issue.ruleId];
+        if (headTag) {
+            const s = suggestHeadInsert(doc, headTag);
+            if (s)
+                issue.suggestion = s;
+        }
+    }
+    return issues;
+}

package/dist/src/engine/rules/technical-rules.js ADDED Viewed

@@ -0,0 +1,100 @@
+import { buildIssue } from './helpers.js';
+const JS_FILE_TYPES = new Set(['jsx', 'tsx', 'vue', 'svelte']);
+/**
+ * Hand-coded handlers for technical rules that require compound conditions,
+ * iteration, or runtime context that can't be expressed as a single
+ * declarative check descriptor.
+ *
+ * Simple checks (missing-lang, missing-viewport, accidental-noindex, etc.)
+ * live as `check` descriptors in seo-rules.json.
+ */
+export function checkTechnicalRules(rule, doc) {
+    switch (rule.id) {
+        case 'noindex-in-javascript': {
+            if (!JS_FILE_TYPES.has(doc.fileType))
+                return null;
+            if (doc.hasNoindex)
+                return null; // already caught by accidental-noindex
+            const dynamicNoindex = /content\s*=\s*\{[^}]*noindex/.test(doc.rawContent) ||
+                /['"`]noindex,\s*nofollow['"`]/.test(doc.rawContent);
+            if (dynamicNoindex)
+                return buildIssue(rule, doc, null, rule.fixTemplate);
+            return null;
+        }
+        case 'robots-meta-outside-head': {
+            if (doc.fileType !== 'html')
+                return null;
+            const headEndIdx = doc.rawContent.toLowerCase().indexOf('</head>');
+            if (headEndIdx < 0)
+                return null;
+            const bodyContent = doc.rawContent.slice(headEndIdx);
+            if (/<meta[^>]+name\s*=\s*["']robots["'][^>]*>/i.test(bodyContent)) {
+                return buildIssue(rule, doc, null, rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'missing-hreflang': {
+            if (!doc.isPageDocument)
+                return null;
+            if (doc.hreflangLinks.length > 0)
+                return null;
+            if (doc.langAttribute && !/^en(-|$)/i.test(doc.langAttribute.value)) {
+                return buildIssue(rule, doc, doc.langAttribute.line, rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'hreflang-no-combined-attributes': {
+            const issues = [];
+            for (const link of doc.hreflangLinks) {
+                if (link.hasExtraAttrs) {
+                    issues.push(buildIssue(rule, doc, link.line, rule.fixTemplate
+                        .replace('{{LANG_CODE}}', link.lang)
+                        .replace('{{URL}}', link.href)));
+                }
+            }
+            return issues.length > 0 ? issues : null;
+        }
+        case 'url-parameters-best-practice': {
+            if (doc.ogUrl?.value.includes('?') && !doc.canonicalUrl) {
+                return buildIssue(rule, doc, doc.ogUrl.line, rule.fixTemplate);
+            }
+            return null;
+        }
+        case 'googlebot-file-size-limits': {
+            const sizeKB = doc.rawContent.length / 1024;
+            if (sizeKB > 500) {
+                return buildIssue(rule, doc, null, rule.fixTemplate + ` Current file size: ~${Math.round(sizeKB)}KB.`);
+            }
+            return null;
+        }
+        case 'javascript-paywall-detection': {
+            if (!JS_FILE_TYPES.has(doc.fileType))
+                return null;
+            const paywallClass = /(?:className|class)\s*=\s*["'][^"']*(?:paywall|subscription-wall|paywalled|locked-content|premium-content|members-only)[^"']*/i;
+            if (paywallClass.test(doc.rawContent)) {
+                const hasPaywallSchema = doc.jsonLdBlocks.some(b => b.content.includes('isAccessibleForFree'));
+                if (!hasPaywallSchema)
+                    return buildIssue(rule, doc, null, rule.fixTemplate);
+            }
+            return null;
+        }
+        // Cannot check from static file analysis alone
+        case 'mobile-version-links':
+        case 'explicit-content-video-crawlable':
+        case 'robots-txt-unsupported-fields':
+        case 'indexing-api-spam-detection':
+        case 'ai-mode-search-console':
+        case 'preferred-sources-feature':
+        case 'core-updates-continuous':
+        case 'spam-policies-apply-to-ai-responses':
+        case 'javascript-non-200-rendering':
+        case 'canonical-javascript-best-practice':
+        case 'safe-search-explicit-tagging':
+        case 'agent-friendly-website':
+        case 'favicon-aspect-ratio':
+        case 'sitemap-recommended':
+            return null;
+        default:
+            return null;
+    }
+}

package/dist/src/parsers/frameworks/ast-value.js ADDED Viewed

@@ -0,0 +1,83 @@
+import * as t from '@babel/types';
+/**
+ * Best-effort static evaluation of a Babel expression node into a plain JS
+ * value. Handles the literal shapes frameworks use for metadata objects:
+ * strings, template literals with no substitutions, numbers, booleans, null,
+ * arrays, and nested objects. Anything dynamic (variables, calls, spreads)
+ * evaluates to `undefined` — the caller treats that as "present but unknown",
+ * never as "missing", so dynamic metadata never produces a false positive.
+ */
+export function astToValue(node) {
+    if (!node)
+        return undefined;
+    if (t.isStringLiteral(node))
+        return node.value;
+    if (t.isNumericLiteral(node))
+        return node.value;
+    if (t.isBooleanLiteral(node))
+        return node.value;
+    if (t.isNullLiteral(node))
+        return null;
+    // `as const`, `satisfies`, parenthesised, TS assertions — unwrap
+    if (t.isTSAsExpression(node) || t.isTSSatisfiesExpression(node))
+        return astToValue(node.expression);
+    if (t.isTSNonNullExpression(node))
+        return astToValue(node.expression);
+    if (t.isParenthesizedExpression(node))
+        return astToValue(node.expression);
+    if (t.isTemplateLiteral(node)) {
+        // Only static templates (no ${...}) are resolvable
+        if (node.expressions.length === 0 && node.quasis.length === 1) {
+            return node.quasis[0].value.cooked ?? node.quasis[0].value.raw;
+        }
+        return undefined;
+    }
+    if (t.isArrayExpression(node)) {
+        return node.elements.map(el => (el ? astToValue(el) : undefined));
+    }
+    if (t.isObjectExpression(node)) {
+        const obj = {};
+        for (const prop of node.properties) {
+            if (!t.isObjectProperty(prop))
+                continue;
+            let key;
+            if (t.isIdentifier(prop.key) && !prop.computed)
+                key = prop.key.name;
+            else if (t.isStringLiteral(prop.key))
+                key = prop.key.value;
+            if (key === undefined)
+                continue;
+            obj[key] = astToValue(prop.value);
+        }
+        return obj;
+    }
+    return undefined;
+}
+/** Reads a nested path (e.g. "openGraph.images") returning undefined if any hop is missing. */
+export function getPath(value, path) {
+    return path.split('.').reduce((acc, key) => {
+        if (acc && typeof acc === 'object')
+            return acc[key];
+        return undefined;
+    }, value);
+}
+/**
+ * Coerces a metadata value into a display string when possible. Handles the
+ * common shapes: plain string; `{ url }` / `{ default }` / `{ absolute }`
+ * objects; and arrays (first element). Returns undefined for anything else.
+ */
+export function toStringish(value) {
+    if (typeof value === 'string')
+        return value;
+    if (Array.isArray(value))
+        return value.length ? toStringish(value[0]) : undefined;
+    if (value && typeof value === 'object') {
+        const o = value;
+        for (const k of ['url', 'default', 'absolute', 'content']) {
+            if (typeof o[k] === 'string')
+                return o[k];
+        }
+        // nested (e.g. { url: { … } }) — give up rather than guess
+    }
+    return undefined;
+}

package/dist/src/parsers/frameworks/astro.js ADDED Viewed

@@ -0,0 +1,107 @@
+import { LAYOUT_SHELL_SUPPRESS, PAGE_INHERITED_FROM_LAYOUT } from './roles.js';
+/**
+ * Astro adapter.
+ *
+ * Astro files are a `---` frontmatter fence (JS/TS) followed by an HTML-like
+ * template. Two patterns cause false positives for a static reader:
+ *
+ *  1. A base **layout** owns the document shell and sets `<title>{title}</title>`
+ *     / `<meta name="description" content={description} />` from props. A static
+ *     reader sees an expression, not text, and would wrongly flag the title/
+ *     description as missing or too short.
+ *  2. A **page** in `src/pages/` delegates its whole `<head>` to a layout
+ *     component (`<Layout title={…}>…</Layout>`) and has no head of its own — so
+ *     head/meta rules must not be demanded of the page file.
+ *
+ * The adapter maps Astro onto the shared layout/page roles and reconciles these.
+ */
+function splitFrontmatter(content) {
+    const m = /^\s*---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(content);
+    if (m)
+        return { frontmatter: m[1], template: m[2] };
+    return { frontmatter: '', template: content };
+}
+/** A `<title>` whose content is (or contains) a `{expr}` — dynamic, not static. */
+function hasDynamicTitle(template) {
+    const m = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(template);
+    return !!m && /\{[^}]+\}/.test(m[1]);
+}
+/** A `<meta name="description">` whose `content` is a `{expr}` binding. */
+function hasDynamicDescription(template) {
+    // content={expr} with name="description" in either attribute order.
+    return (/<meta\b[^>]*\bname=["']description["'][^>]*\bcontent=\{[^}]+\}/i.test(template) ||
+        /<meta\b[^>]*\bcontent=\{[^}]+\}[^>]*\bname=["']description["']/i.test(template));
+}
+/** Does the template hand its <head> to a wrapping layout component? */
+function delegatesToLayout(template) {
+    // A capitalised component whose name ends in/contains "Layout", or common
+    // base-shell names, used as an element: <Layout …>, <BaseLayout>, <MainLayout>.
+    return (/<[A-Z][A-Za-z0-9]*Layout\b/.test(template) ||
+        /<Layout\b/.test(template));
+}
+function inPagesDir(filePath) {
+    return /(^|\/)(src\/)?pages\//.test(filePath);
+}
+function isLayoutPath(filePath) {
+    return /(^|\/)layouts?\//.test(filePath);
+}
+const astroAdapter = {
+    name: 'astro',
+    detect(input) {
+        return input.fileType === 'astro' || /\.astro$/i.test(input.filePath);
+    },
+    apply(input, doc) {
+        const { template } = splitFrontmatter(input.content);
+        const suppressedRuleIds = new Set();
+        const suppressedCategories = new Set();
+        const rendersHtmlShell = /<html[\s>]/i.test(template) || /<head[\s>]/i.test(template);
+        // ── Layout / shell ──────────────────────────────────────────────────────────
+        if (rendersHtmlShell || isLayoutPath(input.filePath)) {
+            for (const id of LAYOUT_SHELL_SUPPRESS)
+                suppressedRuleIds.add(id);
+            // Dynamic head values are rendered by Astro — treat them as provided so we
+            // don't false-positive on missing/too-short/too-long.
+            if (hasDynamicTitle(template)) {
+                if (!doc.titleTag)
+                    doc.titleTag = { value: 'Astro dynamic title', line: 0 };
+                suppressedRuleIds.add('missing-title');
+                suppressedRuleIds.add('title-too-short');
+                suppressedRuleIds.add('title-too-long');
+            }
+            if (hasDynamicDescription(template)) {
+                if (!doc.metaDescription)
+                    doc.metaDescription = { value: 'Astro dynamic description', line: 0 };
+                suppressedRuleIds.add('missing-meta-description');
+                suppressedRuleIds.add('meta-description-too-short');
+                suppressedRuleIds.add('meta-description-too-long');
+            }
+            return {
+                name: 'astro',
+                role: 'layout',
+                suppressedRuleIds: [...suppressedRuleIds],
+                suppressedCategories: [...suppressedCategories],
+            };
+        }
+        // ── Page that delegates its <head> to a layout ──────────────────────────────
+        if (delegatesToLayout(template) || inPagesDir(input.filePath)) {
+            for (const id of PAGE_INHERITED_FROM_LAYOUT)
+                suppressedRuleIds.add(id);
+            // The head lives in the wrapping layout — don't demand meta tags here.
+            suppressedCategories.add('meta');
+            return {
+                name: 'astro',
+                role: 'page',
+                suppressedRuleIds: [...suppressedRuleIds],
+                suppressedCategories: [...suppressedCategories],
+            };
+        }
+        // ── A partial/component .astro (no shell, no layout wrapper) ─────────────────
+        return {
+            name: 'astro',
+            role: 'component',
+            suppressedRuleIds: [],
+            suppressedCategories: [],
+        };
+    },
+};
+export default astroAdapter;

package/dist/src/parsers/frameworks/index.js ADDED Viewed

@@ -0,0 +1,36 @@
+import nextjsAdapter from './nextjs.js';
+import remixAdapter from './remix.js';
+import astroAdapter from './astro.js';
+/**
+ * Registered framework adapters, in priority order. The first whose `detect`
+ * matches wins. To support a new framework, implement FrameworkAdapter and add
+ * it here — nothing else in the parser or engine needs to change.
+ */
+export const ADAPTERS = [nextjsAdapter, remixAdapter, astroAdapter];
+/**
+ * Runs the first matching adapter against a freshly-parsed document, enriching
+ * it in place and stamping `doc.framework`. No-op (leaves `doc.framework`
+ * null) when no adapter recognises the file.
+ */
+export function applyFrameworkAdapters(input, doc) {
+    for (const adapter of ADAPTERS) {
+        let matched = false;
+        try {
+            matched = adapter.detect(input);
+        }
+        catch {
+            matched = false;
+        }
+        if (!matched)
+            continue;
+        try {
+            doc.framework = adapter.apply(input, doc);
+        }
+        catch (err) {
+            console.warn(`[WARN] Framework adapter "${adapter.name}" failed on ${input.filePath}:`, err);
+            doc.framework = null;
+        }
+        return;
+    }
+    doc.framework = null;
+}

package/dist/src/parsers/frameworks/nextjs.js ADDED Viewed

@@ -0,0 +1,170 @@
+import * as t from '@babel/types';
+import { astToValue, getPath, toStringish } from './ast-value.js';
+import { LAYOUT_SHELL_SUPPRESS, HEAD_GOVERNED_ABSENCE_RULES } from './roles.js';
+// Next.js injects these into every rendered page, so their absence from source
+// is never a real issue.
+const FRAMEWORK_DEFAULTS = ['missing-charset', 'missing-viewport', 'missing-favicon'];
+const APP_ROUTER_FILES = new Set(['layout', 'page', 'template', 'default', 'error', 'loading', 'not-found', 'route']);
+function basename(filePath) {
+    const file = filePath.split('/').pop() ?? '';
+    return file.replace(/\.(t|j)sx?$/, '');
+}
+function programBody(ast) {
+    return ast?.program?.body ?? [];
+}
+/** Finds the initializer of `export const <name> = …`. */
+function findNamedExportInit(ast, name) {
+    for (const stmt of programBody(ast)) {
+        if (t.isExportNamedDeclaration(stmt) && stmt.declaration && t.isVariableDeclaration(stmt.declaration)) {
+            for (const decl of stmt.declaration.declarations) {
+                if (t.isIdentifier(decl.id) && decl.id.name === name && decl.init) {
+                    return { node: decl.init, line: decl.init.loc?.start.line ?? stmt.loc?.start.line ?? 0 };
+                }
+            }
+        }
+    }
+    return null;
+}
+/** True if the module exports a const or function of the given name. */
+function hasNamedExport(ast, name) {
+    for (const stmt of programBody(ast)) {
+        if (!t.isExportNamedDeclaration(stmt) || !stmt.declaration)
+            continue;
+        const d = stmt.declaration;
+        if (t.isFunctionDeclaration(d) && d.id?.name === name)
+            return true;
+        if (t.isVariableDeclaration(d)) {
+            for (const decl of d.declarations) {
+                if (t.isIdentifier(decl.id) && decl.id.name === name)
+                    return true;
+            }
+        }
+    }
+    return false;
+}
+function importsNext(ast) {
+    return programBody(ast).some(stmt => t.isImportDeclaration(stmt) && /^next(\/|$)/.test(stmt.source.value));
+}
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'];
+/**
+ * A Next.js App Router **route handler** (`app/**\/route.ts|tsx`) or an OG image
+ * route (`next/og` ImageResponse). These return a Response/Image — never an HTML
+ * page — so no page/content rule applies. Signals: the conventional `route`
+ * filename, or a module that exports HTTP-method handlers with no default page
+ * component.
+ */
+function isRouteHandler(ast, filePath) {
+    if (basename(filePath) === 'route')
+        return true;
+    const hasMethodExport = HTTP_METHODS.some(m => hasNamedExport(ast, m));
+    const hasDefault = programBody(ast).some(s => t.isExportDefaultDeclaration(s));
+    return hasMethodExport && !hasDefault;
+}
+const nextjsAdapter = {
+    name: 'nextjs',
+    detect(input) {
+        if (!input.ast)
+            return false;
+        const base = basename(input.filePath);
+        const inAppOrPages = /\/(app|pages)\//.test(input.filePath) || /(^|\/)(app|pages)\//.test(input.filePath);
+        if (importsNext(input.ast))
+            return true;
+        if (hasNamedExport(input.ast, 'metadata') || hasNamedExport(input.ast, 'generateMetadata') || hasNamedExport(input.ast, 'viewport'))
+            return true;
+        if (inAppOrPages && APP_ROUTER_FILES.has(base))
+            return true;
+        return false;
+    },
+    apply(input, doc) {
+        const ast = input.ast;
+        // Route handlers (incl. next/og image routes) emit no HTML page — the engine
+        // skips every rule for role 'route'. Short-circuit before any page/meta logic.
+        if (isRouteHandler(ast, input.filePath)) {
+            return { name: 'nextjs', role: 'route', suppressedRuleIds: [], suppressedCategories: [] };
+        }
+        const suppressedRuleIds = new Set(FRAMEWORK_DEFAULTS);
+        const suppressedCategories = new Set();
+        // ── Extract the Metadata API object ────────────────────────────────────────
+        const metaExport = findNamedExportInit(ast, 'metadata');
+        const hasGenerate = hasNamedExport(ast, 'generateMetadata');
+        let hasStaticTitle = false;
+        let hasStaticDescription = false;
+        if (metaExport) {
+            const line = metaExport.line;
+            const meta = astToValue(metaExport.node);
+            const set = (cur, path, assign) => {
+                const v = toStringish(getPath(cur, path));
+                if (typeof v === 'string' && v.length > 0)
+                    assign(v);
+            };
+            if (meta && typeof meta === 'object') {
+                set(meta, 'title', v => { doc.titleTag = { value: v, line }; hasStaticTitle = true; });
+                set(meta, 'description', v => { doc.metaDescription = { value: v, line }; hasStaticDescription = true; });
+                set(meta, 'openGraph.title', v => (doc.ogTitle = { value: v, line }));
+                set(meta, 'openGraph.description', v => (doc.ogDescription = { value: v, line }));
+                set(meta, 'openGraph.images', v => (doc.ogImage = { value: v, line }));
+                set(meta, 'openGraph.url', v => (doc.ogUrl = { value: v, line }));
+                set(meta, 'openGraph.type', v => (doc.ogType = { value: v, line }));
+                set(meta, 'openGraph.locale', v => (doc.ogLocale = { value: v, line }));
+                set(meta, 'twitter.card', v => (doc.twitterCard = { value: v, line }));
+                set(meta, 'twitter.title', v => (doc.twitterTitle = { value: v, line }));
+                set(meta, 'twitter.description', v => (doc.twitterDescription = { value: v, line }));
+                set(meta, 'twitter.images', v => (doc.twitterImage = { value: v, line }));
+                set(meta, 'alternates.canonical', v => (doc.canonicalUrl = { value: v, line }));
+                const robots = getPath(meta, 'robots');
+                const robotsStr = typeof robots === 'string' ? robots.toLowerCase() : '';
+                const robotsIndexFalse = robots && typeof robots === 'object' && robots.index === false;
+                if (robotsStr.includes('noindex') || robotsIndexFalse) {
+                    doc.hasNoindex = true;
+                    doc.metaRobots = { value: robotsStr || 'noindex', line };
+                }
+                if (getPath(meta, 'icons') !== undefined)
+                    doc.hasFavicon = true;
+            }
+        }
+        void hasStaticTitle;
+        void hasStaticDescription;
+        void hasGenerate;
+        // ── Determine the file's role ───────────────────────────────────────────────
+        const role = detectRole(input, doc);
+        // The framework's Metadata API owns the <head>, merged across root/nested
+        // layouts + page + generateMetadata + auto-fallbacks. Absence of any head
+        // element is therefore unprovable from one file — suppress that whole class
+        // on every page/layout. What still fires: positively-detected head problems
+        // (accidental-noindex from metadata.robots, literal invalid-json-ld) and all
+        // body-content rules (headings, images, links) reflecting the real DOM.
+        if (role === 'page' || role === 'layout') {
+            for (const id of HEAD_GOVERNED_ABSENCE_RULES)
+                suppressedRuleIds.add(id);
+        }
+        // A layout shell owns no page content — its heading outline lives in pages.
+        if (role === 'layout') {
+            for (const id of LAYOUT_SHELL_SUPPRESS)
+                suppressedRuleIds.add(id);
+        }
+        return {
+            name: 'nextjs',
+            role,
+            suppressedRuleIds: [...suppressedRuleIds],
+            suppressedCategories: [...suppressedCategories],
+        };
+    },
+};
+function detectRole(input, doc) {
+    const base = basename(input.filePath);
+    if (base === 'layout' || base === 'template')
+        return 'layout';
+    if (base === 'page')
+        return 'page';
+    // Structural fallbacks for non-conventional filenames.
+    const rendersHtmlShell = /<html[\s>]/i.test(input.content) || /<body[\s>]/i.test(input.content);
+    const rendersChildren = /\{\s*children\s*\}/.test(input.content);
+    if (rendersHtmlShell || rendersChildren)
+        return 'layout';
+    // A default-exported component with page-level content is a page.
+    const hasDefaultExport = programBody(input.ast).some(s => t.isExportDefaultDeclaration(s));
+    if (hasDefaultExport && (doc.headings.length > 0 || doc.images.length > 0 || doc.links.length > 0))
+        return 'page';
+    return 'component';
+}
+export default nextjsAdapter;