github-discover 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# github-discover-cli
+
+[中文](./README_zh.md) | English
+
+A lightweight CLI tool to discover **newly created and fast-growing** open-source repositories and trending topics on GitHub.
+
+Uses the GitHub Search API to filter high-star repos, track growth trends, and surface tech hotspots by day, week, month, or year.
+
+## Features
+
+- **`trending`** — Smart ranking by stars-per-day, highlighting truly fast-rising projects
+- **`popular`** — Newly created high-star repos within a given time period, sorted by star count
+- **`topic`** — Trending topics across popular repos, scored by frequency and total stars
+- Filter by **programming language**, with output as a **terminal table** or **JSON**
+
+## Installation
+
+Requires [Node.js](https://nodejs.org/) **18+**.
+
+```bash
+git clone https://github.com/coderyi/github-discover-cli.git
+cd github-discover-cli
+npm install && npm run build
+```
+
+## Usage
+
+### `trending` — Growth Trends
+
+Ranks repos by stars-per-day (with age smoothing), rather than raw star count.
+
+```bash
+github-discover trending                         # fastest growing repos recently
+github-discover trending -p monthly -l Python    # monthly, Python only
+```
+
+### `popular` — Popular New Repos
+
+```bash
+github-discover popular                          # popular repos from the past day
+github-discover popular -p weekly -l Rust        # past week, Rust only
+github-discover popular -p monthly -n 10 --json  # monthly, top 10, JSON output
+```
+
+### `topic` — Topic Insights
+
+Aggregates frequent topic tags from popular repos, scored by occurrence count and total associated stars.
+
+```bash
+github-discover topic                            # recent trending topics
+github-discover topic -p yearly -n 20            # yearly, top 20
+```
+
+## Options
+
+All subcommands support the following options:
+
+| Option | Short | Description | Default |
+| --- | --- | --- | --- |
+| `--period <period>` | `-p` | Time window: `daily` \| `weekly` \| `monthly` \| `yearly` | `daily` |
+| `--limit <number>` | `-n` | Number of results (1–100) | `50` (topic: `30`) |
+| `--language <lang>` | `-l` | Programming language filter | none |
+| `--min-stars <number>` | `-s` | Minimum star threshold | auto by period \* |
+| `--json` | — | Output as JSON | `false` |
+
+\* `--min-stars` defaults: daily `60` · weekly `500` · monthly `4000` · yearly `10000`
+
+## Output Examples
+
+**Table mode (default):**
+
+| Name         | Stars | Lang       | Created    | URL                             | Description |
+| ------------ | ----- | ---------- | ---------- | ------------------------------- | ----------- |
+| owner1/repo1 | 1234  | TypeScript | 2026-03-09 | https://github.com/owner1/repo1 | description |
+
+**JSON mode** — pipe to `jq` for further processing:
+
+```bash
+github-discover trending --json | jq '.[].full_name'
+```
+
+
+
+## License
+
+MIT

package/README_zh.md

@@ -0,0 +1,85 @@
+# github-discover-cli
+
+中文 | [English](./README.md)
+
+一个轻量级命令行工具，帮助你发现 GitHub 上**新创建且快速增长**的开源仓库和热门话题。
+
+通过 GitHub Search API，按日 / 周 / 月 / 年维度筛选高星仓库、追踪增长趋势、洞察技术热点。
+
+## 功能亮点
+
+- **增长趋势** (`trending`) — 基于「日均星标数」智能排序，突出真正快速崛起的项目
+- **热门仓库** (`popular`) — 指定时间段内新创建的高星仓库，按星标数排序
+- **话题洞察** (`topic`) — 热门仓库中的高频话题，综合频率与星标数评分排名
+- 支持按**编程语言**过滤，输出**终端表格**或 **JSON**
+
+## 安装
+
+需要 [Node.js](https://nodejs.org/) **18+**
+
+```bash
+git clone https://github.com/coderyi/github-discover-cli.git
+cd github-discover-cli
+npm install && npm run build
+```
+
+## 使用方法
+
+### `trending` — 增长趋势
+
+使用「日均星标数」（带平滑因子）衡量增长速度，区别于简单的星标排序。
+
+```bash
+github-discover trending                         # 近期增长最快的仓库
+github-discover trending -p monthly -l Python    # 月度，限定 Python
+```
+
+### `popular` — 热门新仓库
+
+```bash
+github-discover popular                          # 过去一天的热门仓库
+github-discover popular -p weekly -l Rust        # 过去一周，限定 Rust
+github-discover popular -p monthly -n 10 --json  # 月度，前 10 个，JSON 输出
+```
+
+### `topic` — 话题洞察
+
+统计热门仓库中的高频话题标签，综合出现次数和关联星标总数评分。
+
+```bash
+github-discover topic                            # 近期热门话题
+github-discover topic -p yearly -n 20            # 年度，前 20 个
+```
+
+## 命令参考
+
+所有子命令均支持以下选项：
+
+| 选项 | 简写 | 说明 | 默认值 |
+| --- | --- | --- | --- |
+| `--period <period>` | `-p` | 时间维度：`daily` \| `weekly` \| `monthly` \| `yearly` | `daily` |
+| `--limit <number>` | `-n` | 返回结果数量（1–100） | `50`（topic 为 `30`） |
+| `--language <lang>` | `-l` | 编程语言过滤 | 不限 |
+| `--min-stars <number>` | `-s` | 最低星标数阈值 | 按时间维度自动设定 \* |
+| `--json` | — | 以 JSON 格式输出 | `false` |
+
+\* `--min-stars` 默认值：daily `60` · weekly `500` · monthly `4000` · yearly `10000`
+
+## 输出示例
+
+**表格模式（默认）：**
+
+| Name         | Stars | Lang       | Created    | URL                             | Description |
+| ------------ | ----- | ---------- | ---------- | ------------------------------- | ----------- |
+| owner1/repo1 | 1234  | TypeScript | 2026-03-09 | https://github.com/owner1/repo1 | description |
+
+**JSON 模式** 可配合 `jq` 做进一步处理：
+
+```bash
+github-discover trending --json | jq '.[].full_name'
+```
+
+
+## 许可证
+
+MIT

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "github-discover",
+  "version": "0.1.0",
+  "description": "A minimal CLI to discover newly created popular GitHub repositories by day/week/month.",
+  "bin": {
+    "github-discover": "dist/cli.js"
+  },
+  "type": "commonjs",
+  "main": "dist/cli.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/cli.js",
+    "dev": "ts-node src/cli.ts"
+  },
+  "keywords": [
+    "github",
+    "cli",
+    "discover",
+    "repositories"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "commander": "^13.1.0",
+    "undici": "^6.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/cli.ts

@@ -0,0 +1,122 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { runPopularCommand } from "./commands/popular";
+import { runTrendingCommand } from "./commands/trending";
+import { runTopicCommand } from "./commands/topic";
+
+const program = new Command();
+
+program
+  .name("github-discover")
+  .description(
+    "Discover newly created popular GitHub repositories and trending topics (daily/weekly/monthly/yearly)."
+  )
+  .version("0.1.0");
+  
+  program
+  .command("trending")
+  .description(
+    "List trending repositories based on lifetime stars per day, adjusted by repository age."
+  )
+  .option(
+    "-p, --period <period>",
+    "time period for repository creation window: daily | weekly | monthly | yearly",
+    "daily"
+  )
+  .option(
+    "-n, --limit <number>",
+    "maximum number of repositories to return (1-100)",
+    "50"
+  )
+  .option(
+    "-l, --language <language>",
+    "optional programming language filter, e.g. TypeScript"
+  )
+  .option(
+    "-s, --min-stars <number>",
+    "minimum star count threshold (defaults: daily 60, weekly 500, monthly 4000, yearly 10000)"
+  )
+  .option("--json", "output JSON instead of a table", false)
+  .action(async (options) => {
+    try {
+      await runTrendingCommand(options);
+    } catch (err) {
+      const error = err as Error;
+      console.error("Error:", error.message);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("popular")
+  .description("List newly created popular repositories for a given period.")
+  .option(
+    "-p, --period <period>",
+    "time period: daily | weekly | monthly | yearly",
+    "daily"
+  )
+  .option(
+    "-n, --limit <number>",
+    "maximum number of repositories to return (1-100)",
+    "50"
+  )
+  .option(
+    "-l, --language <language>",
+    "optional programming language filter, e.g. TypeScript"
+  )
+  .option(
+    "-s, --min-stars <number>",
+    "minimum star count threshold (defaults: daily 60, weekly 500, monthly 4000, yearly 10000)"
+  )
+  .option("--json", "output JSON instead of a table", false)
+  .action(async (options) => {
+    try {
+      await runPopularCommand(options);
+    } catch (err) {
+      const error = err as Error;
+      console.error("Error:", error.message);
+      process.exitCode = 1;
+    }
+  });
+
+program
+  .command("topic")
+  .description(
+    "List trending repository topics for a given period based on frequency and stars."
+  )
+  .option(
+    "-p, --period <period>",
+    "time period: daily | weekly | monthly | yearly",
+    "daily"
+  )
+  .option(
+    "-n, --limit <number>",
+    "maximum number of topics to return (1-100)",
+    "30"
+  )
+  .option(
+    "-l, --language <language>",
+    "optional programming language filter, e.g. TypeScript"
+  )
+  .option(
+    "-s, --min-stars <number>",
+    "minimum star count threshold (defaults: daily 60, weekly 500, monthly 4000, yearly 10000)"
+  )
+  .option("--json", "output JSON instead of a table", false)
+  .action(async (options) => {
+    try {
+      await runTopicCommand(options);
+    } catch (err) {
+      const error = err as Error;
+      console.error("Error:", error.message);
+      process.exitCode = 1;
+    }
+  });
+
+program.parseAsync(process.argv).catch((err) => {
+  const error = err as Error;
+  console.error("Error:", error.message);
+  process.exit(1);
+});
+

package/src/commands/popular.ts

@@ -0,0 +1,68 @@
+import { GitHubClient } from "../github/client";
+import { searchNewPopularRepositories } from "../github/repoSearch";
+import { getStartDate, Period } from "../utils/dateRange";
+import { printRepositories } from "../utils/output";
+
+interface PopularCliOptions {
+  period?: string;
+  limit?: string;
+  language?: string;
+  minStars?: string;
+  json?: boolean;
+}
+
+export async function runPopularCommand(
+  options: PopularCliOptions
+): Promise<void> {
+  const periodInput = (options.period ?? "daily").toLowerCase();
+  const validPeriods: Period[] = ["daily", "weekly", "monthly", "yearly"];
+  const defaultMinStarsByPeriod: Record<Period, number> = {
+    daily: 60,
+    weekly: 500,
+    monthly: 4000,
+    yearly: 10000,
+  };
+
+  if (!validPeriods.includes(periodInput as Period)) {
+    throw new Error(
+      `Invalid period "${options.period}". Expected one of: daily, weekly, monthly, yearly.`
+    );
+  }
+
+  const period = periodInput as Period;
+
+  const limit = clampToInt(options.limit ?? "50", 1, 100, "limit");
+  const minStars = clampToInt(
+    options.minStars ?? String(defaultMinStarsByPeriod[period]),
+    1,
+    Number.MAX_SAFE_INTEGER,
+    "min-stars"
+  );
+
+  const startDate = getStartDate(period);
+  const client = new GitHubClient();
+
+  const repos = await searchNewPopularRepositories(client, {
+    startDate,
+    minStars,
+    language: options.language,
+    limit,
+  });
+
+  printRepositories(repos, { json: Boolean(options.json) });
+}
+
+function clampToInt(
+  valueStr: string,
+  min: number,
+  max: number,
+  label: string
+): number {
+  const value = Number.parseInt(valueStr, 10);
+  if (Number.isNaN(value)) {
+    throw new Error(`Invalid number for ${label}: "${valueStr}".`);
+  }
+  const clamped = Math.min(Math.max(value, min), max);
+  return clamped;
+}
+

package/src/commands/topic.ts

@@ -0,0 +1,85 @@
+import { GitHubClient } from "../github/client";
+import {
+  searchRepositoriesForTopics,
+  TopicOptionsInternal,
+} from "../github/repoSearch";
+import { aggregateTopicStats } from "../github/topicStats";
+import { getStartDate, Period } from "../utils/dateRange";
+import { printTopicStats } from "../utils/output";
+
+interface TopicCliOptions {
+  period?: string;
+  limit?: string;
+  language?: string;
+  minStars?: string;
+  json?: boolean;
+}
+
+export async function runTopicCommand(
+  options: TopicCliOptions
+): Promise<void> {
+  const periodInput = (options.period ?? "daily").toLowerCase();
+  const validPeriods: Period[] = ["daily", "weekly", "monthly", "yearly"];
+
+  const defaultMinStarsByPeriod: Record<Period, number> = {
+    daily: 60,
+    weekly: 500,
+    monthly: 4000,
+    yearly: 10000,
+  };
+
+  if (!validPeriods.includes(periodInput as Period)) {
+    throw new Error(
+      `Invalid period "${options.period}". Expected one of: daily, weekly, monthly, yearly.`
+    );
+  }
+
+  const period = periodInput as Period;
+
+  const limit = clampToInt(options.limit ?? "30", 1, 100, "limit");
+  const minStars = clampToInt(
+    options.minStars ?? String(defaultMinStarsByPeriod[period]),
+    1,
+    Number.MAX_SAFE_INTEGER,
+    "min-stars"
+  );
+
+  const startDate = getStartDate(period);
+  const client = new GitHubClient();
+
+  const searchOptions: TopicOptionsInternal = {
+    startDate,
+    minStars,
+    language: options.language,
+    limit,
+  };
+
+  const { totalCount, repos } = await searchRepositoriesForTopics(
+    client,
+    searchOptions
+  );
+
+
+  const stats = aggregateTopicStats(repos, limit);
+
+  if (stats.length === 0) {
+    return;
+  }
+
+  printTopicStats(stats, { json: Boolean(options.json) });
+}
+
+function clampToInt(
+  valueStr: string,
+  min: number,
+  max: number,
+  label: string
+): number {
+  const value = Number.parseInt(valueStr, 10);
+  if (Number.isNaN(value)) {
+    throw new Error(`Invalid number for ${label}: "${valueStr}".`);
+  }
+  const clamped = Math.min(Math.max(value, min), max);
+  return clamped;
+}
+

package/src/commands/trending.ts

@@ -0,0 +1,76 @@
+import { GitHubClient } from "../github/client";
+import { searchLifetimeFastGrowingRepositories } from "../github/repoSearch";
+import { Period } from "../utils/dateRange";
+import { printRepositories } from "../utils/output";
+
+interface TrendingCliOptions {
+  period?: string;
+  limit?: string;
+  language?: string;
+  minStars?: string;
+  json?: boolean;
+}
+
+export async function runTrendingCommand(
+  options: TrendingCliOptions
+): Promise<void> {
+  const periodInput = (options.period ?? "daily").toLowerCase();
+  const validPeriods: Period[] = ["daily", "weekly", "monthly", "yearly"];
+
+  const windowDaysByPeriod: Record<Period, number> = {
+    daily: 7,
+    weekly: 28,
+    monthly: 90,
+    yearly: 730,
+  };
+
+  const defaultMinStarsByPeriod: Record<Period, number> = {
+    daily: 60,
+    weekly: 500,
+    monthly: 4000,
+    yearly: 10000,
+  };
+
+  if (!validPeriods.includes(periodInput as Period)) {
+    throw new Error(
+      `Invalid period "${options.period}". Expected one of: daily, weekly, monthly, yearly.`
+    );
+  }
+
+  const period = periodInput as Period;
+
+  const limit = clampToInt(options.limit ?? "50", 1, 100, "limit");
+  const minStars = clampToInt(
+    options.minStars ?? String(defaultMinStarsByPeriod[period]),
+    1,
+    Number.MAX_SAFE_INTEGER,
+    "min-stars"
+  );
+
+  const windowDays = windowDaysByPeriod[period];
+  const client = new GitHubClient();
+
+  const repos = await searchLifetimeFastGrowingRepositories(client, {
+    windowDays,
+    minStars,
+    language: options.language,
+    limit,
+  });
+
+  printRepositories(repos, { json: Boolean(options.json) });
+}
+
+function clampToInt(
+  valueStr: string,
+  min: number,
+  max: number,
+  label: string
+): number {
+  const value = Number.parseInt(valueStr, 10);
+  if (Number.isNaN(value)) {
+    throw new Error(`Invalid number for ${label}: "${valueStr}".`);
+  }
+  const clamped = Math.min(Math.max(value, min), max);
+  return clamped;
+}
+

package/src/config.ts

@@ -0,0 +1,8 @@
+export function getGitHubToken(): string | undefined {
+  return process.env.GITHUB_TOKEN;
+}
+
+export function getUserAgent(): string {
+  return "github-discover-cli/0.1.0";
+}
+

package/src/github/client.ts

@@ -0,0 +1,78 @@
+import { getGitHubToken, getUserAgent } from "../config";
+
+export interface GitHubRequestParams {
+  [key: string]: string | number | boolean | undefined;
+}
+
+export interface GitHubErrorDetails {
+  status: number;
+  message: string;
+  documentation_url?: string;
+}
+
+export class GitHubClient {
+  private readonly baseUrl = "https://api.github.com";
+
+  async request<T>(path: string, params: GitHubRequestParams = {}): Promise<T> {
+    const url = new URL(this.baseUrl + path);
+
+    Object.entries(params).forEach(([key, value]) => {
+      if (value === undefined) return;
+      url.searchParams.set(key, String(value));
+    });
+
+    const headers: Record<string, string> = {
+      "User-Agent": getUserAgent(),
+      Accept: "application/vnd.github+json",
+    };
+
+    const token = getGitHubToken();
+    if (token) {
+      headers.Authorization = `token ${token}`;
+    }
+
+    if (typeof fetch === "undefined") {
+      throw new Error(
+        "Global fetch is not available. Please run this CLI with Node.js 18+ where fetch is built-in."
+      );
+    }
+
+    const response = await fetch(url.toString(), {
+      method: "GET",
+      headers,
+    });
+
+    const text = await response.text();
+    let json: any;
+    try {
+      json = text ? JSON.parse(text) : undefined;
+    } catch {
+      json = undefined;
+    }
+
+    if (!response.ok) {
+      const status = response.status;
+      const message =
+        (json && (json.message as string)) ||
+        `GitHub API request failed with status ${status}`;
+
+      if (status === 401 || status === 403) {
+        const hint = getGitHubToken()
+          ? "Check that your GITHUB_TOKEN is valid and has sufficient scopes."
+          : "You may be hitting anonymous rate limits. Set GITHUB_TOKEN to increase limits.";
+        throw new Error(`${message} (${status}). ${hint}`);
+      }
+
+      if (status === 422) {
+        throw new Error(
+          `${message} (${status}). Please check your search parameters.`
+        );
+      }
+
+      throw new Error(`${message} (${status}).`);
+    }
+
+    return json as T;
+  }
+}
+

package/src/github/repoSearch.ts

@@ -0,0 +1,175 @@
+import { GitHubClient } from "./client";
+
+export interface Repo {
+  name: string;
+  full_name: string;
+  html_url: string;
+  stargazers_count: number;
+  language: string | null;
+  description: string | null;
+  created_at: string;
+  topics?: string[];
+}
+
+interface SearchRepositoriesResponse<T = Repo> {
+  total_count: number;
+  items: T[];
+}
+
+export interface DiscoverOptionsInternal {
+  startDate: string;
+  minStars: number;
+  language?: string;
+  limit: number;
+}
+
+export interface GrowthOptionsInternal {
+  windowDays: number;
+  minStars: number;
+  language?: string;
+  limit: number;
+}
+
+export interface TopicOptionsInternal {
+  startDate: string;
+  minStars: number;
+  language?: string;
+  limit: number;
+}
+
+export async function searchNewPopularRepositories(
+  client: GitHubClient,
+  options: DiscoverOptionsInternal
+): Promise<Repo[]> {
+  const { startDate, minStars, language, limit } = options;
+
+  const qualifiers: string[] = [
+    `created:>=${startDate}`,
+    `stars:>=${minStars}`,
+  ];
+
+  if (language) {
+    qualifiers.push(`language:${language}`);
+  }
+
+  const q = qualifiers.join(" ");
+
+  const perPage = Math.min(Math.max(limit, 1), 100);
+
+  const data = await client.request<SearchRepositoriesResponse>(
+    "/search/repositories",
+    {
+      q,
+      sort: "stars",
+      order: "desc",
+      per_page: perPage,
+    }
+  );
+
+  return data.items.slice(0, limit);
+}
+
+export interface TopicSearchResult {
+  totalCount: number;
+  repos: Repo[];
+}
+
+export async function searchRepositoriesForTopics(
+  client: GitHubClient,
+  options: TopicOptionsInternal
+): Promise<TopicSearchResult> {
+  const { startDate, minStars, language } = options;
+
+  const qualifiers: string[] = [`created:>=${startDate}`, `stars:>=${minStars}`];
+
+  if (language) {
+    qualifiers.push(`language:${language}`);
+  }
+
+  const q = qualifiers.join(" ");
+
+  const data = await client.request<SearchRepositoriesResponse>(
+    "/search/repositories",
+    {
+      q,
+      sort: "stars",
+      order: "desc",
+      per_page: 100,
+    }
+  );
+
+  return {
+    totalCount: data.total_count,
+    repos: data.items,
+  };
+}
+
+export async function searchLifetimeFastGrowingRepositories(
+  client: GitHubClient,
+  options: GrowthOptionsInternal
+): Promise<Repo[]> {
+  const { windowDays, minStars, language, limit } = options;
+
+  const startDate = getDateNDaysAgo(windowDays);
+
+  const qualifiers: string[] = [
+    `created:>=${startDate}`,
+    `stars:>=${minStars}`,
+  ];
+
+  if (language) {
+    qualifiers.push(`language:${language}`);
+  }
+
+  const q = qualifiers.join(" ");
+
+  const data = await client.request<SearchRepositoriesResponse>(
+    "/search/repositories",
+    {
+      q,
+      sort: "stars",
+      order: "desc",
+      per_page: 100,
+    }
+  );
+
+  const items = data.items;
+
+  const MS_PER_DAY = 1000 * 60 * 60 * 24;
+  const SMOOTHING_DAYS = 30;
+  const now = Date.now();
+
+  items.sort((a, b) => {
+    const ageDaysARaw = Math.max(
+      (now - new Date(a.created_at).getTime()) / MS_PER_DAY,
+      1
+    );
+    const ageDaysBRaw = Math.max(
+      (now - new Date(b.created_at).getTime()) / MS_PER_DAY,
+      1
+    );
+
+    const ageDaysAEff = ageDaysARaw + SMOOTHING_DAYS;
+    const ageDaysBEff = ageDaysBRaw + SMOOTHING_DAYS;
+
+    const growthA = a.stargazers_count / ageDaysAEff;
+    const growthB = b.stargazers_count / ageDaysBEff;
+
+    return growthB - growthA;
+  });
+
+  return items.slice(0, limit);
+}
+
+function getDateNDaysAgo(days: number): string {
+  const now = new Date();
+  const start = new Date(now);
+  start.setDate(now.getDate() - days);
+
+  const year = start.getFullYear();
+  const month = String(start.getMonth() + 1).padStart(2, "0");
+  const day = String(start.getDate()).padStart(2, "0");
+
+  return `${year}-${month}-${day}`;
+}
+

package/src/github/topicStats.ts

@@ -0,0 +1,56 @@
+import type { Repo } from "./repoSearch";
+
+export interface TopicStat {
+  topic: string;
+  score: number;
+  repoCount: number;
+  starSum: number;
+}
+
+export function aggregateTopicStats(
+  repos: Repo[],
+  limit: number
+): TopicStat[] {
+  const topicMap = new Map<string, { repoCount: number; starSum: number }>();
+
+  for (const repo of repos) {
+    if (!repo.topics || repo.topics.length === 0) continue;
+
+    const uniqueTopics = new Set(
+      repo.topics
+        .map((t) => t.trim())
+        .filter((t) => t.length > 0)
+    );
+
+    for (const topic of uniqueTopics) {
+      const current = topicMap.get(topic) ?? { repoCount: 0, starSum: 0 };
+      current.repoCount += 1;
+      current.starSum += repo.stargazers_count;
+      topicMap.set(topic, current);
+    }
+  }
+
+  const stats: TopicStat[] = [];
+
+  for (const [topic, { repoCount, starSum }] of topicMap.entries()) {
+    const score =
+      repoCount * Math.log10(Math.max(starSum + 10, 1)); // 防止 log10(0)
+
+    stats.push({
+      topic,
+      score,
+      repoCount,
+      starSum,
+    });
+  }
+
+  stats.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score;
+    if (b.repoCount !== a.repoCount) return b.repoCount - a.repoCount;
+    return a.topic.localeCompare(b.topic);
+  });
+
+  const safeLimit = Math.max(1, Math.min(limit, stats.length));
+  return stats.slice(0, safeLimit);
+}
+

package/src/utils/dateRange.ts

@@ -0,0 +1,30 @@
+export type Period = "daily" | "weekly" | "monthly" | "yearly";
+
+export function getStartDate(period: Period): string {
+  const now = new Date();
+  const start = new Date(now);
+
+  switch (period) {
+    case "daily":
+      start.setDate(now.getDate() - 2);
+      break;
+    case "weekly":
+      start.setDate(now.getDate() - 7);
+      break;
+    case "monthly":
+      start.setDate(now.getDate() - 30);
+      break;
+    case "yearly":
+      start.setDate(now.getDate() - 365);
+      break;
+    default:
+      start.setDate(now.getDate() - 2);
+  }
+
+  const year = start.getFullYear();
+  const month = String(start.getMonth() + 1).padStart(2, "0");
+  const day = String(start.getDate()).padStart(2, "0");
+
+  return `${year}-${month}-${day}`;
+}
+

package/src/utils/output.ts

@@ -0,0 +1,141 @@
+import type { Repo } from "../github/repoSearch";
+import type { TopicStat } from "../github/topicStats";
+
+export interface OutputOptions {
+  json: boolean;
+}
+
+export function printRepositories(
+  repos: Repo[],
+  options: OutputOptions
+): void {
+  const filteredRepos = repos.filter((r) => {
+    const langRaw = r.language ?? "";
+    const lang = langRaw.trim();
+    if (!lang || lang === "-") {
+      return false;
+    }
+    const lower = lang.toLowerCase();
+    return lower !== "html" && lower !== "shell";
+  });
+
+  if (options.json) {
+    const minimal = filteredRepos.map((r) => ({
+      name: r.name,
+      full_name: r.full_name,
+      html_url: r.html_url,
+      stars: r.stargazers_count,
+      language: r.language,
+      created_at: r.created_at,
+      description: r.description,
+    }));
+    console.log(JSON.stringify(minimal, null, 2));
+    return;
+  }
+
+  if (filteredRepos.length === 0) {
+    return;
+  }
+
+  const truncate = (text: string, maxLength: number): string =>
+    text.length <= maxLength ? text : `${text.slice(0, maxLength - 1)}…`;
+
+  const rows = filteredRepos.map((r) => {
+    const lang = r.language ?? "-";
+    const created = r.created_at.slice(0, 10);
+    const description = r.description ? truncate(r.description, 150) : "-";
+    return {
+      name: r.full_name,
+      stars: String(r.stargazers_count),
+      lang,
+      created,
+      url: r.html_url,
+      description,
+    };
+  });
+
+  const headers = ["Name", "Stars", "Lang", "Created", "URL", "Description"];
+
+  const colWidths = headers.map((header, index) =>
+    Math.max(
+      header.length,
+      ...rows.map((row) => Object.values(row)[index].length)
+    )
+  );
+
+  const formatRow = (cols: string[]): string =>
+    cols
+      .map((col, i) => col.padEnd(colWidths[i], " "))
+      .join(" | ");
+
+  console.log(formatRow(headers));
+  console.log(
+    formatRow(
+      headers.map((h, i) => "".padEnd(colWidths[i], "-"))
+    )
+  );
+
+  for (const row of rows) {
+    console.log(
+      formatRow([
+        row.name,
+        row.stars,
+        row.lang,
+        row.created,
+        row.url,
+        row.description,
+      ])
+    );
+  }
+}
+
+export function printTopicStats(
+  stats: TopicStat[],
+  options: OutputOptions
+): void {
+  if (options.json) {
+    const minimal = stats.map((s) => ({
+      topic: s.topic,
+    }));
+    console.log(JSON.stringify(minimal, null, 2));
+    return;
+  }
+
+  if (stats.length === 0) {
+    return;
+  }
+
+  const rows = stats.map((s, index) => ({
+    rank: String(index + 1),
+    topic: s.topic,
+  }));
+
+  const headers = ["Rank", "Topic"];
+
+  const colWidths = headers.map((header, index) =>
+    Math.max(
+      header.length,
+      ...rows.map((row) => Object.values(row)[index].length)
+    )
+  );
+
+  const formatRow = (cols: string[]): string =>
+    cols
+      .map((col, i) => col.padEnd(colWidths[i], " "))
+      .join(" | ");
+
+  console.log(formatRow(headers));
+  console.log(
+    formatRow(
+      headers.map((h, i) => "".padEnd(colWidths[i], "-"))
+    )
+  );
+
+  for (const row of rows) {
+    console.log(
+      formatRow([row.rank, row.topic])
+    );
+  }
+}
+
+

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "CommonJS",
+    "moduleResolution": "Node",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "lib": ["ES2020", "DOM"]
+  },
+  "include": ["src"]
+}
+