create-hq 5.0.0

package/template/workers/content-shared/lib/github-integration.ts

@@ -0,0 +1,582 @@
+/**
+ * GitHub Integration (US-016, US-017)
+ * Create issues and PRs from content analysis suggestions
+ */
+
+import type { Suggestion } from './recommendations.js';
+import type { FullAnalysis, PageContent } from './types.js';
+
+// ============================================
+// Types
+// ============================================
+
+export interface GitHubIssue {
+  title: string;
+  body: string;
+  labels: string[];
+  assignees?: string[];
+}
+
+export interface GitHubPR {
+  title: string;
+  body: string;
+  branch: string;
+  baseBranch: string;
+  files: Array<{ path: string; content: string }>;
+}
+
+export interface GitHubConfig {
+  owner: string;
+  repo: string;
+  baseBranch: string;
+  issueLabels: string[];
+  prLabels: string[];
+  assignees?: string[];
+}
+
+export const DEFAULT_GITHUB_CONFIG: GitHubConfig = {
+  owner: '',
+  repo: '',
+  baseBranch: 'main',
+  issueLabels: ['content', 'automated'],
+  prLabels: ['content-fix', 'automated'],
+  assignees: [],
+};
+
+// ============================================
+// Issue Generation (US-016)
+// ============================================
+
+/**
+ * Generate GitHub issue from a single suggestion
+ */
+export function createIssueFromSuggestion(
+  suggestion: Suggestion,
+  config?: Partial<GitHubConfig>
+): GitHubIssue {
+  const cfg = { ...DEFAULT_GITHUB_CONFIG, ...config };
+
+  const title = generateIssueTitle(suggestion);
+  const body = formatIssueBody(suggestion);
+  const labels = generateIssueLabels(suggestion, cfg.issueLabels);
+
+  return {
+    title,
+    body,
+    labels,
+    assignees: cfg.assignees,
+  };
+}
+
+/**
+ * Generate batch of issues from full analysis
+ */
+export function createIssuesFromAnalysis(
+  analysis: FullAnalysis,
+  suggestions: Suggestion[],
+  maxIssues: number = 10,
+  config?: Partial<GitHubConfig>
+): GitHubIssue[] {
+  // Sort by priority and take top N
+  const sorted = [...suggestions].sort((a, b) => b.priority - a.priority);
+  const topSuggestions = sorted.slice(0, maxIssues);
+
+  return topSuggestions.map(s => createIssueFromSuggestion(s, config));
+}
+
+/**
+ * Generate issue title from suggestion
+ */
+function generateIssueTitle(suggestion: Suggestion): string {
+  const typeLabel = formatTypeLabel(suggestion.type);
+  const impactLabel = suggestion.impact === 'high' ? '[HIGH] ' : '';
+
+  // Truncate if too long (GitHub has 256 char limit)
+  const location = suggestion.sectionId
+    ? `${suggestion.pageSlug}#${suggestion.sectionId}`
+    : suggestion.pageSlug;
+
+  let title = `${impactLabel}${typeLabel}: ${location}`;
+
+  // Add brief description
+  const desc = suggestion.rationale.split('.')[0];
+  if (title.length + desc.length < 200) {
+    title += ` - ${desc}`;
+  }
+
+  return title.slice(0, 250);
+}
+
+/**
+ * Format issue body with context
+ */
+export function formatIssueBody(suggestion: Suggestion): string {
+  const lines: string[] = [];
+
+  // Overview
+  lines.push('## Overview');
+  lines.push('');
+  lines.push(`**Type:** ${formatTypeLabel(suggestion.type)}`);
+  lines.push(`**Page:** \`${suggestion.pageSlug}\``);
+  if (suggestion.sectionId) {
+    lines.push(`**Section:** \`${suggestion.sectionId}\``);
+  }
+  lines.push(`**Source:** ${formatSourceLabel(suggestion.source)}`);
+  lines.push(`**Impact:** ${suggestion.impact}`);
+  lines.push(`**Effort:** ${formatEffortLabel(suggestion.effort)}`);
+  lines.push('');
+
+  // Current State
+  lines.push('## Current Content');
+  lines.push('');
+  lines.push('```');
+  lines.push(suggestion.original);
+  lines.push('```');
+  lines.push('');
+
+  // Suggested Change
+  lines.push('## Suggested Change');
+  lines.push('');
+  lines.push('```');
+  lines.push(suggestion.suggested);
+  lines.push('```');
+  lines.push('');
+
+  // Rationale
+  lines.push('## Rationale');
+  lines.push('');
+  lines.push(suggestion.rationale);
+  lines.push('');
+
+  // Metadata
+  lines.push('---');
+  lines.push('');
+  lines.push('*This issue was automatically generated by the content analysis worker.*');
+  lines.push(`*Suggestion ID: \`${suggestion.id}\`*`);
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate issue labels based on suggestion properties
+ */
+function generateIssueLabels(
+  suggestion: Suggestion,
+  baseLabels: string[]
+): string[] {
+  const labels = [...baseLabels];
+
+  // Add type-specific label
+  labels.push(`type:${suggestion.type}`);
+
+  // Add source label
+  labels.push(`source:${suggestion.source}`);
+
+  // Add priority label
+  if (suggestion.impact === 'high') {
+    labels.push('priority:high');
+  } else if (suggestion.impact === 'medium') {
+    labels.push('priority:medium');
+  } else {
+    labels.push('priority:low');
+  }
+
+  // Add effort label
+  if (suggestion.effort === 'quick') {
+    labels.push('good-first-issue');
+  }
+
+  return labels;
+}
+
+// ============================================
+// PR Generation (US-017)
+// ============================================
+
+/**
+ * Generate PR from accepted suggestions
+ */
+export function createPRFromSuggestions(
+  suggestions: Suggestion[],
+  pageContents: Map<string, { path: string; content: string }>,
+  config?: Partial<GitHubConfig>
+): GitHubPR {
+  const cfg = { ...DEFAULT_GITHUB_CONFIG, ...config };
+
+  // Group suggestions by page
+  const suggestionsByPage = new Map<string, Suggestion[]>();
+  for (const suggestion of suggestions) {
+    const existing = suggestionsByPage.get(suggestion.pageSlug) ?? [];
+    existing.push(suggestion);
+    suggestionsByPage.set(suggestion.pageSlug, existing);
+  }
+
+  // Apply suggestions to each page
+  const files: Array<{ path: string; content: string }> = [];
+  for (const [pageSlug, pageSuggestions] of suggestionsByPage) {
+    const pageInfo = pageContents.get(pageSlug);
+    if (!pageInfo) continue;
+
+    let updatedContent = pageInfo.content;
+    for (const suggestion of pageSuggestions) {
+      updatedContent = applySuggestionToContent(suggestion, updatedContent);
+    }
+
+    files.push({
+      path: pageInfo.path,
+      content: updatedContent,
+    });
+  }
+
+  // Generate PR metadata
+  const title = generatePRTitle(suggestions);
+  const body = formatPRBody(suggestions, suggestionsByPage);
+  const branch = generateBranchName(suggestions);
+
+  return {
+    title,
+    body,
+    branch,
+    baseBranch: cfg.baseBranch,
+    files,
+  };
+}
+
+/**
+ * Apply a single suggestion to content
+ * Uses simple string replacement
+ */
+export function applySuggestionToContent(
+  suggestion: Suggestion,
+  content: string
+): string {
+  // For simple text replacements
+  if (content.includes(suggestion.original)) {
+    return content.replace(suggestion.original, suggestion.suggested);
+  }
+
+  // Try case-insensitive match
+  const regex = new RegExp(escapeRegExp(suggestion.original), 'gi');
+  if (regex.test(content)) {
+    return content.replace(regex, suggestion.suggested);
+  }
+
+  // No match found, return unchanged
+  return content;
+}
+
+/**
+ * Escape special regex characters
+ */
+function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Generate commit message for suggestions
+ */
+export function generateCommitMessage(suggestions: Suggestion[]): string {
+  if (suggestions.length === 0) {
+    return 'chore: no content changes';
+  }
+
+  if (suggestions.length === 1) {
+    const s = suggestions[0];
+    return `content(${s.pageSlug}): ${formatTypeLabel(s.type).toLowerCase()} update
+
+${s.rationale}`;
+  }
+
+  // Multiple suggestions
+  const pages = [...new Set(suggestions.map(s => s.pageSlug))];
+  const types = [...new Set(suggestions.map(s => s.type))];
+
+  let message = `content: update ${suggestions.length} items across ${pages.length} page(s)\n\n`;
+
+  // Group by page
+  for (const page of pages) {
+    const pageSuggestions = suggestions.filter(s => s.pageSlug === page);
+    message += `## ${page}\n`;
+    for (const s of pageSuggestions) {
+      message += `- ${formatTypeLabel(s.type)}: ${s.rationale.split('.')[0]}\n`;
+    }
+    message += '\n';
+  }
+
+  return message;
+}
+
+/**
+ * Generate PR title
+ */
+function generatePRTitle(suggestions: Suggestion[]): string {
+  if (suggestions.length === 1) {
+    const s = suggestions[0];
+    return `[Content] ${formatTypeLabel(s.type)} fix for ${s.pageSlug}`;
+  }
+
+  const pages = [...new Set(suggestions.map(s => s.pageSlug))];
+  const highImpact = suggestions.filter(s => s.impact === 'high').length;
+
+  let title = `[Content] ${suggestions.length} improvements`;
+  if (pages.length === 1) {
+    title += ` for ${pages[0]}`;
+  } else {
+    title += ` across ${pages.length} pages`;
+  }
+
+  if (highImpact > 0) {
+    title += ` (${highImpact} high priority)`;
+  }
+
+  return title;
+}
+
+/**
+ * Format PR body
+ */
+function formatPRBody(
+  suggestions: Suggestion[],
+  suggestionsByPage: Map<string, Suggestion[]>
+): string {
+  const lines: string[] = [];
+
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`This PR applies **${suggestions.length} content improvements** identified by automated analysis.`);
+  lines.push('');
+
+  // Stats
+  const highImpact = suggestions.filter(s => s.impact === 'high').length;
+  const mediumImpact = suggestions.filter(s => s.impact === 'medium').length;
+  const lowImpact = suggestions.filter(s => s.impact === 'low').length;
+
+  lines.push('### Impact Breakdown');
+  lines.push('');
+  lines.push(`- High: ${highImpact}`);
+  lines.push(`- Medium: ${mediumImpact}`);
+  lines.push(`- Low: ${lowImpact}`);
+  lines.push('');
+
+  // Changes by page
+  lines.push('## Changes by Page');
+  lines.push('');
+
+  for (const [pageSlug, pageSuggestions] of suggestionsByPage) {
+    lines.push(`### ${pageSlug}`);
+    lines.push('');
+
+    for (const s of pageSuggestions) {
+      lines.push(`#### ${formatTypeLabel(s.type)}`);
+      lines.push('');
+      lines.push('**Before:**');
+      lines.push('```');
+      lines.push(truncate(s.original, 200));
+      lines.push('```');
+      lines.push('');
+      lines.push('**After:**');
+      lines.push('```');
+      lines.push(truncate(s.suggested, 200));
+      lines.push('```');
+      lines.push('');
+      lines.push(`_${s.rationale}_`);
+      lines.push('');
+    }
+  }
+
+  // Test plan
+  lines.push('## Test Plan');
+  lines.push('');
+  lines.push('- [ ] Review each content change for accuracy');
+  lines.push('- [ ] Verify formatting is preserved');
+  lines.push('- [ ] Check page renders correctly');
+  lines.push('- [ ] Confirm no unintended changes');
+  lines.push('');
+
+  // Footer
+  lines.push('---');
+  lines.push('');
+  lines.push('*This PR was automatically generated by the content analysis worker.*');
+
+  return lines.join('\n');
+}
+
+/**
+ * Generate branch name
+ */
+function generateBranchName(suggestions: Suggestion[]): string {
+  const timestamp = new Date().toISOString().split('T')[0].replace(/-/g, '');
+
+  if (suggestions.length === 1) {
+    const s = suggestions[0];
+    const slug = s.pageSlug.replace(/[^a-z0-9]/gi, '-').toLowerCase();
+    return `content/${timestamp}-${slug}-${s.type}`;
+  }
+
+  const pages = [...new Set(suggestions.map(s => s.pageSlug))];
+  if (pages.length === 1) {
+    const slug = pages[0].replace(/[^a-z0-9]/gi, '-').toLowerCase();
+    return `content/${timestamp}-${slug}-fixes`;
+  }
+
+  return `content/${timestamp}-multi-page-fixes`;
+}
+
+// ============================================
+// GitHub CLI Commands
+// ============================================
+
+/**
+ * Generate gh CLI command to create an issue
+ */
+export function generateGitHubIssueCommand(
+  issue: GitHubIssue,
+  config?: Partial<GitHubConfig>
+): string {
+  const cfg = { ...DEFAULT_GITHUB_CONFIG, ...config };
+
+  const parts = ['gh issue create'];
+
+  // Title
+  parts.push(`--title "${escapeShell(issue.title)}"`);
+
+  // Body (use heredoc for multi-line)
+  parts.push(`--body "${escapeShell(issue.body)}"`);
+
+  // Labels
+  if (issue.labels.length > 0) {
+    parts.push(`--label "${issue.labels.join(',')}"`);
+  }
+
+  // Assignees
+  if (issue.assignees && issue.assignees.length > 0) {
+    parts.push(`--assignee "${issue.assignees.join(',')}"`);
+  }
+
+  // Repo (if specified)
+  if (cfg.owner && cfg.repo) {
+    parts.push(`--repo ${cfg.owner}/${cfg.repo}`);
+  }
+
+  return parts.join(' \\\n  ');
+}
+
+/**
+ * Generate gh CLI command to create a PR
+ */
+export function generateGitHubPRCommand(
+  pr: GitHubPR,
+  config?: Partial<GitHubConfig>
+): string {
+  const cfg = { ...DEFAULT_GITHUB_CONFIG, ...config };
+
+  const parts = ['gh pr create'];
+
+  // Title
+  parts.push(`--title "${escapeShell(pr.title)}"`);
+
+  // Body
+  parts.push(`--body "${escapeShell(pr.body)}"`);
+
+  // Base branch
+  parts.push(`--base ${pr.baseBranch}`);
+
+  // Head branch
+  parts.push(`--head ${pr.branch}`);
+
+  // Labels
+  if (cfg.prLabels.length > 0) {
+    parts.push(`--label "${cfg.prLabels.join(',')}"`);
+  }
+
+  // Repo
+  if (cfg.owner && cfg.repo) {
+    parts.push(`--repo ${cfg.owner}/${cfg.repo}`);
+  }
+
+  return parts.join(' \\\n  ');
+}
+
+/**
+ * Escape shell special characters
+ */
+function escapeShell(str: string): string {
+  return str
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\$/g, '\\$')
+    .replace(/`/g, '\\`');
+}
+
+// ============================================
+// Batch Processing
+// ============================================
+
+/**
+ * Create issues for all high-impact suggestions
+ */
+export function createHighImpactIssues(
+  suggestions: Suggestion[],
+  config?: Partial<GitHubConfig>
+): GitHubIssue[] {
+  const highImpact = suggestions.filter(s => s.impact === 'high');
+  return highImpact.map(s => createIssueFromSuggestion(s, config));
+}
+
+/**
+ * Create issues grouped by page
+ */
+export function createIssuesByPage(
+  suggestions: Suggestion[],
+  config?: Partial<GitHubConfig>
+): Map<string, GitHubIssue[]> {
+  const issuesByPage = new Map<string, GitHubIssue[]>();
+
+  for (const suggestion of suggestions) {
+    const issue = createIssueFromSuggestion(suggestion, config);
+    const existing = issuesByPage.get(suggestion.pageSlug) ?? [];
+    existing.push(issue);
+    issuesByPage.set(suggestion.pageSlug, existing);
+  }
+
+  return issuesByPage;
+}
+
+// ============================================
+// Helper Functions
+// ============================================
+
+function formatTypeLabel(type: Suggestion['type']): string {
+  const labels: Record<Suggestion['type'], string> = {
+    text: 'Text',
+    structure: 'Structure',
+    cta: 'CTA',
+    stat: 'Statistic',
+    claim: 'Claim',
+  };
+  return labels[type] ?? type;
+}
+
+function formatSourceLabel(source: Suggestion['source']): string {
+  const labels: Record<Suggestion['source'], string> = {
+    brand: 'Brand Voice',
+    sales: 'Conversion',
+    product: 'Product Accuracy',
+    legal: 'Compliance',
+  };
+  return labels[source] ?? source;
+}
+
+function formatEffortLabel(effort: Suggestion['effort']): string {
+  const labels: Record<Suggestion['effort'], string> = {
+    quick: 'Quick Fix',
+    moderate: 'Moderate',
+    significant: 'Significant',
+  };
+  return labels[effort] ?? effort;
+}
+
+function truncate(text: string, maxLen: number): string {
+  if (text.length <= maxLen) return text;
+  return text.slice(0, maxLen - 3) + '...';
+}