@djangocfg/seo 2.1.50

package/src/reports/markdown-report.ts

@@ -0,0 +1,246 @@
+/**
+ * @djangocfg/seo - Markdown Report Generator
+ * Generate human-readable Markdown reports
+ */
+
+import type { SeoReport, SeoIssue, IssueSeverity, IssueCategory } from '../types/index.js';
+
+export interface MarkdownReportOptions {
+  includeRawIssues?: boolean;
+  includeUrls?: boolean;
+  maxUrlsPerIssue?: number;
+}
+
+/**
+ * Generate a Markdown report from SEO data
+ */
+export function generateMarkdownReport(
+  report: SeoReport,
+  options: MarkdownReportOptions = {}
+): string {
+  const { includeRawIssues = true, includeUrls = true, maxUrlsPerIssue = 10 } = options;
+
+  const lines: string[] = [];
+
+  // Header
+  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('');
+
+  // Summary
+  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('');
+
+  // Issues by Severity
+  lines.push('### Issues by Severity');
+  lines.push('');
+  const severities: IssueSeverity[] = ['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('');
+
+  // Issues by Category
+  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 as IssueCategory)} **${formatCategory(category)}:** ${count}`);
+  }
+  lines.push('');
+
+  // Recommendations
+  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('');
+  }
+
+  // Detailed Issues
+  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 as IssueCategory)} ${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('');
+      }
+    }
+  }
+
+  // Footer
+  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');
+}
+
+/**
+ * Generate a concise summary for AI consumption
+ */
+export function generateAiSummary(report: SeoReport): string {
+  const lines: string[] = [];
+
+  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');
+}
+
+// Helper functions
+function getSeverityEmoji(severity: IssueSeverity): string {
+  const emojis: Record<IssueSeverity, string> = {
+    critical: '🔴',
+    error: '🟠',
+    warning: '🟡',
+    info: '🔵',
+  };
+  return emojis[severity];
+}
+
+function getCategoryEmoji(category: IssueCategory): string {
+  const emojis: Record<IssueCategory, string> = {
+    indexing: '📑',
+    crawling: '🕷️',
+    content: '📝',
+    technical: '⚙️',
+    mobile: '📱',
+    performance: '⚡',
+    'structured-data': '🏷️',
+    security: '🔒',
+  };
+  return emojis[category] || '📋';
+}
+
+function getPriorityEmoji(priority: number): string {
+  const emojis: Record<number, string> = {
+    1: '🚨',
+    2: '⚠️',
+    3: '📌',
+    4: '💡',
+    5: 'ℹ️',
+  };
+  return emojis[priority] || '📋';
+}
+
+function getHealthScoreEmoji(score: number): string {
+  if (score >= 90) return '🟢';
+  if (score >= 70) return '🟡';
+  if (score >= 50) return '🟠';
+  return '🔴';
+}
+
+function capitalize(str: string): string {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+function formatCategory(category: string): string {
+  return category
+    .split('-')
+    .map(capitalize)
+    .join(' ');
+}
+
+function groupBy<T>(array: T[], key: keyof T): Record<string, T[]> {
+  return array.reduce(
+    (acc, item) => {
+      const groupKey = String(item[key]);
+      if (!acc[groupKey]) {
+        acc[groupKey] = [];
+      }
+      acc[groupKey].push(item);
+      return acc;
+    },
+    {} as Record<string, T[]>
+  );
+}

package/src/reports/split-report.ts

@@ -0,0 +1,252 @@
+/**
+ * @djangocfg/seo - Split Report Generator
+ * Generates AI-friendly split reports (max 1000 lines each)
+ */
+
+import { writeFileSync, mkdirSync, existsSync, rmSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import type { SeoReport, SeoIssue, IssueCategory, IssueSeverity } from '../types/index.js';
+
+const MAX_LINES = 1000;
+
+export interface SplitReportOptions {
+  outputDir: string;
+  /** Clear output directory before generating */
+  clearOutputDir?: boolean;
+}
+
+export interface SplitReportResult {
+  indexFile: string;
+  categoryFiles: string[];
+  totalFiles: number;
+}
+
+/**
+ * Generate split reports for AI processing
+ */
+export function generateSplitReports(
+  report: SeoReport,
+  options: SplitReportOptions
+): SplitReportResult {
+  const { outputDir, clearOutputDir = true } = options;
+
+  // Clear output directory
+  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 });
+      }
+    }
+  }
+
+  // Ensure output directory exists
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const siteName = new URL(report.siteUrl).hostname.replace(/\./g, '-');
+  const prefix = `seo-${siteName}-${timestamp}`;
+
+  const categoryFiles: string[] = [];
+
+  // Group issues by category
+  const issuesByCategory = groupIssuesByCategory(report.issues);
+  const categories = Object.keys(issuesByCategory) as IssueCategory[];
+
+  // Generate category files
+  for (const category of categories) {
+    const issues = issuesByCategory[category] || [];
+    if (issues.length === 0) continue;
+
+    const chunks = splitIntoChunks(issues, category);
+
+    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 : undefined,
+        totalParts: chunks.length > 1 ? chunks.length : undefined,
+      });
+
+      writeFileSync(filepath, content, 'utf-8');
+      categoryFiles.push(filename);
+    }
+  }
+
+  // Generate index file
+  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,
+  };
+}
+
+/**
+ * Generate compact index file
+ */
+function generateIndexFile(report: SeoReport, categoryFiles: string[]): string {
+  const lines: string[] = [];
+
+  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('');
+
+  // Severity counts
+  lines.push('## Issues');
+  lines.push('');
+  lines.push('| Severity | Count |');
+  lines.push('|----------|-------|');
+  const severities: IssueSeverity[] = ['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('');
+
+  // Top 10 recommendations (compact)
+  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('');
+
+  // File index
+  lines.push('## Files');
+  lines.push('');
+  for (const file of categoryFiles) {
+    lines.push(`- [${file}](./${file})`);
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate compact category file
+ */
+function generateCategoryFile(
+  siteUrl: string,
+  category: IssueCategory,
+  issues: SeoIssue[],
+  opts: { part?: number; totalParts?: number }
+): string {
+  const lines: string[] = [];
+  const partStr = opts.part ? ` (Part ${opts.part}/${opts.totalParts})` : '';
+
+  lines.push(`# ${formatCategory(category)}${partStr}`);
+  lines.push('');
+  lines.push(`Site: ${siteUrl}`);
+  lines.push(`Issues: ${issues.length}`);
+  lines.push('');
+
+  // Group by title for compact display
+  const byTitle = new Map<string, SeoIssue[]>();
+  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('');
+
+    // Compact URL list
+    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');
+}
+
+/**
+ * Split issues into chunks that fit within MAX_LINES
+ */
+function splitIntoChunks(issues: SeoIssue[], category: IssueCategory): SeoIssue[][] {
+  // Estimate lines per issue group (title + severity + recommendation + URLs)
+  const byTitle = new Map<string, SeoIssue[]>();
+  for (const issue of issues) {
+    const group = byTitle.get(issue.title) || [];
+    group.push(issue);
+    byTitle.set(issue.title, group);
+  }
+
+  const chunks: SeoIssue[][] = [];
+  let currentChunk: SeoIssue[] = [];
+  let currentLines = 10; // Header overhead
+
+  for (const [, groupIssues] of byTitle) {
+    // Estimate: 6 lines header + min(20, count) URLs + 2 spacing
+    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: SeoIssue[]): Record<IssueCategory, SeoIssue[]> {
+  const result: Partial<Record<IssueCategory, SeoIssue[]>> = {};
+
+  for (const issue of issues) {
+    if (!result[issue.category]) {
+      result[issue.category] = [];
+    }
+    result[issue.category]!.push(issue);
+  }
+
+  return result as Record<IssueCategory, SeoIssue[]>;
+}
+
+function formatCategory(category: string): string {
+  return category
+    .split('-')
+    .map(s => s.charAt(0).toUpperCase() + s.slice(1))
+    .join(' ');
+}