@djangocfg/seo 2.1.50

package/dist/reports/index.mjs

@@ -0,0 +1,836 @@
+import { existsSync, readdirSync, rmSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import consola from 'consola';
+
+// src/reports/generator.ts
+
+// src/reports/json-report.ts
+function generateJsonReport(siteUrl, data, options = {}) {
+  const { issues, urlInspections = [], crawlResults = [] } = data;
+  const maxUrlsPerIssue = options.maxUrlsPerIssue ?? 10;
+  const limitedIssues = limitIssuesByTitle(issues, maxUrlsPerIssue);
+  const report = {
+    id: generateReportId(),
+    siteUrl,
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    summary: generateSummary(issues, urlInspections, crawlResults),
+    // Use original for accurate counts
+    issues: sortIssues(limitedIssues),
+    urlInspections: options.includeRawData ? urlInspections.slice(0, 100) : [],
+    crawlResults: options.includeRawData ? crawlResults.slice(0, 100) : [],
+    recommendations: generateRecommendations(issues, maxUrlsPerIssue)
+  };
+  return report;
+}
+function limitIssuesByTitle(issues, maxUrls) {
+  const byTitle = /* @__PURE__ */ new Map();
+  for (const issue of issues) {
+    const existing = byTitle.get(issue.title) || [];
+    existing.push(issue);
+    byTitle.set(issue.title, existing);
+  }
+  const limited = [];
+  for (const [, group] of byTitle) {
+    const sorted = group.sort((a, b) => {
+      const severityOrder = { critical: 0, error: 1, warning: 2, info: 3 };
+      return severityOrder[a.severity] - severityOrder[b.severity];
+    });
+    limited.push(...sorted.slice(0, maxUrls));
+  }
+  return limited;
+}
+function generateSummary(issues, urlInspections, crawlResults) {
+  const totalUrls = Math.max(
+    urlInspections.length,
+    crawlResults.length,
+    new Set(issues.map((i) => i.url)).size
+  );
+  const indexedUrls = urlInspections.filter(
+    (r) => r.indexStatusResult.coverageState === "SUBMITTED_AND_INDEXED"
+  ).length;
+  const notIndexedUrls = urlInspections.filter(
+    (r) => r.indexStatusResult.coverageState === "NOT_INDEXED" || r.indexStatusResult.coverageState === "CRAWLED_CURRENTLY_NOT_INDEXED" || r.indexStatusResult.coverageState === "DISCOVERED_CURRENTLY_NOT_INDEXED"
+  ).length;
+  const issuesByCategory = issues.reduce(
+    (acc, issue) => {
+      acc[issue.category] = (acc[issue.category] || 0) + 1;
+      return acc;
+    },
+    {}
+  );
+  const issuesBySeverity = issues.reduce(
+    (acc, issue) => {
+      acc[issue.severity] = (acc[issue.severity] || 0) + 1;
+      return acc;
+    },
+    {}
+  );
+  const healthScore = calculateHealthScore(issues, totalUrls);
+  return {
+    totalUrls,
+    indexedUrls,
+    notIndexedUrls,
+    issuesByCategory,
+    issuesBySeverity,
+    healthScore
+  };
+}
+function calculateHealthScore(issues, totalUrls) {
+  if (totalUrls === 0) return 100;
+  const severityWeights = {
+    critical: 10,
+    error: 5,
+    warning: 2,
+    info: 0.5
+  };
+  const totalPenalty = issues.reduce(
+    (sum, issue) => sum + severityWeights[issue.severity],
+    0
+  );
+  const maxPenalty = totalUrls * 20;
+  const penaltyRatio = Math.min(totalPenalty / maxPenalty, 1);
+  return Math.round((1 - penaltyRatio) * 100);
+}
+function generateRecommendations(issues, maxUrls = 10) {
+  const recommendations = [];
+  const issueGroups = /* @__PURE__ */ new Map();
+  for (const issue of issues) {
+    const key = `${issue.category}:${issue.title}`;
+    if (!issueGroups.has(key)) {
+      issueGroups.set(key, []);
+    }
+    issueGroups.get(key).push(issue);
+  }
+  for (const [, groupedIssues] of issueGroups) {
+    const firstIssue = groupedIssues[0];
+    if (!firstIssue) continue;
+    const severity = firstIssue.severity;
+    const priority = severity === "critical" ? 1 : severity === "error" ? 2 : severity === "warning" ? 3 : 4;
+    const impact = priority <= 2 ? "high" : priority === 3 ? "medium" : "low";
+    const allUrls = groupedIssues.map((i) => i.url);
+    const totalCount = allUrls.length;
+    const limitedUrls = allUrls.slice(0, maxUrls);
+    recommendations.push({
+      priority,
+      category: firstIssue.category,
+      title: firstIssue.title,
+      description: totalCount > maxUrls ? `${firstIssue.description} (showing ${maxUrls} of ${totalCount} URLs)` : firstIssue.description,
+      affectedUrls: limitedUrls,
+      estimatedImpact: impact,
+      actionItems: [firstIssue.recommendation]
+    });
+  }
+  return recommendations.sort((a, b) => a.priority - b.priority);
+}
+function sortIssues(issues) {
+  const severityOrder = {
+    critical: 0,
+    error: 1,
+    warning: 2,
+    info: 3
+  };
+  return [...issues].sort((a, b) => {
+    const severityDiff = severityOrder[a.severity] - severityOrder[b.severity];
+    if (severityDiff !== 0) return severityDiff;
+    return a.category.localeCompare(b.category);
+  });
+}
+function generateReportId() {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 8);
+  return `seo-report-${timestamp}-${random}`;
+}
+function exportJsonReport(report, pretty = true) {
+  return JSON.stringify(report, null, pretty ? 2 : 0);
+}
+var AI_REPORT_SCHEMA = {
+  $schema: "http://json-schema.org/draft-07/schema#",
+  title: "SEO Report",
+  description: "AI-friendly SEO analysis report with issues and recommendations",
+  type: "object",
+  properties: {
+    id: { type: "string", description: "Unique report identifier" },
+    siteUrl: { type: "string", description: "Analyzed site URL" },
+    generatedAt: { type: "string", format: "date-time" },
+    summary: {
+      type: "object",
+      description: "Quick overview of SEO health",
+      properties: {
+        totalUrls: { type: "number" },
+        indexedUrls: { type: "number" },
+        notIndexedUrls: { type: "number" },
+        healthScore: {
+          type: "number",
+          minimum: 0,
+          maximum: 100,
+          description: "0-100 score, higher is better"
+        }
+      }
+    },
+    issues: {
+      type: "array",
+      description: "List of detected SEO issues sorted by severity",
+      items: {
+        type: "object",
+        properties: {
+          severity: {
+            type: "string",
+            enum: ["critical", "error", "warning", "info"]
+          },
+          category: {
+            type: "string",
+            enum: [
+              "indexing",
+              "crawling",
+              "content",
+              "technical",
+              "mobile",
+              "performance",
+              "structured-data",
+              "security"
+            ]
+          },
+          title: { type: "string" },
+          description: { type: "string" },
+          recommendation: { type: "string" },
+          url: { type: "string" }
+        }
+      }
+    },
+    recommendations: {
+      type: "array",
+      description: "Prioritized action items",
+      items: {
+        type: "object",
+        properties: {
+          priority: { type: "number", minimum: 1, maximum: 5 },
+          title: { type: "string" },
+          affectedUrls: { type: "array", items: { type: "string" } },
+          actionItems: { type: "array", items: { type: "string" } }
+        }
+      }
+    }
+  }
+};
+
+// src/reports/markdown-report.ts
+function generateMarkdownReport(report, options = {}) {
+  const { includeRawIssues = true, includeUrls = true, maxUrlsPerIssue = 10 } = options;
+  const lines = [];
+  lines.push(`# SEO Analysis Report`);
+  lines.push("");
+  lines.push(`**Site:** ${report.siteUrl}`);
+  lines.push(`**Generated:** ${new Date(report.generatedAt).toLocaleString()}`);
+  lines.push(`**Report ID:** ${report.id}`);
+  lines.push("");
+  lines.push("## Summary");
+  lines.push("");
+  lines.push(`| Metric | Value |`);
+  lines.push(`|--------|-------|`);
+  lines.push(`| Health Score | ${getHealthScoreEmoji(report.summary.healthScore)} **${report.summary.healthScore}/100** |`);
+  lines.push(`| Total URLs | ${report.summary.totalUrls} |`);
+  lines.push(`| Indexed URLs | ${report.summary.indexedUrls} |`);
+  lines.push(`| Not Indexed | ${report.summary.notIndexedUrls} |`);
+  lines.push("");
+  lines.push("### Issues by Severity");
+  lines.push("");
+  const severities = ["critical", "error", "warning", "info"];
+  for (const severity of severities) {
+    const count = report.summary.issuesBySeverity[severity] || 0;
+    lines.push(`- ${getSeverityEmoji(severity)} **${capitalize(severity)}:** ${count}`);
+  }
+  lines.push("");
+  lines.push("### Issues by Category");
+  lines.push("");
+  const categories = Object.entries(report.summary.issuesByCategory).sort(
+    ([, a], [, b]) => b - a
+  );
+  for (const [category, count] of categories) {
+    lines.push(`- ${getCategoryEmoji(category)} **${formatCategory(category)}:** ${count}`);
+  }
+  lines.push("");
+  lines.push("## Prioritized Recommendations");
+  lines.push("");
+  for (const rec of report.recommendations) {
+    lines.push(`### ${getPriorityEmoji(rec.priority)} Priority ${rec.priority}: ${rec.title}`);
+    lines.push("");
+    lines.push(`**Category:** ${formatCategory(rec.category)}`);
+    lines.push(`**Impact:** ${capitalize(rec.estimatedImpact)}`);
+    lines.push(`**Affected URLs:** ${rec.affectedUrls.length}`);
+    lines.push("");
+    lines.push(`${rec.description}`);
+    lines.push("");
+    lines.push("**Action Items:**");
+    for (const action of rec.actionItems) {
+      lines.push(`- ${action}`);
+    }
+    lines.push("");
+    if (includeUrls && rec.affectedUrls.length > 0) {
+      const urlsToShow = rec.affectedUrls.slice(0, maxUrlsPerIssue);
+      lines.push("<details>");
+      lines.push(`<summary>Affected URLs (${rec.affectedUrls.length})</summary>`);
+      lines.push("");
+      for (const url of urlsToShow) {
+        lines.push(`- ${url}`);
+      }
+      if (rec.affectedUrls.length > maxUrlsPerIssue) {
+        lines.push(`- ... and ${rec.affectedUrls.length - maxUrlsPerIssue} more`);
+      }
+      lines.push("</details>");
+      lines.push("");
+    }
+    lines.push("---");
+    lines.push("");
+  }
+  if (includeRawIssues) {
+    lines.push("## All Issues");
+    lines.push("");
+    const issuesByCategory = groupBy(report.issues, "category");
+    for (const [category, issues] of Object.entries(issuesByCategory)) {
+      lines.push(`### ${getCategoryEmoji(category)} ${formatCategory(category)}`);
+      lines.push("");
+      for (const issue of issues) {
+        lines.push(
+          `#### ${getSeverityEmoji(issue.severity)} ${issue.title}`
+        );
+        lines.push("");
+        lines.push(`**URL:** \`${issue.url}\``);
+        lines.push(`**Severity:** ${capitalize(issue.severity)}`);
+        lines.push("");
+        lines.push(issue.description);
+        lines.push("");
+        lines.push(`**Recommendation:** ${issue.recommendation}`);
+        lines.push("");
+      }
+    }
+  }
+  lines.push("---");
+  lines.push("");
+  lines.push("*Report generated by [@djangocfg/seo](https://djangocfg.com)*");
+  lines.push("");
+  lines.push("> This report is designed to be processed by AI assistants for automated SEO improvements.");
+  return lines.join("\n");
+}
+function generateAiSummary(report) {
+  const lines = [];
+  lines.push("# SEO Report Summary for AI Processing");
+  lines.push("");
+  lines.push("## Context");
+  lines.push(`Site: ${report.siteUrl}`);
+  lines.push(`Health Score: ${report.summary.healthScore}/100`);
+  lines.push(`Critical Issues: ${report.summary.issuesBySeverity.critical || 0}`);
+  lines.push(`Errors: ${report.summary.issuesBySeverity.error || 0}`);
+  lines.push(`Warnings: ${report.summary.issuesBySeverity.warning || 0}`);
+  lines.push("");
+  lines.push("## Top Priority Actions");
+  lines.push("");
+  const topRecommendations = report.recommendations.slice(0, 5);
+  for (let i = 0; i < topRecommendations.length; i++) {
+    const rec = topRecommendations[i];
+    if (!rec) continue;
+    lines.push(`${i + 1}. **${rec.title}** (${rec.affectedUrls.length} URLs)`);
+    lines.push(`   - ${rec.actionItems[0]}`);
+  }
+  lines.push("");
+  lines.push("## Issue Categories");
+  lines.push("");
+  const sortedCategories = Object.entries(report.summary.issuesByCategory).sort(([, a], [, b]) => b - a);
+  for (const [category, count] of sortedCategories) {
+    lines.push(`- ${formatCategory(category)}: ${count} issues`);
+  }
+  return lines.join("\n");
+}
+function getSeverityEmoji(severity) {
+  const emojis = {
+    critical: "\u{1F534}",
+    error: "\u{1F7E0}",
+    warning: "\u{1F7E1}",
+    info: "\u{1F535}"
+  };
+  return emojis[severity];
+}
+function getCategoryEmoji(category) {
+  const emojis = {
+    indexing: "\u{1F4D1}",
+    crawling: "\u{1F577}\uFE0F",
+    content: "\u{1F4DD}",
+    technical: "\u2699\uFE0F",
+    mobile: "\u{1F4F1}",
+    performance: "\u26A1",
+    "structured-data": "\u{1F3F7}\uFE0F",
+    security: "\u{1F512}"
+  };
+  return emojis[category] || "\u{1F4CB}";
+}
+function getPriorityEmoji(priority) {
+  const emojis = {
+    1: "\u{1F6A8}",
+    2: "\u26A0\uFE0F",
+    3: "\u{1F4CC}",
+    4: "\u{1F4A1}",
+    5: "\u2139\uFE0F"
+  };
+  return emojis[priority] || "\u{1F4CB}";
+}
+function getHealthScoreEmoji(score) {
+  if (score >= 90) return "\u{1F7E2}";
+  if (score >= 70) return "\u{1F7E1}";
+  if (score >= 50) return "\u{1F7E0}";
+  return "\u{1F534}";
+}
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+function formatCategory(category) {
+  return category.split("-").map(capitalize).join(" ");
+}
+function groupBy(array, key) {
+  return array.reduce(
+    (acc, item) => {
+      const groupKey = String(item[key]);
+      if (!acc[groupKey]) {
+        acc[groupKey] = [];
+      }
+      acc[groupKey].push(item);
+      return acc;
+    },
+    {}
+  );
+}
+var MAX_LINES = 1e3;
+function generateSplitReports(report, options) {
+  const { outputDir, clearOutputDir = true } = options;
+  if (clearOutputDir && existsSync(outputDir)) {
+    const files = readdirSync(outputDir);
+    for (const file of files) {
+      if (file.startsWith("seo-") && file.endsWith(".md")) {
+        rmSync(join(outputDir, file), { force: true });
+      }
+    }
+  }
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+  const siteName = new URL(report.siteUrl).hostname.replace(/\./g, "-");
+  const prefix = `seo-${siteName}-${timestamp}`;
+  const categoryFiles = [];
+  const issuesByCategory = groupIssuesByCategory(report.issues);
+  const categories = Object.keys(issuesByCategory);
+  for (const category of categories) {
+    const issues = issuesByCategory[category] || [];
+    if (issues.length === 0) continue;
+    const chunks = splitIntoChunks(issues);
+    for (let i = 0; i < chunks.length; i++) {
+      const suffix = chunks.length > 1 ? `-${i + 1}` : "";
+      const filename = `${prefix}-${category}${suffix}.md`;
+      const filepath = join(outputDir, filename);
+      const chunk = chunks[i];
+      if (!chunk) continue;
+      const content = generateCategoryFile(report.siteUrl, category, chunk, {
+        part: chunks.length > 1 ? i + 1 : void 0,
+        totalParts: chunks.length > 1 ? chunks.length : void 0
+      });
+      writeFileSync(filepath, content, "utf-8");
+      categoryFiles.push(filename);
+    }
+  }
+  const indexFilename = `${prefix}-index.md`;
+  const indexFilepath = join(outputDir, indexFilename);
+  const indexContent = generateIndexFile(report, categoryFiles);
+  writeFileSync(indexFilepath, indexContent, "utf-8");
+  return {
+    indexFile: indexFilename,
+    categoryFiles,
+    totalFiles: categoryFiles.length + 1
+  };
+}
+function generateIndexFile(report, categoryFiles) {
+  const lines = [];
+  lines.push("# SEO Report Index");
+  lines.push("");
+  lines.push(`Site: ${report.siteUrl}`);
+  lines.push(`Score: ${report.summary.healthScore}/100`);
+  lines.push(`Date: ${report.generatedAt.slice(0, 10)}`);
+  lines.push("");
+  lines.push("## Issues");
+  lines.push("");
+  lines.push("| Severity | Count |");
+  lines.push("|----------|-------|");
+  const severities = ["critical", "error", "warning", "info"];
+  for (const sev of severities) {
+    const count = report.summary.issuesBySeverity[sev] || 0;
+    if (count > 0) {
+      lines.push(`| ${sev} | ${count} |`);
+    }
+  }
+  lines.push("");
+  lines.push("## Actions");
+  lines.push("");
+  const topRecs = report.recommendations.slice(0, 10);
+  for (let i = 0; i < topRecs.length; i++) {
+    const rec = topRecs[i];
+    if (!rec) continue;
+    lines.push(`${i + 1}. **${rec.title}** (${rec.affectedUrls.length})`);
+    lines.push(`   ${rec.actionItems[0]}`);
+  }
+  lines.push("");
+  lines.push("## Files");
+  lines.push("");
+  for (const file of categoryFiles) {
+    lines.push(`- [${file}](./${file})`);
+  }
+  return lines.join("\n");
+}
+function generateCategoryFile(siteUrl, category, issues, opts) {
+  const lines = [];
+  const partStr = opts.part ? ` (Part ${opts.part}/${opts.totalParts})` : "";
+  lines.push(`# ${formatCategory2(category)}${partStr}`);
+  lines.push("");
+  lines.push(`Site: ${siteUrl}`);
+  lines.push(`Issues: ${issues.length}`);
+  lines.push("");
+  const byTitle = /* @__PURE__ */ new Map();
+  for (const issue of issues) {
+    const group = byTitle.get(issue.title) || [];
+    group.push(issue);
+    byTitle.set(issue.title, group);
+  }
+  for (const [title, groupIssues] of byTitle) {
+    const first = groupIssues[0];
+    if (!first) continue;
+    lines.push(`## ${title}`);
+    lines.push("");
+    lines.push(`Severity: ${first.severity}`);
+    lines.push(`Count: ${groupIssues.length}`);
+    lines.push("");
+    lines.push(`> ${first.recommendation}`);
+    lines.push("");
+    lines.push("URLs:");
+    for (const issue of groupIssues.slice(0, 20)) {
+      lines.push(`- ${issue.url}`);
+    }
+    if (groupIssues.length > 20) {
+      lines.push(`- ... +${groupIssues.length - 20} more`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+function splitIntoChunks(issues, category) {
+  const byTitle = /* @__PURE__ */ new Map();
+  for (const issue of issues) {
+    const group = byTitle.get(issue.title) || [];
+    group.push(issue);
+    byTitle.set(issue.title, group);
+  }
+  const chunks = [];
+  let currentChunk = [];
+  let currentLines = 10;
+  for (const [, groupIssues] of byTitle) {
+    const urlCount = Math.min(20, groupIssues.length);
+    const groupLines = 8 + urlCount;
+    if (currentLines + groupLines > MAX_LINES && currentChunk.length > 0) {
+      chunks.push(currentChunk);
+      currentChunk = [];
+      currentLines = 10;
+    }
+    currentChunk.push(...groupIssues);
+    currentLines += groupLines;
+  }
+  if (currentChunk.length > 0) {
+    chunks.push(currentChunk);
+  }
+  return chunks.length > 0 ? chunks : [[]];
+}
+function groupIssuesByCategory(issues) {
+  const result = {};
+  for (const issue of issues) {
+    if (!result[issue.category]) {
+      result[issue.category] = [];
+    }
+    result[issue.category].push(issue);
+  }
+  return result;
+}
+function formatCategory2(category) {
+  return category.split("-").map((s) => s.charAt(0).toUpperCase() + s.slice(1)).join(" ");
+}
+
+// src/reports/claude-context.ts
+function generateClaudeContext(report) {
+  const lines = [];
+  lines.push("# @djangocfg/seo");
+  lines.push("");
+  lines.push("SEO audit toolkit. Generates AI-optimized split reports (max 1000 lines each).");
+  lines.push("");
+  lines.push("## Commands");
+  lines.push("");
+  lines.push("```bash");
+  lines.push("# Audit (HTTP-based, crawls live site)");
+  lines.push("pnpm seo:audit                    # Full audit (split reports)");
+  lines.push("pnpm seo:audit --env dev          # Audit local dev");
+  lines.push("pnpm seo:audit --format all       # All formats");
+  lines.push("");
+  lines.push("# Content (file-based, scans MDX/content/)");
+  lines.push("pnpm exec djangocfg-seo content check    # Check MDX links");
+  lines.push("pnpm exec djangocfg-seo content fix      # Show fixable links");
+  lines.push("pnpm exec djangocfg-seo content fix --fix # Apply fixes");
+  lines.push("pnpm exec djangocfg-seo content sitemap  # Generate sitemap.ts");
+  lines.push("```");
+  lines.push("");
+  lines.push("## Options");
+  lines.push("");
+  lines.push("- `--env, -e` - prod (default) or dev");
+  lines.push("- `--site, -s` - Site URL (overrides env)");
+  lines.push("- `--output, -o` - Output directory");
+  lines.push("- `--format, -f` - split (default), json, markdown, ai-summary, all");
+  lines.push("- `--max-pages` - Max pages (default: 100)");
+  lines.push("- `--service-account` - Google service account JSON path");
+  lines.push("- `--content-dir` - Content directory (default: content/)");
+  lines.push("- `--base-path` - Base URL path for docs (default: /docs)");
+  lines.push("");
+  lines.push("## Reports");
+  lines.push("");
+  lines.push("- `seo-*-index.md` - Summary + links to categories");
+  lines.push("- `seo-*-technical.md` - Broken links, sitemap issues");
+  lines.push("- `seo-*-content.md` - H1, meta, title issues");
+  lines.push("- `seo-*-performance.md` - Load time, TTFB issues");
+  lines.push("- `seo-ai-summary-*.md` - Quick overview");
+  lines.push("");
+  lines.push("## Issue Severity");
+  lines.push("");
+  lines.push("- **critical** - Blocks indexing (fix immediately)");
+  lines.push("- **error** - SEO problems (high priority)");
+  lines.push("- **warning** - Recommendations (medium priority)");
+  lines.push("- **info** - Best practices (low priority)");
+  lines.push("");
+  lines.push("## Issue Categories");
+  lines.push("");
+  lines.push("- **technical** - Broken links, sitemap, robots.txt");
+  lines.push("- **content** - Missing H1, meta description, title");
+  lines.push("- **indexing** - Not indexed, crawl errors from GSC");
+  lines.push("- **performance** - Slow load time (>3s), high TTFB (>800ms)");
+  lines.push("");
+  lines.push("## Routes Scanner");
+  lines.push("");
+  lines.push("Scans Next.js App Router `app/` directory. Handles:");
+  lines.push("- Route groups `(group)` - ignored in URL");
+  lines.push("- Dynamic `[slug]` - shown as `:slug`");
+  lines.push("- Catch-all `[...slug]` - shown as `:...slug`");
+  lines.push("- Parallel `@folder` - skipped");
+  lines.push("- Private `_folder` - skipped");
+  lines.push("");
+  lines.push("## Link Guidelines");
+  lines.push("");
+  lines.push("### Nextra/MDX Projects (content/)");
+  lines.push("");
+  lines.push("For non-index files (e.g., `overview.mdx`):");
+  lines.push("- **Sibling file**: `../sibling` (one level up)");
+  lines.push("- **Other section**: `/docs/full/path` (absolute)");
+  lines.push("- **AVOID**: `./sibling` (browser adds filename to path!)");
+  lines.push("- **AVOID**: `../../deep/path` (hard to maintain)");
+  lines.push("");
+  lines.push("For index files (e.g., `index.mdx`):");
+  lines.push("- **Child file**: `./child` works correctly");
+  lines.push("- **Sibling folder**: `../sibling/` or absolute");
+  lines.push("");
+  lines.push("### Next.js App Router Projects");
+  lines.push("");
+  lines.push("Use declarative routes from `_routes/`:");
+  lines.push("```typescript");
+  lines.push('import { routes } from "@/app/_routes";');
+  lines.push("<Link href={routes.dashboard.machines}>Machines</Link>");
+  lines.push("```");
+  lines.push("");
+  lines.push("Benefits: type-safe, refactor-friendly, centralized.");
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push("## Current Audit");
+  lines.push("");
+  lines.push(`Site: ${report.siteUrl}`);
+  lines.push(`Score: ${report.summary.healthScore}/100`);
+  lines.push(`Date: ${report.generatedAt.slice(0, 10)}`);
+  lines.push("");
+  lines.push("### Issues");
+  lines.push("");
+  const { critical = 0, error = 0, warning = 0, info = 0 } = report.summary.issuesBySeverity;
+  if (critical > 0) lines.push(`- Critical: ${critical}`);
+  if (error > 0) lines.push(`- Error: ${error}`);
+  if (warning > 0) lines.push(`- Warning: ${warning}`);
+  if (info > 0) lines.push(`- Info: ${info}`);
+  lines.push("");
+  lines.push("### Top Actions");
+  lines.push("");
+  const topRecs = report.recommendations.slice(0, 5);
+  for (let i = 0; i < topRecs.length; i++) {
+    const rec = topRecs[i];
+    if (!rec) continue;
+    lines.push(`${i + 1}. **${rec.title}** (${rec.affectedUrls.length} URLs)`);
+  }
+  lines.push("");
+  lines.push("### Report Files");
+  lines.push("");
+  lines.push("See split reports in this directory:");
+  lines.push("- `seo-*-index.md` - Start here");
+  lines.push("- `seo-*-technical.md` - Technical issues");
+  lines.push("- `seo-*-content.md` - Content issues");
+  lines.push("- `seo-*-performance.md` - Performance issues");
+  lines.push("");
+  return lines.join("\n");
+}
+
+// src/reports/generator.ts
+async function generateAndSaveReports(siteUrl, data, options) {
+  const {
+    outputDir,
+    formats,
+    includeRawData = false,
+    timestamp = true,
+    clearOutputDir = true,
+    maxUrlsPerIssue = 10
+  } = options;
+  if (clearOutputDir && existsSync(outputDir)) {
+    try {
+      const files = readdirSync(outputDir);
+      for (const file of files) {
+        if (file.startsWith("seo-")) {
+          rmSync(join(outputDir, file), { force: true });
+        }
+      }
+    } catch {
+    }
+  }
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+  const report = generateJsonReport(siteUrl, data, { includeRawData, maxUrlsPerIssue });
+  const result = {
+    report,
+    files: {}
+  };
+  const ts = timestamp ? `-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)}` : "";
+  const siteName = new URL(siteUrl).hostname.replace(/\./g, "-");
+  if (formats.includes("json")) {
+    const filename = `seo-report-${siteName}${ts}.json`;
+    const filepath = join(outputDir, filename);
+    const content = exportJsonReport(report, true);
+    writeFileSync(filepath, content, "utf-8");
+    result.files.json = filepath;
+    consola.success(`JSON report saved: ${filepath}`);
+  }
+  if (formats.includes("markdown")) {
+    const filename = `seo-report-${siteName}${ts}.md`;
+    const filepath = join(outputDir, filename);
+    const content = generateMarkdownReport(report, {
+      includeRawIssues: true,
+      includeUrls: true
+    });
+    writeFileSync(filepath, content, "utf-8");
+    result.files.markdown = filepath;
+    consola.success(`Markdown report saved: ${filepath}`);
+  }
+  if (formats.includes("ai-summary")) {
+    const filename = `seo-ai-summary-${siteName}${ts}.md`;
+    const filepath = join(outputDir, filename);
+    const content = generateAiSummary(report);
+    writeFileSync(filepath, content, "utf-8");
+    result.files.aiSummary = filepath;
+    consola.success(`AI summary saved: ${filepath}`);
+  }
+  if (formats.includes("split")) {
+    const splitResult = generateSplitReports(report, {
+      outputDir,
+      clearOutputDir: false
+      // Already cleared above
+    });
+    result.files.split = {
+      index: join(outputDir, splitResult.indexFile),
+      categories: splitResult.categoryFiles.map((f) => join(outputDir, f))
+    };
+    consola.success(`Split reports saved: ${splitResult.totalFiles} files (index + ${splitResult.categoryFiles.length} categories)`);
+  }
+  const claudeContent = generateClaudeContext(report);
+  const claudeFilepath = join(outputDir, "CLAUDE.md");
+  writeFileSync(claudeFilepath, claudeContent, "utf-8");
+  consola.success(`AI context saved: ${claudeFilepath}`);
+  return result;
+}
+function printReportSummary(report) {
+  consola.box(
+    `SEO Report: ${report.siteUrl}
+Health Score: ${report.summary.healthScore}/100
+Total URLs: ${report.summary.totalUrls}
+Indexed: ${report.summary.indexedUrls} | Not Indexed: ${report.summary.notIndexedUrls}
+Issues: ${report.issues.length}`
+  );
+  if (report.summary.issuesBySeverity.critical) {
+    consola.error(`Critical issues: ${report.summary.issuesBySeverity.critical}`);
+  }
+  if (report.summary.issuesBySeverity.error) {
+    consola.warn(`Errors: ${report.summary.issuesBySeverity.error}`);
+  }
+  if (report.summary.issuesBySeverity.warning) {
+    consola.info(`Warnings: ${report.summary.issuesBySeverity.warning}`);
+  }
+  consola.log("");
+  consola.info("Top recommendations:");
+  for (const rec of report.recommendations.slice(0, 3)) {
+    consola.log(`  ${rec.priority}. ${rec.title} (${rec.affectedUrls.length} URLs)`);
+  }
+}
+function mergeReports(reports) {
+  if (reports.length === 0) {
+    throw new Error("Cannot merge empty reports array");
+  }
+  const merged = {
+    id: `merged-${Date.now().toString(36)}`,
+    siteUrl: reports.map((r) => r.siteUrl).join(", "),
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    summary: {
+      totalUrls: reports.reduce((sum, r) => sum + r.summary.totalUrls, 0),
+      indexedUrls: reports.reduce((sum, r) => sum + r.summary.indexedUrls, 0),
+      notIndexedUrls: reports.reduce((sum, r) => sum + r.summary.notIndexedUrls, 0),
+      issuesByCategory: {},
+      issuesBySeverity: {},
+      healthScore: Math.round(
+        reports.reduce((sum, r) => sum + r.summary.healthScore, 0) / reports.length
+      )
+    },
+    issues: reports.flatMap((r) => r.issues),
+    urlInspections: reports.flatMap((r) => r.urlInspections),
+    crawlResults: reports.flatMap((r) => r.crawlResults),
+    recommendations: []
+  };
+  for (const report of reports) {
+    for (const [category, count] of Object.entries(report.summary.issuesByCategory)) {
+      const cat = category;
+      merged.summary.issuesByCategory[cat] = (merged.summary.issuesByCategory[cat] || 0) + count;
+    }
+    for (const [severity, count] of Object.entries(report.summary.issuesBySeverity)) {
+      const sev = severity;
+      merged.summary.issuesBySeverity[sev] = (merged.summary.issuesBySeverity[sev] || 0) + count;
+    }
+  }
+  const recMap = /* @__PURE__ */ new Map();
+  for (const report of reports) {
+    for (const rec of report.recommendations) {
+      const key = `${rec.category}:${rec.title}`;
+      if (recMap.has(key)) {
+        const existing = recMap.get(key);
+        existing.affectedUrls.push(...rec.affectedUrls);
+      } else {
+        recMap.set(key, { ...rec, affectedUrls: [...rec.affectedUrls] });
+      }
+    }
+  }
+  merged.recommendations = Array.from(recMap.values()).sort(
+    (a, b) => a.priority - b.priority
+  );
+  return merged;
+}
+
+export { AI_REPORT_SCHEMA, exportJsonReport, generateAiSummary, generateAndSaveReports, generateJsonReport, generateMarkdownReport, generateSplitReports, mergeReports, printReportSummary };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map