@djangocfg/seo 2.1.50

package/src/reports/generator.ts

@@ -0,0 +1,244 @@
+/**
+ * @djangocfg/seo - Report Generator
+ * Main report generation orchestrator
+ */
+
+import { writeFileSync, mkdirSync, existsSync, rmSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import consola from 'consola';
+import { generateJsonReport, exportJsonReport } from './json-report.js';
+import { generateMarkdownReport, generateAiSummary } from './markdown-report.js';
+import { generateSplitReports } from './split-report.js';
+import { generateClaudeContext } from './claude-context.js';
+import type {
+  SeoReport,
+  SeoIssue,
+  UrlInspectionResult,
+  CrawlResult,
+  IssueCategory,
+  IssueSeverity,
+} from '../types/index.js';
+
+export interface ReportGeneratorOptions {
+  outputDir: string;
+  formats: ('json' | 'markdown' | 'ai-summary' | 'split')[];
+  includeRawData?: boolean;
+  timestamp?: boolean;
+  /** Clear output directory before generating reports */
+  clearOutputDir?: boolean;
+  /** Maximum URLs to show per issue group (default: 10) */
+  maxUrlsPerIssue?: number;
+}
+
+export interface GeneratedReports {
+  report: SeoReport;
+  files: {
+    json?: string;
+    markdown?: string;
+    aiSummary?: string;
+    split?: {
+      index: string;
+      categories: string[];
+    };
+  };
+}
+
+/**
+ * Generate and save SEO reports
+ */
+export async function generateAndSaveReports(
+  siteUrl: string,
+  data: {
+    issues: SeoIssue[];
+    urlInspections?: UrlInspectionResult[];
+    crawlResults?: CrawlResult[];
+  },
+  options: ReportGeneratorOptions
+): Promise<GeneratedReports> {
+  const {
+    outputDir,
+    formats,
+    includeRawData = false,
+    timestamp = true,
+    clearOutputDir = true,
+    maxUrlsPerIssue = 10,
+  } = options;
+
+  // Clear output directory if requested
+  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 {
+      // Ignore errors
+    }
+  }
+
+  // Ensure output directory exists
+  if (!existsSync(outputDir)) {
+    mkdirSync(outputDir, { recursive: true });
+  }
+
+  // Generate the report
+  const report = generateJsonReport(siteUrl, data, { includeRawData, maxUrlsPerIssue });
+
+  const result: GeneratedReports = {
+    report,
+    files: {},
+  };
+
+  // Generate timestamp for filenames
+  const ts = timestamp
+    ? `-${new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19)}`
+    : '';
+  const siteName = new URL(siteUrl).hostname.replace(/\./g, '-');
+
+  // Generate JSON report
+  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}`);
+  }
+
+  // Generate Markdown report
+  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}`);
+  }
+
+  // Generate AI summary
+  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}`);
+  }
+
+  // Generate split reports (AI-optimized, max 1000 lines each)
+  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)`);
+  }
+
+  // Always generate CLAUDE.md for AI context
+  const claudeContent = generateClaudeContext(report);
+  const claudeFilepath = join(outputDir, 'CLAUDE.md');
+  writeFileSync(claudeFilepath, claudeContent, 'utf-8');
+  consola.success(`AI context saved: ${claudeFilepath}`);
+
+  return result;
+}
+
+/**
+ * Print report summary to console
+ */
+export function printReportSummary(report: SeoReport): void {
+  consola.box(
+    `SEO Report: ${report.siteUrl}\n` +
+      `Health Score: ${report.summary.healthScore}/100\n` +
+      `Total URLs: ${report.summary.totalUrls}\n` +
+      `Indexed: ${report.summary.indexedUrls} | Not Indexed: ${report.summary.notIndexedUrls}\n` +
+      `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)`);
+  }
+}
+
+/**
+ * Merge multiple reports into one
+ */
+export function mergeReports(reports: SeoReport[]): SeoReport {
+  if (reports.length === 0) {
+    throw new Error('Cannot merge empty reports array');
+  }
+
+  const merged: SeoReport = {
+    id: `merged-${Date.now().toString(36)}`,
+    siteUrl: reports.map((r) => r.siteUrl).join(', '),
+    generatedAt: 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: {} as any,
+      issuesBySeverity: {} as any,
+      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: [],
+  };
+
+  // Merge issue counts
+  for (const report of reports) {
+    for (const [category, count] of Object.entries(report.summary.issuesByCategory)) {
+      const cat = category as IssueCategory;
+      merged.summary.issuesByCategory[cat] =
+        (merged.summary.issuesByCategory[cat] || 0) + count;
+    }
+    for (const [severity, count] of Object.entries(report.summary.issuesBySeverity)) {
+      const sev = severity as IssueSeverity;
+      merged.summary.issuesBySeverity[sev] =
+        (merged.summary.issuesBySeverity[sev] || 0) + count;
+    }
+  }
+
+  // Merge and deduplicate recommendations
+  const recMap = new Map<string, typeof merged.recommendations[0]>();
+  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;
+}

package/src/reports/index.ts

@@ -0,0 +1,27 @@
+/**
+ * @djangocfg/seo - Reports Module
+ * Report generation tools
+ */
+
+export {
+  generateAndSaveReports,
+  printReportSummary,
+  mergeReports,
+} from './generator.js';
+export type { ReportGeneratorOptions, GeneratedReports } from './generator.js';
+
+export {
+  generateJsonReport,
+  exportJsonReport,
+  AI_REPORT_SCHEMA,
+} from './json-report.js';
+export type { JsonReportOptions } from './json-report.js';
+
+export {
+  generateMarkdownReport,
+  generateAiSummary,
+} from './markdown-report.js';
+export type { MarkdownReportOptions } from './markdown-report.js';
+
+export { generateSplitReports } from './split-report.js';
+export type { SplitReportOptions, SplitReportResult } from './split-report.js';

package/src/reports/json-report.ts

@@ -0,0 +1,320 @@
+/**
+ * @djangocfg/seo - JSON Report Generator
+ * Generate AI-friendly JSON reports
+ */
+
+import type {
+  SeoReport,
+  SeoIssue,
+  UrlInspectionResult,
+  CrawlResult,
+  ReportSummary,
+  Recommendation,
+  IssueCategory,
+  IssueSeverity,
+} from '../types/index.js';
+
+export interface JsonReportOptions {
+  includeRawData?: boolean;
+  prettyPrint?: boolean;
+  /** Maximum URLs to include per issue group (default: 10) */
+  maxUrlsPerIssue?: number;
+}
+
+/**
+ * Generate a comprehensive JSON report
+ */
+export function generateJsonReport(
+  siteUrl: string,
+  data: {
+    issues: SeoIssue[];
+    urlInspections?: UrlInspectionResult[];
+    crawlResults?: CrawlResult[];
+  },
+  options: JsonReportOptions = {}
+): SeoReport {
+  const { issues, urlInspections = [], crawlResults = [] } = data;
+  const maxUrlsPerIssue = options.maxUrlsPerIssue ?? 10;
+
+  // Limit issues to maxUrlsPerIssue per title group
+  const limitedIssues = limitIssuesByTitle(issues, maxUrlsPerIssue);
+
+  const report: SeoReport = {
+    id: generateReportId(),
+    siteUrl,
+    generatedAt: 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;
+}
+
+/**
+ * Limit issues to maxUrls per issue title group
+ */
+function limitIssuesByTitle(issues: SeoIssue[], maxUrls: number): SeoIssue[] {
+  const byTitle = new Map<string, SeoIssue[]>();
+
+  for (const issue of issues) {
+    const existing = byTitle.get(issue.title) || [];
+    existing.push(issue);
+    byTitle.set(issue.title, existing);
+  }
+
+  const limited: SeoIssue[] = [];
+  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;
+}
+
+/**
+ * Generate report summary
+ */
+function generateSummary(
+  issues: SeoIssue[],
+  urlInspections: UrlInspectionResult[],
+  crawlResults: CrawlResult[]
+): ReportSummary {
+  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;
+    },
+    {} as Record<IssueCategory, number>
+  );
+
+  const issuesBySeverity = issues.reduce(
+    (acc, issue) => {
+      acc[issue.severity] = (acc[issue.severity] || 0) + 1;
+      return acc;
+    },
+    {} as Record<IssueSeverity, number>
+  );
+
+  // Calculate health score (0-100)
+  const healthScore = calculateHealthScore(issues, totalUrls);
+
+  return {
+    totalUrls,
+    indexedUrls,
+    notIndexedUrls,
+    issuesByCategory,
+    issuesBySeverity,
+    healthScore,
+  };
+}
+
+/**
+ * Calculate overall SEO health score
+ */
+function calculateHealthScore(issues: SeoIssue[], totalUrls: number): number {
+  if (totalUrls === 0) return 100;
+
+  const severityWeights: Record<IssueSeverity, number> = {
+    critical: 10,
+    error: 5,
+    warning: 2,
+    info: 0.5,
+  };
+
+  const totalPenalty = issues.reduce(
+    (sum, issue) => sum + severityWeights[issue.severity],
+    0
+  );
+
+  // Max penalty per URL is 20 points
+  const maxPenalty = totalUrls * 20;
+  const penaltyRatio = Math.min(totalPenalty / maxPenalty, 1);
+
+  return Math.round((1 - penaltyRatio) * 100);
+}
+
+/**
+ * Generate prioritized recommendations
+ */
+function generateRecommendations(issues: SeoIssue[], maxUrls: number = 10): Recommendation[] {
+  const recommendations: Recommendation[] = [];
+  const issueGroups = new Map<string, SeoIssue[]>();
+
+  // Group issues by title (similar issues)
+  for (const issue of issues) {
+    const key = `${issue.category}:${issue.title}`;
+    if (!issueGroups.has(key)) {
+      issueGroups.set(key, []);
+    }
+    issueGroups.get(key)!.push(issue);
+  }
+
+  // Create recommendations for each group
+  for (const [, groupedIssues] of issueGroups) {
+    const firstIssue = groupedIssues[0];
+    if (!firstIssue) continue;
+    const severity = firstIssue.severity;
+
+    const priority: 1 | 2 | 3 | 4 | 5 =
+      severity === 'critical'
+        ? 1
+        : severity === 'error'
+          ? 2
+          : severity === 'warning'
+            ? 3
+            : 4;
+
+    const impact: 'high' | 'medium' | 'low' =
+      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],
+    });
+  }
+
+  // Sort by priority
+  return recommendations.sort((a, b) => a.priority - b.priority);
+}
+
+/**
+ * Sort issues by severity and category
+ */
+function sortIssues(issues: SeoIssue[]): SeoIssue[] {
+  const severityOrder: Record<IssueSeverity, number> = {
+    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);
+  });
+}
+
+/**
+ * Generate unique report ID
+ */
+function generateReportId(): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 8);
+  return `seo-report-${timestamp}-${random}`;
+}
+
+/**
+ * Export report as JSON string
+ */
+export function exportJsonReport(report: SeoReport, pretty = true): string {
+  return JSON.stringify(report, null, pretty ? 2 : 0);
+}
+
+/**
+ * Generate AI-optimized schema for the report
+ * This schema helps AI understand the report structure
+ */
+export const 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' } },
+        },
+      },
+    },
+  },
+};