@urmzd/github-insights 2.2.0 → 2.4.0

package/src/templates.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "vitest";
 import { makeContributionData, makeUserProfile } from "./__fixtures__/repos.js";
 import {
   buildSocialBadges,
+  descriptiveAlt,
   extractFirstName,
   getTemplate,
   shieldsBadgeLabel,
@@ -219,9 +220,11 @@ describe("classicTemplate", () => {
     expect(output).toContain("A software developer in Austin, TX.");
   });
 
-  it("includes SVG embeds", () => {
+  it("includes SVG embeds with descriptive alt text", () => {
     const output = getTemplate("classic")(makeContext());
-    expect(output).toContain("![GitHub Metrics](assets/insights/index.svg)");
+    expect(output).toContain(
+      `![${descriptiveAlt("GitHub Metrics", "Urmzd Maharramoff")}](assets/insights/index.svg)`,
+    );
   });
 
   it("includes social badges", () => {
@@ -246,7 +249,7 @@ describe("classicTemplate", () => {
     expect(output).toContain("/ˈʊrm.zəd/");
   });
 
-  it("includes archived section for archived projects", () => {
+  it("omits archived section", () => {
     const output = getTemplate("classic")(
       makeContext({
         archivedProjects: [
@@ -259,12 +262,6 @@ describe("classicTemplate", () => {
         ],
       }),
     );
-    expect(output).toContain("## Archived");
-    expect(output).toContain("[old-project]");
-  });
-
-  it("omits archived section when no archived projects", () => {
-    const output = getTemplate("classic")(makeContext());
     expect(output).not.toContain("## Archived");
   });
 
@@ -293,7 +290,7 @@ describe("modernTemplate", () => {
     expect(output).toContain(
       "### [resume-generator](https://github.com/urmzd/resume-generator)",
     );
-    expect(output).toContain("\u2605 42");
+    expect(output).toContain("Stars: 42");
   });
 
   it("includes maintained projects section with h3 headings", () => {
@@ -334,7 +331,7 @@ describe("modernTemplate", () => {
     expect(output).toContain("assets/insights/metrics-constellation.svg");
   });
 
-  it("includes archived section separate from active/maintained", () => {
+  it("omits archived section", () => {
     const output = getTemplate("modern")(
       makeContext({
         archivedProjects: [
@@ -347,8 +344,7 @@ describe("modernTemplate", () => {
         ],
       }),
     );
-    expect(output).toContain("## Archived");
-    expect(output).toContain("[legacy-lib]");
+    expect(output).not.toContain("## Archived");
   });
 
   it("includes social badges", () => {
@@ -375,9 +371,11 @@ describe("minimalTemplate", () => {
     expect(output).toContain("A software developer in Austin, TX.");
   });
 
-  it("includes SVG embeds", () => {
+  it("includes SVG embeds with descriptive alt text", () => {
     const output = getTemplate("minimal")(makeContext());
-    expect(output).toContain("![GitHub Metrics](assets/insights/index.svg)");
+    expect(output).toContain(
+      `![${descriptiveAlt("GitHub Metrics", "Urmzd Maharramoff")}](assets/insights/index.svg)`,
+    );
   });
 
   it("includes social badges", () => {
@@ -390,7 +388,7 @@ describe("minimalTemplate", () => {
     expect(output).toContain("@urmzd/github-insights");
   });
 
-  it("includes archived section for archived projects", () => {
+  it("omits archived section", () => {
     const output = getTemplate("minimal")(
       makeContext({
         archivedProjects: [
@@ -403,8 +401,7 @@ describe("minimalTemplate", () => {
         ],
       }),
     );
-    expect(output).toContain("## Archived");
-    expect(output).toContain("[old-util]");
+    expect(output).not.toContain("## Archived");
   });
 
   it("ends with trailing newline", () => {
@@ -466,7 +463,7 @@ describe("ecosystemTemplate", () => {
     expect(output).toContain("@urmzd/github-insights");
   });
 
-  it("separates archived projects from category tables", () => {
+  it("omits archived section", () => {
     const output = getTemplate("ecosystem")(
       makeContext({
         archivedProjects: [
@@ -478,31 +475,9 @@ describe("ecosystemTemplate", () => {
             category: "Applications",
           },
         ],
-        categorizedProjects: {
-          Applications: [
-            {
-              name: "resume-generator",
-              url: "https://github.com/urmzd/resume-generator",
-              description: "CLI tool for professional resumes",
-              stars: 42,
-              category: "Applications",
-            },
-            {
-              name: "old-app",
-              url: "https://github.com/urmzd/old-app",
-              description: "A retired application",
-              stars: 3,
-              category: "Applications",
-            },
-          ],
-        },
       }),
     );
-    expect(output).toContain("### Archived");
-    expect(output).toContain("[old-app]");
-    // old-app should NOT appear in the Applications table
-    const appSection = output.split("### Applications")[1].split("###")[0];
-    expect(appSection).not.toContain("old-app");
+    expect(output).not.toContain("### Archived");
   });
 
   it("ends with trailing newline", () => {

package/src/templates.ts

@@ -10,7 +10,51 @@ import type {
 
 function attribution(templateName: string): 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) · Template: \`${templateName}\`</sub>`;
+  return `<!-- section: footer -->\n<sub>Last generated on ${now} using [@urmzd/github-insights](https://github.com/urmzd/github-insights) · Template: \`${templateName}\`</sub>`;
+}
+
+function frontmatter(ctx: TemplateContext): string {
+  const langs = ctx.languages.slice(0, 10).map((l) => l.name);
+  const lines = [
+    "<!-- ai-metadata",
+    `type: github-profile`,
+    `name: ${ctx.name}`,
+    `username: ${ctx.username}`,
+    ...(ctx.title ? [`title: ${ctx.title}`] : []),
+    `languages: [${langs.join(", ")}]`,
+    `profile: https://github.com/${ctx.username}`,
+    "-->",
+  ];
+  return lines.join("\n");
+}
+
+const ALT_TEXT_MAP: Record<string, string> = {
+  "GitHub Metrics":
+    "Combined visualization of language velocity, contribution rhythm, project constellation, and open source impact for {name}",
+  "Language Velocity":
+    "Streamgraph of {name}'s programming language usage over the past year",
+  "Contribution Rhythm":
+    "Radar chart of {name}'s contribution patterns by day of week",
+  "Project Constellation":
+    "Map of {name}'s projects positioned by language ecosystem and complexity",
+  "Impact Trail":
+    "Bar chart of {name}'s open source contributions by repository star count",
+};
+
+export function descriptiveAlt(label: string, name: string): string {
+  const template = ALT_TEXT_MAP[label];
+  if (template) return template.replace(/\{name\}/g, name);
+  return label;
+}
+
+function inlineMetadata(ctx: TemplateContext): string {
+  const parts: string[] = [];
+  if (ctx.title) parts.push(`**Role:** ${ctx.title}`);
+  const topLangs = ctx.languages.slice(0, 5).map((l) => l.name);
+  if (topLangs.length > 0)
+    parts.push(`**Top Languages:** ${topLangs.join(", ")}`);
+  if (parts.length === 0) return "";
+  return parts.join(" | ");
 }
 
 export function extractFirstName(fullName: string): string {
@@ -77,8 +121,9 @@ function renderProjectSection(title: string, projects: ProjectItem[]): string {
     .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(", "));
+      if (p.stars > 0) meta.push(`Stars: ${p.stars}`);
+      if (p.languages?.length)
+        meta.push(`Languages: ${p.languages.slice(0, 3).join(", ")}`);
       const metaLine = meta.length > 0 ? `${meta.join(" \u00b7 ")}` : "";
       return `### [${p.name}](${p.url})\n${desc}${metaLine ? `\n${metaLine}` : ""}`;
     })
@@ -92,12 +137,16 @@ function renderProjectSection(title: string, projects: ProjectItem[]): string {
 function renderProjectTable(title: string, projects: ProjectItem[]): string {
   if (projects.length === 0) return "";
 
-  const header = `| Project | Description |\n|---------|-------------|`;
+  const header = `| Project | Description | Stars | Languages |\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} |`;
+      const stars = p.stars > 0 ? String(p.stars) : "-";
+      const langs = p.languages?.length
+        ? p.languages.slice(0, 3).join(", ")
+        : "-";
+      return `| [${p.name}](${p.url}) | ${safeDesc} | ${stars} | ${langs} |`;
     })
     .join("\n");
 
@@ -109,6 +158,8 @@ function renderProjectTable(title: string, projects: ProjectItem[]): string {
 function classicTemplate(ctx: TemplateContext): string {
   const parts: string[] = [];
 
+  parts.push(frontmatter(ctx));
+
   if (ctx.pronunciation) {
     parts.push(`# ${ctx.name} <sub><i>(${ctx.pronunciation})</i></sub>`);
   } else {
@@ -123,16 +174,18 @@ function classicTemplate(ctx: TemplateContext): string {
     parts.push(ctx.preamble);
   }
 
-  if (ctx.socialBadges) {
-    parts.push(ctx.socialBadges);
-  }
+  const meta = inlineMetadata(ctx);
+  if (meta) parts.push(meta);
 
-  for (const svg of ctx.svgs) {
-    parts.push(`![${svg.label}](${svg.path})`);
+  if (ctx.socialBadges) {
+    parts.push(`<!-- section: social -->\n${ctx.socialBadges}`);
   }
 
-  if (ctx.archivedProjects.length > 0) {
-    parts.push(renderProjectSection("Archived", ctx.archivedProjects));
+  if (ctx.svgs.length > 0) {
+    const svgLines = ctx.svgs
+      .map((svg) => `![${descriptiveAlt(svg.label, ctx.name)}](${svg.path})`)
+      .join("\n");
+    parts.push(`<!-- section: visualizations -->\n${svgLines}`);
   }
 
   if (ctx.bio) {
@@ -149,66 +202,82 @@ function classicTemplate(ctx: TemplateContext): string {
 function modernTemplate(ctx: TemplateContext): string {
   const parts: string[] = [];
 
+  parts.push(frontmatter(ctx));
+
   parts.push(`# Hi, I'm ${ctx.firstName} 👋`);
 
   if (ctx.preamble) {
     parts.push(ctx.preamble);
   }
 
+  const meta = inlineMetadata(ctx);
+  if (meta) parts.push(meta);
+
   if (ctx.socialBadges) {
-    parts.push(ctx.socialBadges);
+    parts.push(`<!-- section: social -->\n${ctx.socialBadges}`);
   }
 
+  // Projects
+  const projectSections: string[] = [];
   const activeSection = renderProjectSection(
     "Active Projects",
     ctx.activeProjects,
   );
-  if (activeSection) parts.push(activeSection);
+  if (activeSection) projectSections.push(activeSection);
 
   const maintainedSection = renderProjectSection(
     "Maintained Projects",
     ctx.maintainedProjects,
   );
-  if (maintainedSection) parts.push(maintainedSection);
+  if (maintainedSection) projectSections.push(maintainedSection);
 
   const inactiveSection = renderProjectSection(
     "Inactive Projects",
     ctx.inactiveProjects,
   );
-  if (inactiveSection) parts.push(inactiveSection);
+  if (inactiveSection) projectSections.push(inactiveSection);
 
-  const archivedSection = renderProjectSection(
-    "Archived",
-    ctx.archivedProjects,
-  );
-  if (archivedSection) parts.push(archivedSection);
+  if (projectSections.length > 0) {
+    parts.push(`<!-- section: projects -->\n${projectSections.join("\n\n")}`);
+  }
+
+  // Visualizations
+  const vizParts: string[] = [];
 
   // Constellation
   if (ctx.sectionSvgs.constellation) {
-    parts.push(
-      `## Project Map\n\n![Project Constellation](${ctx.sectionSvgs.constellation})`,
+    vizParts.push(
+      `## Project Map\n\n![${descriptiveAlt("Project Constellation", ctx.name)}](${ctx.sectionSvgs.constellation})`,
     );
   }
 
   // GitHub Stats section: rhythm + velocity
   const statsImages: string[] = [];
   if (ctx.sectionSvgs.velocity) {
-    statsImages.push(`![Language Velocity](${ctx.sectionSvgs.velocity})`);
+    statsImages.push(
+      `![${descriptiveAlt("Language Velocity", ctx.name)}](${ctx.sectionSvgs.velocity})`,
+    );
   }
   if (ctx.sectionSvgs.rhythm) {
-    statsImages.push(`![Contribution Rhythm](${ctx.sectionSvgs.rhythm})`);
+    statsImages.push(
+      `![${descriptiveAlt("Contribution Rhythm", ctx.name)}](${ctx.sectionSvgs.rhythm})`,
+    );
   }
   if (statsImages.length > 0) {
-    parts.push(`## GitHub Stats\n\n${statsImages.join("\n")}`);
+    vizParts.push(`## GitHub Stats\n\n${statsImages.join("\n")}`);
   }
 
   // Impact
   if (ctx.sectionSvgs.impact) {
-    parts.push(
-      `## Open Source Impact\n\n![Impact Trail](${ctx.sectionSvgs.impact})`,
+    vizParts.push(
+      `## Open Source Impact\n\n![${descriptiveAlt("Impact Trail", ctx.name)}](${ctx.sectionSvgs.impact})`,
     );
   }
 
+  if (vizParts.length > 0) {
+    parts.push(`<!-- section: visualizations -->\n${vizParts.join("\n\n")}`);
+  }
+
   parts.push(attribution(ctx.templateName));
 
   return `${parts.join("\n\n")}\n`;
@@ -219,22 +288,26 @@ function modernTemplate(ctx: TemplateContext): string {
 function minimalTemplate(ctx: TemplateContext): string {
   const parts: string[] = [];
 
+  parts.push(frontmatter(ctx));
+
   parts.push(`# ${ctx.firstName}`);
 
   if (ctx.preamble) {
     parts.push(ctx.preamble);
   }
 
-  if (ctx.socialBadges) {
-    parts.push(ctx.socialBadges);
-  }
+  const meta = inlineMetadata(ctx);
+  if (meta) parts.push(meta);
 
-  for (const svg of ctx.svgs) {
-    parts.push(`![${svg.label}](${svg.path})`);
+  if (ctx.socialBadges) {
+    parts.push(`<!-- section: social -->\n${ctx.socialBadges}`);
   }
 
-  if (ctx.archivedProjects.length > 0) {
-    parts.push(renderProjectSection("Archived", ctx.archivedProjects));
+  if (ctx.svgs.length > 0) {
+    const svgLines = ctx.svgs
+      .map((svg) => `![${descriptiveAlt(svg.label, ctx.name)}](${svg.path})`)
+      .join("\n");
+    parts.push(`<!-- section: visualizations -->\n${svgLines}`);
   }
 
   parts.push(attribution(ctx.templateName));
@@ -254,70 +327,82 @@ const CATEGORY_ORDER = [
 function ecosystemTemplate(ctx: TemplateContext): string {
   const parts: string[] = [];
 
+  parts.push(frontmatter(ctx));
+
   parts.push(`# Hi, I'm ${ctx.firstName} 👋`);
 
   if (ctx.preamble) {
     parts.push(ctx.preamble);
   }
 
+  const meta = inlineMetadata(ctx);
+  if (meta) parts.push(meta);
+
   if (ctx.socialBadges) {
-    parts.push(ctx.socialBadges);
+    parts.push(`<!-- section: social -->\n${ctx.socialBadges}`);
   }
 
-  // Build a set of archived project names to filter them out of category tables
-  const archivedNames = new Set(ctx.archivedProjects.map((p) => p.name));
+  // Projects
+  const projectParts: string[] = [];
 
-  // Render project tables grouped by category (excluding archived)
+  // Render project tables grouped by category
   for (const category of CATEGORY_ORDER) {
-    const projects = ctx.categorizedProjects[category]?.filter(
-      (p) => !archivedNames.has(p.name),
-    );
+    const projects = ctx.categorizedProjects[category];
     if (projects && projects.length > 0) {
-      parts.push(renderProjectTable(category, projects));
+      projectParts.push(renderProjectTable(category, projects));
     }
   }
 
-  // Render any uncategorized projects that don't match known categories (excluding archived)
+  // Render any uncategorized projects that don't match known categories
   for (const [category, projects] of Object.entries(ctx.categorizedProjects)) {
     if (!CATEGORY_ORDER.includes(category)) {
-      const nonArchived = projects.filter((p) => !archivedNames.has(p.name));
-      if (nonArchived.length > 0) {
-        parts.push(renderProjectTable(category, nonArchived));
+      if (projects.length > 0) {
+        projectParts.push(renderProjectTable(category, projects));
       }
     }
   }
 
-  // Render all archived projects in one consolidated section
-  if (ctx.archivedProjects.length > 0) {
-    parts.push(renderProjectTable("Archived", ctx.archivedProjects));
+  if (projectParts.length > 0) {
+    parts.push(`<!-- section: projects -->\n${projectParts.join("\n\n")}`);
   }
 
+  // Visualizations
+  const vizParts: string[] = [];
+
   // Constellation
   if (ctx.sectionSvgs.constellation) {
-    parts.push(
-      `## Project Map\n\n![Project Constellation](${ctx.sectionSvgs.constellation})`,
+    vizParts.push(
+      `## Project Map\n\n![${descriptiveAlt("Project Constellation", ctx.name)}](${ctx.sectionSvgs.constellation})`,
     );
   }
 
   // GitHub Stats section: velocity + rhythm
   const statsImages: string[] = [];
   if (ctx.sectionSvgs.velocity) {
-    statsImages.push(`![Language Velocity](${ctx.sectionSvgs.velocity})`);
+    statsImages.push(
+      `![${descriptiveAlt("Language Velocity", ctx.name)}](${ctx.sectionSvgs.velocity})`,
+    );
   }
   if (ctx.sectionSvgs.rhythm) {
-    statsImages.push(`![Contribution Rhythm](${ctx.sectionSvgs.rhythm})`);
+    statsImages.push(
+      `![${descriptiveAlt("Contribution Rhythm", ctx.name)}](${ctx.sectionSvgs.rhythm})`,
+    );
   }
   if (statsImages.length > 0) {
-    parts.push(`## GitHub Stats\n\n${statsImages.join("\n")}`);
+    vizParts.push(`## GitHub Stats\n\n${statsImages.join("\n")}`);
   }
 
   // Impact
   if (ctx.sectionSvgs.impact) {
-    parts.push(
-      `## Open Source Impact\n\n![Impact Trail](${ctx.sectionSvgs.impact})`,
+    vizParts.push(
+      `## Open Source Impact\n\n![${descriptiveAlt("Impact Trail", ctx.name)}](${ctx.sectionSvgs.impact})`,
     );
   }
 
+  if (vizParts.length > 0) {
+    parts.push(`<!-- section: visualizations -->\n${vizParts.join("\n\n")}`);
+  }
+
   parts.push(attribution(ctx.templateName));
 
   return `${parts.join("\n\n")}\n`;

package/src/types.ts

@@ -166,6 +166,12 @@ export interface ContributionRhythm {
 
 // ── Project constellation ─────────────────────────────────────────────────
 
+export interface GrowthArcPoint {
+  label: string;
+  avgComplexity: number;
+  repoCount: number;
+}
+
 export interface ConstellationNode {
   name: string;
   url: string;