@urmzd/github-insights 2.0.0

package/src/templates.test.ts

@@ -0,0 +1,412 @@
+import { describe, expect, it } from "vitest";
+import { makeContributionData, makeUserProfile } from "./__fixtures__/repos.js";
+import {
+  buildSocialBadges,
+  extractFirstName,
+  getTemplate,
+  shieldsBadgeLabel,
+} from "./templates.js";
+import type { TemplateContext } from "./types.js";
+
+const makeContext = (
+  overrides: Partial<TemplateContext> = {},
+): TemplateContext => ({
+  username: "urmzd",
+  name: "Urmzd Maharramoff",
+  firstName: "Urmzd",
+  pronunciation: undefined,
+  title: "Software Engineer",
+  bio: "Building tools",
+  preamble: "A software developer in Austin, TX.",
+  svgs: [{ label: "GitHub Metrics", path: "metrics/index.svg" }],
+  sectionSvgs: {
+    pulse: "metrics/metrics-pulse.svg",
+    calendar: "metrics/metrics-calendar.svg",
+    expertise: "metrics/metrics-expertise.svg",
+  },
+  profile: makeUserProfile(),
+  activeProjects: [
+    {
+      name: "resume-generator",
+      url: "https://github.com/urmzd/resume-generator",
+      description: "CLI tool for professional resumes",
+      stars: 42,
+      category: "Applications",
+    },
+  ],
+  maintainedProjects: [
+    {
+      name: "flappy-bird",
+      url: "https://github.com/urmzd/flappy-bird",
+      description: "JavaFX game with design patterns",
+      stars: 8,
+      category: "Research & Experiments",
+    },
+  ],
+  inactiveProjects: [],
+  allProjects: [],
+  categorizedProjects: {
+    Applications: [
+      {
+        name: "resume-generator",
+        url: "https://github.com/urmzd/resume-generator",
+        description: "CLI tool for professional resumes",
+        stars: 42,
+        category: "Applications",
+      },
+    ],
+    "Research & Experiments": [
+      {
+        name: "flappy-bird",
+        url: "https://github.com/urmzd/flappy-bird",
+        description: "JavaFX game with design patterns",
+        stars: 8,
+        category: "Research & Experiments",
+      },
+    ],
+  },
+  languages: [
+    { name: "TypeScript", value: 100, percent: "60.0", color: "#3178c6" },
+    { name: "Rust", value: 50, percent: "30.0", color: "#dea584" },
+  ],
+  techHighlights: [],
+  contributionData: makeContributionData(),
+  socialBadges:
+    "[![urmzd.dev](https://img.shields.io/badge/urmzd.dev-4285F4?style=flat&logo=google-chrome&logoColor=white)](https://urmzd.dev)",
+  svgDir: "metrics",
+  ...overrides,
+});
+
+// ── extractFirstName ───────────────────────────────────────────────────────
+
+describe("extractFirstName", () => {
+  it("returns first word of full name", () => {
+    expect(extractFirstName("Urmzd Maharramoff")).toBe("Urmzd");
+  });
+
+  it("returns whole name if single word", () => {
+    expect(extractFirstName("Urmzd")).toBe("Urmzd");
+  });
+
+  it("handles extra whitespace", () => {
+    expect(extractFirstName("  Urmzd  Maharramoff  ")).toBe("Urmzd");
+  });
+});
+
+// ── buildSocialBadges ──────────────────────────────────────────────────────
+
+describe("buildSocialBadges", () => {
+  it("builds website badge with hostname", () => {
+    const profile = makeUserProfile({
+      twitterUsername: null,
+      socialAccounts: [],
+    });
+    const badges = buildSocialBadges(profile);
+    expect(badges).toContain("urmzd.dev");
+    expect(badges).toContain("https://urmzd.dev");
+    expect(badges).not.toContain("Website");
+  });
+
+  it("builds twitter badge with @username", () => {
+    const profile = makeUserProfile({ websiteUrl: null, socialAccounts: [] });
+    const badges = buildSocialBadges(profile);
+    expect(badges).toContain("@urmzd");
+    expect(badges).toContain("https://x.com/urmzd");
+  });
+
+  it("builds LinkedIn badge with handle from URL", () => {
+    const profile = makeUserProfile({
+      websiteUrl: null,
+      twitterUsername: null,
+    });
+    const badges = buildSocialBadges(profile);
+    expect(badges).toContain("[![urmzd]");
+    expect(badges).toContain("https://linkedin.com/in/urmzd");
+  });
+
+  it("builds Mastodon badge with @user from URL", () => {
+    const profile = makeUserProfile({
+      websiteUrl: null,
+      twitterUsername: null,
+      socialAccounts: [
+        { provider: "MASTODON", url: "https://mastodon.social/@urmzd" },
+      ],
+    });
+    const badges = buildSocialBadges(profile);
+    expect(badges).toContain("@urmzd");
+    expect(badges).toContain("mastodon.social/@urmzd");
+  });
+
+  it("builds YouTube badge with channel name from URL", () => {
+    const profile = makeUserProfile({
+      websiteUrl: null,
+      twitterUsername: null,
+      socialAccounts: [
+        { provider: "YOUTUBE", url: "https://youtube.com/@mychannel" },
+      ],
+    });
+    const badges = buildSocialBadges(profile);
+    expect(badges).toContain("mychannel");
+    expect(badges).toContain("youtube.com/@mychannel");
+  });
+
+  it("returns empty string when no social info", () => {
+    const profile = makeUserProfile({
+      websiteUrl: null,
+      twitterUsername: null,
+      socialAccounts: [],
+    });
+    expect(buildSocialBadges(profile)).toBe("");
+  });
+});
+
+// ── shieldsBadgeLabel ────────────────────────────────────────────────────────
+
+describe("shieldsBadgeLabel", () => {
+  it("escapes hyphens", () => {
+    expect(shieldsBadgeLabel("my-site")).toBe("my--site");
+  });
+
+  it("escapes underscores", () => {
+    expect(shieldsBadgeLabel("my_name")).toBe("my__name");
+  });
+
+  it("leaves plain text unchanged", () => {
+    expect(shieldsBadgeLabel("urmzd.dev")).toBe("urmzd.dev");
+  });
+});
+
+// ── getTemplate ────────────────────────────────────────────────────────────
+
+describe("getTemplate", () => {
+  it("returns a function for classic", () => {
+    expect(typeof getTemplate("classic")).toBe("function");
+  });
+
+  it("returns a function for modern", () => {
+    expect(typeof getTemplate("modern")).toBe("function");
+  });
+
+  it("returns a function for minimal", () => {
+    expect(typeof getTemplate("minimal")).toBe("function");
+  });
+
+  it("returns a function for ecosystem", () => {
+    expect(typeof getTemplate("ecosystem")).toBe("function");
+  });
+});
+
+// ── Classic template ───────────────────────────────────────────────────────
+
+describe("classicTemplate", () => {
+  it("includes name heading", () => {
+    const output = getTemplate("classic")(makeContext());
+    expect(output).toContain("# Urmzd Maharramoff");
+  });
+
+  it("includes title blockquote", () => {
+    const output = getTemplate("classic")(makeContext());
+    expect(output).toContain("> Software Engineer");
+  });
+
+  it("includes preamble content", () => {
+    const output = getTemplate("classic")(makeContext());
+    expect(output).toContain("A software developer in Austin, TX.");
+  });
+
+  it("includes SVG embeds", () => {
+    const output = getTemplate("classic")(makeContext());
+    expect(output).toContain("![GitHub Metrics](metrics/index.svg)");
+  });
+
+  it("includes social badges", () => {
+    const output = getTemplate("classic")(makeContext());
+    expect(output).toContain("img.shields.io");
+  });
+
+  it("includes bio footer", () => {
+    const output = getTemplate("classic")(makeContext());
+    expect(output).toContain("<sub>Building tools</sub>");
+  });
+
+  it("includes attribution", () => {
+    const output = getTemplate("classic")(makeContext());
+    expect(output).toContain("@urmzd/github-insights");
+  });
+
+  it("includes pronunciation when provided", () => {
+    const output = getTemplate("classic")(
+      makeContext({ pronunciation: "/ˈʊrm.zəd/" }),
+    );
+    expect(output).toContain("/ˈʊrm.zəd/");
+  });
+
+  it("ends with trailing newline", () => {
+    const output = getTemplate("classic")(makeContext());
+    expect(output.endsWith("\n")).toBe(true);
+  });
+});
+
+// ── Modern template ────────────────────────────────────────────────────────
+
+describe("modernTemplate", () => {
+  it("includes wave greeting with first name", () => {
+    const output = getTemplate("modern")(makeContext());
+    expect(output).toContain("# Hi, I'm Urmzd");
+  });
+
+  it("includes preamble", () => {
+    const output = getTemplate("modern")(makeContext());
+    expect(output).toContain("A software developer in Austin, TX.");
+  });
+
+  it("includes active projects section with h3 headings", () => {
+    const output = getTemplate("modern")(makeContext());
+    expect(output).toContain("## Active Projects");
+    expect(output).toContain(
+      "### [resume-generator](https://github.com/urmzd/resume-generator)",
+    );
+    expect(output).toContain("\u2605 42");
+  });
+
+  it("includes maintained projects section with h3 headings", () => {
+    const output = getTemplate("modern")(makeContext());
+    expect(output).toContain("## Maintained Projects");
+    expect(output).toContain(
+      "### [flappy-bird](https://github.com/urmzd/flappy-bird)",
+    );
+  });
+
+  it("includes AI summary in project section when available", () => {
+    const output = getTemplate("modern")(
+      makeContext({
+        activeProjects: [
+          {
+            name: "my-tool",
+            url: "https://github.com/urmzd/my-tool",
+            description: "A CLI tool",
+            stars: 5,
+            summary: "AI-generated summary of the project.",
+          },
+        ],
+      }),
+    );
+    expect(output).toContain("AI-generated summary of the project.");
+  });
+
+  it("includes GitHub Stats section with pulse and calendar", () => {
+    const output = getTemplate("modern")(makeContext());
+    expect(output).toContain("## GitHub Stats");
+    expect(output).toContain("metrics/metrics-pulse.svg");
+    expect(output).toContain("metrics/metrics-calendar.svg");
+  });
+
+  it("includes expertise section", () => {
+    const output = getTemplate("modern")(makeContext());
+    expect(output).toContain("## Other Areas of Interest");
+    expect(output).toContain("metrics/metrics-expertise.svg");
+  });
+
+  it("includes social badges", () => {
+    const output = getTemplate("modern")(makeContext());
+    expect(output).toContain("img.shields.io");
+  });
+
+  it("ends with trailing newline", () => {
+    const output = getTemplate("modern")(makeContext());
+    expect(output.endsWith("\n")).toBe(true);
+  });
+});
+
+// ── Minimal template ───────────────────────────────────────────────────────
+
+describe("minimalTemplate", () => {
+  it("uses first name as heading", () => {
+    const output = getTemplate("minimal")(makeContext());
+    expect(output).toContain("# Urmzd");
+  });
+
+  it("includes preamble", () => {
+    const output = getTemplate("minimal")(makeContext());
+    expect(output).toContain("A software developer in Austin, TX.");
+  });
+
+  it("includes SVG embeds", () => {
+    const output = getTemplate("minimal")(makeContext());
+    expect(output).toContain("![GitHub Metrics](metrics/index.svg)");
+  });
+
+  it("includes social badges", () => {
+    const output = getTemplate("minimal")(makeContext());
+    expect(output).toContain("img.shields.io");
+  });
+
+  it("includes attribution", () => {
+    const output = getTemplate("minimal")(makeContext());
+    expect(output).toContain("@urmzd/github-insights");
+  });
+
+  it("ends with trailing newline", () => {
+    const output = getTemplate("minimal")(makeContext());
+    expect(output.endsWith("\n")).toBe(true);
+  });
+});
+
+// ── Ecosystem template ──────────────────────────────────────────────────
+
+describe("ecosystemTemplate", () => {
+  it("includes wave greeting with first name", () => {
+    const output = getTemplate("ecosystem")(makeContext());
+    expect(output).toContain("# Hi, I'm Urmzd");
+  });
+
+  it("includes preamble", () => {
+    const output = getTemplate("ecosystem")(makeContext());
+    expect(output).toContain("A software developer in Austin, TX.");
+  });
+
+  it("renders projects as categorized tables", () => {
+    const output = getTemplate("ecosystem")(makeContext());
+    expect(output).toContain("### Applications");
+    expect(output).toContain("| Project | Description |");
+    expect(output).toContain(
+      "| [resume-generator](https://github.com/urmzd/resume-generator) |",
+    );
+  });
+
+  it("renders Research & Experiments category", () => {
+    const output = getTemplate("ecosystem")(makeContext());
+    expect(output).toContain("### Research & Experiments");
+    expect(output).toContain(
+      "| [flappy-bird](https://github.com/urmzd/flappy-bird) |",
+    );
+  });
+
+  it("includes GitHub Stats section", () => {
+    const output = getTemplate("ecosystem")(makeContext());
+    expect(output).toContain("## GitHub Stats");
+    expect(output).toContain("metrics/metrics-pulse.svg");
+    expect(output).toContain("metrics/metrics-calendar.svg");
+  });
+
+  it("includes expertise section", () => {
+    const output = getTemplate("ecosystem")(makeContext());
+    expect(output).toContain("## Other Areas of Interest");
+    expect(output).toContain("metrics/metrics-expertise.svg");
+  });
+
+  it("includes social badges", () => {
+    const output = getTemplate("ecosystem")(makeContext());
+    expect(output).toContain("img.shields.io");
+  });
+
+  it("includes attribution", () => {
+    const output = getTemplate("ecosystem")(makeContext());
+    expect(output).toContain("@urmzd/github-insights");
+  });
+
+  it("ends with trailing newline", () => {
+    const output = getTemplate("ecosystem")(makeContext());
+    expect(output.endsWith("\n")).toBe(true);
+  });
+});

package/src/templates.ts

@@ -0,0 +1,296 @@
+import type {
+  ProjectItem,
+  TemplateContext,
+  TemplateFunction,
+  TemplateName,
+  UserProfile,
+} from "./types.js";
+
+// ── Helpers ────────────────────────────────────────────────────────────────
+
+function attribution(): string {
+  const now = new Date().toISOString().split("T")[0];
+  return `<sub>Last generated on ${now} using [@urmzd/github-insights](https://github.com/urmzd/github-insights)</sub>`;
+}
+
+export function extractFirstName(fullName: string): string {
+  return fullName.trim().split(/\s+/)[0] || fullName;
+}
+
+/** Escape special characters for shields.io badge labels (`-` → `--`, `_` → `__`). */
+export function shieldsBadgeLabel(text: string): string {
+  return text.replace(/-/g, "--").replace(/_/g, "__");
+}
+
+export function buildSocialBadges(profile: UserProfile): string {
+  const badges: string[] = [];
+
+  if (profile.websiteUrl) {
+    let label: string;
+    try {
+      label = new URL(profile.websiteUrl).hostname;
+    } catch {
+      label = "Website";
+    }
+    badges.push(
+      `[![${label}](https://img.shields.io/badge/${shieldsBadgeLabel(label)}-4285F4?style=flat&logo=google-chrome&logoColor=white)](${profile.websiteUrl})`,
+    );
+  }
+  if (profile.twitterUsername) {
+    const label = `@${profile.twitterUsername}`;
+    badges.push(
+      `[![${label}](https://img.shields.io/badge/${shieldsBadgeLabel(label)}-000000?style=flat&logo=x&logoColor=white)](https://x.com/${profile.twitterUsername})`,
+    );
+  }
+  for (const account of profile.socialAccounts) {
+    const provider = account.provider.toLowerCase();
+    if (provider === "linkedin") {
+      const match = account.url.match(/\/in\/([^/?#]+)/);
+      const label = match?.[1] || "LinkedIn";
+      badges.push(
+        `[![${label}](https://img.shields.io/badge/${shieldsBadgeLabel(label)}-0A66C2?style=flat&logo=linkedin&logoColor=white)](${account.url})`,
+      );
+    } else if (provider === "mastodon") {
+      const match = account.url.match(/\/@([^/?#]+)/);
+      const label = match ? `@${match[1]}` : "Mastodon";
+      badges.push(
+        `[![${label}](https://img.shields.io/badge/${shieldsBadgeLabel(label)}-6364FF?style=flat&logo=mastodon&logoColor=white)](${account.url})`,
+      );
+    } else if (provider === "youtube") {
+      const match = account.url.match(/\/(?:@|c(?:hannel)?\/|user\/)([^/?#]+)/);
+      const label = match?.[1] || "YouTube";
+      badges.push(
+        `[![${label}](https://img.shields.io/badge/${shieldsBadgeLabel(label)}-FF0000?style=flat&logo=youtube&logoColor=white)](${account.url})`,
+      );
+    }
+  }
+
+  return badges.join(" ");
+}
+
+// ── Project section helper (modern template) ─────────────────────────────
+
+function renderProjectSection(title: string, projects: ProjectItem[]): string {
+  if (projects.length === 0) return "";
+
+  const items = projects
+    .map((p) => {
+      const desc = p.summary || p.description || "No description";
+      const meta: string[] = [];
+      if (p.stars > 0) meta.push(`\u2605 ${p.stars}`);
+      if (p.languages?.length) meta.push(p.languages.slice(0, 3).join(", "));
+      const metaLine = meta.length > 0 ? `${meta.join(" \u00b7 ")}` : "";
+      return `### [${p.name}](${p.url})\n${desc}${metaLine ? `\n${metaLine}` : ""}`;
+    })
+    .join("\n\n");
+
+  return `## ${title}\n\n${items}`;
+}
+
+// ── Project table helper (ecosystem template) ────────────────────────────
+
+function renderProjectTable(title: string, projects: ProjectItem[]): string {
+  if (projects.length === 0) return "";
+
+  const header = `| Project | Description |\n|---------|-------------|`;
+  const rows = projects
+    .map((p) => {
+      const desc = p.summary || p.description || "No description";
+      const safeDesc = desc.replace(/\|/g, "\\|").replace(/\n/g, " ");
+      return `| [${p.name}](${p.url}) | ${safeDesc} |`;
+    })
+    .join("\n");
+
+  return `### ${title}\n\n${header}\n${rows}`;
+}
+
+// ── Classic template ───────────────────────────────────────────────────────
+
+function classicTemplate(ctx: TemplateContext): string {
+  const parts: string[] = [];
+
+  if (ctx.pronunciation) {
+    parts.push(`# ${ctx.name} <sub><i>(${ctx.pronunciation})</i></sub>`);
+  } else {
+    parts.push(`# ${ctx.name}`);
+  }
+
+  if (ctx.title) {
+    parts.push(`> ${ctx.title}`);
+  }
+
+  if (ctx.preamble) {
+    parts.push(ctx.preamble);
+  }
+
+  if (ctx.socialBadges) {
+    parts.push(ctx.socialBadges);
+  }
+
+  for (const svg of ctx.svgs) {
+    parts.push(`![${svg.label}](${svg.path})`);
+  }
+
+  if (ctx.bio) {
+    parts.push(`---\n\n<sub>${ctx.bio}</sub>`);
+  }
+
+  parts.push(attribution());
+
+  return `${parts.join("\n\n")}\n`;
+}
+
+// ── Modern template ────────────────────────────────────────────────────────
+
+function modernTemplate(ctx: TemplateContext): string {
+  const parts: string[] = [];
+
+  parts.push(`# Hi, I'm ${ctx.firstName} 👋`);
+
+  if (ctx.preamble) {
+    parts.push(ctx.preamble);
+  }
+
+  if (ctx.socialBadges) {
+    parts.push(ctx.socialBadges);
+  }
+
+  const activeSection = renderProjectSection(
+    "Active Projects",
+    ctx.activeProjects,
+  );
+  if (activeSection) parts.push(activeSection);
+
+  const maintainedSection = renderProjectSection(
+    "Maintained Projects",
+    ctx.maintainedProjects,
+  );
+  if (maintainedSection) parts.push(maintainedSection);
+
+  const inactiveSection = renderProjectSection(
+    "Inactive Projects",
+    ctx.inactiveProjects,
+  );
+  if (inactiveSection) parts.push(inactiveSection);
+
+  // GitHub Stats section: pulse + calendar
+  const statsImages: string[] = [];
+  if (ctx.sectionSvgs.pulse) {
+    statsImages.push(`![At a Glance](${ctx.sectionSvgs.pulse})`);
+  }
+  if (ctx.sectionSvgs.calendar) {
+    statsImages.push(`![Contributions](${ctx.sectionSvgs.calendar})`);
+  }
+  if (statsImages.length > 0) {
+    parts.push(`## GitHub Stats\n\n${statsImages.join("\n")}`);
+  }
+
+  // Other areas of interest: expertise
+  if (ctx.sectionSvgs.expertise) {
+    parts.push(
+      `## Other Areas of Interest\n\n![Expertise](${ctx.sectionSvgs.expertise})`,
+    );
+  }
+
+  parts.push(attribution());
+
+  return `${parts.join("\n\n")}\n`;
+}
+
+// ── Minimal template ───────────────────────────────────────────────────────
+
+function minimalTemplate(ctx: TemplateContext): string {
+  const parts: string[] = [];
+
+  parts.push(`# ${ctx.firstName}`);
+
+  if (ctx.preamble) {
+    parts.push(ctx.preamble);
+  }
+
+  if (ctx.socialBadges) {
+    parts.push(ctx.socialBadges);
+  }
+
+  for (const svg of ctx.svgs) {
+    parts.push(`![${svg.label}](${svg.path})`);
+  }
+
+  parts.push(attribution());
+
+  return `${parts.join("\n\n")}\n`;
+}
+
+// ── Ecosystem template ────────────────────────────────────────────────────
+
+const CATEGORY_ORDER = [
+  "Developer Tools",
+  "SDKs",
+  "Applications",
+  "Research & Experiments",
+];
+
+function ecosystemTemplate(ctx: TemplateContext): string {
+  const parts: string[] = [];
+
+  parts.push(`# Hi, I'm ${ctx.firstName} 👋`);
+
+  if (ctx.preamble) {
+    parts.push(ctx.preamble);
+  }
+
+  if (ctx.socialBadges) {
+    parts.push(ctx.socialBadges);
+  }
+
+  // Render project tables grouped by category
+  for (const category of CATEGORY_ORDER) {
+    const projects = ctx.categorizedProjects[category];
+    if (projects && projects.length > 0) {
+      parts.push(renderProjectTable(category, projects));
+    }
+  }
+
+  // Render any uncategorized projects that don't match known categories
+  for (const [category, projects] of Object.entries(ctx.categorizedProjects)) {
+    if (!CATEGORY_ORDER.includes(category) && projects.length > 0) {
+      parts.push(renderProjectTable(category, projects));
+    }
+  }
+
+  // GitHub Stats section: pulse + calendar
+  const statsImages: string[] = [];
+  if (ctx.sectionSvgs.pulse) {
+    statsImages.push(`![At a Glance](${ctx.sectionSvgs.pulse})`);
+  }
+  if (ctx.sectionSvgs.calendar) {
+    statsImages.push(`![Contributions](${ctx.sectionSvgs.calendar})`);
+  }
+  if (statsImages.length > 0) {
+    parts.push(`## GitHub Stats\n\n${statsImages.join("\n")}`);
+  }
+
+  // Other areas of interest: expertise
+  if (ctx.sectionSvgs.expertise) {
+    parts.push(
+      `## Other Areas of Interest\n\n![Expertise](${ctx.sectionSvgs.expertise})`,
+    );
+  }
+
+  parts.push(attribution());
+
+  return `${parts.join("\n\n")}\n`;
+}
+
+// ── Registry ───────────────────────────────────────────────────────────────
+
+const TEMPLATES: Record<TemplateName, TemplateFunction> = {
+  classic: classicTemplate,
+  modern: modernTemplate,
+  minimal: minimalTemplate,
+  ecosystem: ecosystemTemplate,
+};
+
+export function getTemplate(name: TemplateName): TemplateFunction {
+  return TEMPLATES[name] || TEMPLATES.classic;
+}