Architecture

export function compareStars({
  currentRepos,
  previousSnapshot,
}: CompareStarsParams): ComparisonResults {
  // Builds maps of current vs previous star counts
  // Identifies new repos, removed repos, and deltas
  // Returns ComparisonResults with per-repo and aggregate metrics
}

export function getLastSnapshot(history: History): Snapshot | null;
export function addSnapshot({ history, snapshot, maxHistory }: AddSnapshotParams): History;

export function computeForecast({
  history,
  topRepoNames,
}: ComputeForecastParams): ForecastData | null {
  // Requires at least 3 snapshots
  // Applies linear regression and weighted moving average
  // Forecasts 4 weeks ahead
}

export function diffStargazers({
  current,
  previousMap,
}: DiffStargazersParams): StargazerDiffResult {
  // Identifies new stargazers per repository
  // Returns sorted list by starred_at timestamp
}

export function shouldNotify({
  totalStars,
  starsAtLastNotification,
  threshold,
}: ShouldNotifyParams): boolean {
  // Supports fixed thresholds (N stars)
  // Supports adaptive thresholds ('auto' mode)
  // Adaptive: 1% for <1000 stars, 0.5% for 1000-10000, 0.1% for >10000
}

interface RepoInfo {
  owner: string;
  name: string;
  fullName: string;
  private: boolean;
  archived: boolean;
  fork: boolean;
  stars: number;
}

interface Snapshot {
  timestamp: string;
  totalStars: number;
  repos: SnapshotRepo[];
}

interface Summary {
  totalStars: number;
  totalPrevious: number;
  totalDelta: number;
  newStars: number;
  lostStars: number;
  changed: boolean;
}

export async function getRepos({ octokit, config }: GetReposParams): Promise<RepoInfo[]> {
  const allRepos = await fetchRepos({ octokit, config });
  const filtered = filterRepos({ repos: allRepos, config });
  return mapRepos(filtered);
}

export async function fetchAllStargazers({
  octokit,
  repos,
}: FetchAllStargazersParams): Promise<RepoStargazers[]> {
  // Paginates through stargazers endpoint
  // Returns login, avatar, profile URL, and starred_at timestamp
}

export function initializeDataBranch(dataBranch: string): string {
  // Configures git user (github-actions[bot])
  // Checks if branch exists on remote
  // Creates orphan branch if needed
  // Adds worktree in separate directory
  return dataDir; // e.g., ".star-tracker-data"
}

export function cleanup(dataDir: string): void {
  // Removes worktree after operations complete
}

export function readHistory(dataDir: string): History;
export function writeHistory({ dataDir, history }: WriteHistoryParams): void;
export function writeReport({ dataDir, markdown }: WriteReportParams): void;
export function writeBadge({ dataDir, svg }: WriteBadgeParams): void;
export function writeChart({ dataDir, filename, svg }: WriteChartParams): void;
export function writeCsv({ dataDir, csv }: WriteCsvParams): void;
export function readStargazers(dataDir: string): StargazerMap;
export function writeStargazers({ dataDir, stargazerMap }: WriteStargazersParams): void;

export function commitAndPush({
  dataDir,
  dataBranch,
  message,
}: CommitAndPushParams): boolean {
  // Stages all files with git add -A
  // Checks for staged changes with git diff --cached --quiet
  // Commits and pushes to origin/{dataBranch}
  // Returns true if changes were committed
}

export async function sendEmail({
  emailConfig,
  subject,
  htmlBody,
}: SendEmailParams): Promise<void> {
  // Uses nodemailer with SMTP transport
  // Sends HTML report with inline styles
}

export async function trackStars(): Promise<void> {
  const config = loadConfig();
  const octokit = github.getOctokit(token, ...);
  
  const repos = await getRepos({ octokit, config });
  
  await withDataDir(config.dataBranch, async (dataDir) => {
    const history = readHistory(dataDir);
    const lastSnapshot = getLastSnapshot(history);
    const results = compareStars({ currentRepos: repos, previousSnapshot: lastSnapshot });
    
    if (config.trackStargazers) {
      const repoStargazers = await fetchAllStargazers({ octokit, repos });
      // ... stargazer diffing logic
    }
    
    const forecastData = computeForecast({ history, topRepoNames });
    
    // Generate all reports
    const markdownReport = generateMarkdownReport({ ... });
    const htmlReport = generateHtmlReport({ ... });
    const csvReport = generateCsvReport(results);
    const badge = generateBadge({ ... });
    
    // Generate charts
    const svgChart = generateSvgChart({ ... });
    // ... other charts
    
    // Persist everything
    writeHistory({ dataDir, history: updatedHistory });
    writeReport({ dataDir, markdown: markdownReport });
    // ... other writes
    
    commitAndPush({ dataDir, dataBranch: config.dataBranch, message: commitMsg });
    
    setOutputs({ summary, markdownReport, htmlReport, csvReport, shouldNotify, newStargazers });
    
    // Email if configured
    if (emailConfig && (notify || config.sendOnNoChanges)) {
      await sendEmail({ emailConfig, subject, htmlBody: htmlReport });
    }
  });
}

async function withDataDir(branch: string, fn: (dataDir: string) => Promise<void>): Promise<void> {
  const dataDir = initializeDataBranch(branch);
  try {
    await fn(dataDir);
  } finally {
    cleanup(dataDir);
  }
}

export function generateMarkdownReport(params: GenerateReportParams): string {
  // Renders summary table with delta indicators
  // Embeds chart images from data branch
  // Shows new/removed repos
  // Includes stargazer details if enabled
  // Displays forecast tables
}

export function generateHtmlReport(params: GenerateReportParams): string {
  // Inline CSS for email client compatibility
  // Responsive tables
  // Delta indicators with color coding
}

export function generateCsvReport(results: ComparisonResults): string {
  // Columns: Repository, Stars, Previous, Delta, Status
  // Status: New, Removed, Changed, Unchanged
}

export function generateBadge({ totalStars, locale }: GenerateBadgeParams): string {
  // Localized "stars" label
  // Formatted star count (e.g., 1.2k, 1.5M)
  // Blue color scheme
}

export function generateSvgChart({ history, title, locale }: GenerateSvgChartParams): string | null;
export function generatePerRepoSvgChart({ history, repoFullName, locale }: PerRepoChartParams): string | null;
export function generateComparisonSvgChart({ history, repoNames, title, locale }: ComparisonChartParams): string | null;
export function generateForecastSvgChart({ history, forecastData, locale }: ForecastChartParams): string | null;