github-portfolio-analyzer 1.1.0

package/src/io/markdown.js

@@ -0,0 +1,153 @@
+import path from 'node:path';
+import { ensureDirectory, writeTextFile } from './files.js';
+
+export async function writeProjectMarkdownFiles(outputDir, items) {
+  const projectsDir = path.join(outputDir, 'projects');
+  await ensureDirectory(projectsDir);
+
+  const assigned = new Set();
+
+  for (const item of items) {
+    const fileSlug = uniqueSlug(item.slug, item.type, assigned);
+    const filePath = path.join(projectsDir, `${fileSlug}.md`);
+    const content = renderProjectMarkdown(item);
+    await writeTextFile(filePath, content);
+  }
+}
+
+export async function writePortfolioSummary(outputDir, payload) {
+  const summaryPath = path.join(outputDir, 'portfolio-summary.md');
+  await writeTextFile(summaryPath, renderPortfolioSummary(payload));
+  return summaryPath;
+}
+
+function renderProjectMarkdown(item) {
+  const name = item.title ?? item.fullName ?? item.name ?? item.slug;
+  const lines = [
+    `# ${name}`,
+    '',
+    '## Metadata',
+    `- type: ${item.type}`,
+    `- category: ${item.category}`,
+    `- state: ${item.state}`,
+    `- strategy: ${item.strategy}`,
+    `- effort: ${item.effort}`,
+    `- value: ${item.value}`,
+    `- score: ${item.score ?? 0}`,
+    `- nextAction: ${item.nextAction}`,
+    ''
+  ];
+
+  if (item.type === 'repo') {
+    lines.push('## Repository');
+    lines.push(`- fullName: ${item.fullName}`);
+    lines.push(`- url: ${item.htmlUrl ?? 'n/a'}`);
+    lines.push(`- language: ${item.language ?? 'n/a'}`);
+    lines.push(`- activity: ${item.activity ?? 'n/a'}`);
+    lines.push(`- maturity: ${item.maturity ?? 'n/a'}`);
+    lines.push('');
+
+    if (item.structuralHealth) {
+      lines.push('## Structural Health');
+      lines.push(`- README: ${item.structuralHealth.hasReadme}`);
+      lines.push(`- LICENSE: ${item.structuralHealth.hasLicense}`);
+      lines.push(`- package.json: ${item.structuralHealth.hasPackageJson}`);
+      lines.push(`- tests: ${item.structuralHealth.hasTests}`);
+      lines.push(`- CI: ${item.structuralHealth.hasCi}`);
+      lines.push('');
+    }
+  }
+
+  if (item.type === 'idea') {
+    lines.push('## Idea');
+    lines.push(`- status: ${item.status ?? 'draft'}`);
+    lines.push(`- targetUser: ${item.targetUser ?? 'n/a'}`);
+    lines.push(`- problem: ${item.problem ?? 'n/a'}`);
+    lines.push(`- scope: ${item.scope ?? 'n/a'}`);
+    lines.push(`- mvp: ${item.mvp ?? 'n/a'}`);
+    lines.push('');
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+function renderPortfolioSummary(payload) {
+  const { generatedAt, asOfDate, items } = payload;
+  const repos = items.filter((item) => item.type === 'repo');
+  const ideas = items.filter((item) => item.type === 'idea');
+
+  const lines = [
+    '# Portfolio Summary',
+    '',
+    `- generatedAt: ${generatedAt}`,
+    `- asOfDate: ${asOfDate ?? 'null'}`,
+    `- totalProjects: ${items.length}`,
+    `- repositories: ${repos.length}`,
+    `- ideas: ${ideas.length}`,
+    '',
+    '## Top 10 by score',
+    ''
+  ];
+
+  const topTen = [...items]
+    .sort((left, right) => {
+      if ((right.score ?? 0) !== (left.score ?? 0)) {
+        return (right.score ?? 0) - (left.score ?? 0);
+      }
+      return left.slug.localeCompare(right.slug);
+    })
+    .slice(0, 10);
+
+  if (topTen.length === 0) {
+    lines.push('- No projects available.');
+  } else {
+    topTen.forEach((item, index) => {
+      const label = item.title ?? item.fullName ?? item.name ?? item.slug;
+      lines.push(`${index + 1}. ${label} (${item.type}) — score ${item.score ?? 0}, state ${item.state}`);
+    });
+  }
+
+  lines.push('');
+
+  for (const state of ['active', 'stale', 'abandoned', 'idea']) {
+    lines.push(`## State: ${state}`);
+    lines.push('');
+
+    const scoped = items.filter((item) => item.state === state);
+    if (scoped.length === 0) {
+      lines.push('- None');
+    } else {
+      scoped.forEach((item) => {
+        const label = item.title ?? item.fullName ?? item.name ?? item.slug;
+        lines.push(`- ${label} (${item.type}) — score ${item.score ?? 0}`);
+      });
+    }
+
+    lines.push('');
+  }
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+function uniqueSlug(slug, type, assigned) {
+  let candidate = slug;
+  if (!assigned.has(candidate)) {
+    assigned.add(candidate);
+    return candidate;
+  }
+
+  candidate = `${slug}-${type}`;
+  if (!assigned.has(candidate)) {
+    assigned.add(candidate);
+    return candidate;
+  }
+
+  let index = 2;
+  while (assigned.has(`${candidate}-${index}`)) {
+    index += 1;
+  }
+
+  const finalValue = `${candidate}-${index}`;
+  assigned.add(finalValue);
+  return finalValue;
+}

package/src/io/report.js

@@ -0,0 +1,187 @@
+import path from 'node:path';
+import { writeJsonFile, writeTextFile } from './files.js';
+import { effortOrder, stateOrder } from '../core/report.js';
+
+export async function writeReportJson(outputDir, model) {
+  const filePath = path.join(outputDir, 'portfolio-report.json');
+  await writeJsonFile(filePath, model);
+  return filePath;
+}
+
+export async function writeReportMarkdown(outputDir, model) {
+  const filePath = path.join(outputDir, 'portfolio-report.md');
+  await writeTextFile(filePath, renderReportMarkdown(model));
+  return filePath;
+}
+
+export async function writeReportAscii(outputDir, model) {
+  const filePath = path.join(outputDir, 'portfolio-report.txt');
+  await writeTextFile(filePath, renderReportAscii(model));
+  return filePath;
+}
+
+export function renderReportAscii(model) {
+  const lines = [];
+
+  lines.push('Portfolio Decision Report');
+  lines.push('=========================');
+  lines.push(`Generated: ${model.meta.generatedAt}`);
+  lines.push(`As-of date: ${model.meta.asOfDate ?? 'null'}`);
+  lines.push(`Owner: ${model.meta.owner ?? 'null'}`);
+  lines.push(`Counts: total ${model.meta.counts.total}, repos ${model.meta.counts.repos}, ideas ${model.meta.counts.ideas}`);
+  lines.push('');
+  lines.push(`State bar: ${buildStateBarLine(model.summary.byState)}`);
+  lines.push('');
+  lines.push('Completion x Effort Matrix');
+  lines.push('--------------------------');
+  lines.push(renderAsciiMatrix(model.matrix.completionByEffort));
+  lines.push('');
+
+  lines.push(...renderAsciiBandSection('NOW', model.summary.now));
+  lines.push(...renderAsciiBandSection('NEXT', model.summary.next));
+  lines.push(...renderAsciiBandSection('LATER', model.summary.later));
+  lines.push(...renderAsciiBandSection('PARK', model.summary.park));
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+export function renderReportMarkdown(model) {
+  const lines = [];
+
+  lines.push('# Portfolio Decision Report');
+  lines.push('');
+  lines.push(`- Generated: ${model.meta.generatedAt}`);
+  lines.push(`- As-of date: ${model.meta.asOfDate ?? 'null'}`);
+  lines.push(`- Owner: ${model.meta.owner ?? 'null'}`);
+  lines.push(`- Counts: total ${model.meta.counts.total}, repos ${model.meta.counts.repos}, ideas ${model.meta.counts.ideas}`);
+  lines.push('');
+
+  lines.push('## State Bar');
+  lines.push('');
+  lines.push(buildStateBarLine(model.summary.byState));
+  lines.push('');
+
+  lines.push('## Top 10 by Score');
+  lines.push('');
+  lines.push('| # | Slug | Type | Score | State | Effort Estimate | Value | CL | Priority | Next Action |');
+  lines.push('|---|------|------|-------|-------|-----------------|-------|----|----------|-------------|');
+
+  const top10 = model.summary.top10ByScore;
+  if (top10.length === 0) {
+    lines.push('| 1 | - | - | - | - | - | - | - | - | - |');
+  } else {
+    top10.forEach((item, index) => {
+      lines.push(`| ${index + 1} | ${escapeCell(item.slug)} | ${item.type} | ${item.score} | ${item.state} | ${item.effortEstimate} | ${item.value} | ${item.completionLevel} | ${item.priorityBand} | ${escapeCell(item.nextAction)} |`);
+    });
+  }
+
+  lines.push('');
+  lines.push('## Completion x Effort Matrix');
+  lines.push('');
+  lines.push('| Level | xs | s | m | l | xl |');
+  lines.push('|-------|----|---|---|---|----|');
+
+  for (let level = 0; level <= 5; level += 1) {
+    const key = `CL${level}`;
+    const row = model.matrix.completionByEffort[key];
+    lines.push(`| ${key} | ${row.xs} | ${row.s} | ${row.m} | ${row.l} | ${row.xl} |`);
+  }
+
+  lines.push('');
+  lines.push(...renderMarkdownBandSection('NOW', model.summary.now));
+  lines.push(...renderMarkdownBandSection('NEXT', model.summary.next));
+  lines.push(...renderMarkdownBandSection('LATER', model.summary.later));
+  lines.push(...renderMarkdownBandSection('PARK', model.summary.park));
+
+  return `${lines.join('\n').trimEnd()}\n`;
+}
+
+function renderAsciiBandSection(title, items) {
+  const lines = [];
+  lines.push(`${title}`);
+  lines.push('-'.repeat(title.length));
+
+  if (items.length === 0) {
+    lines.push('None');
+    lines.push('');
+    return lines;
+  }
+
+  items.slice(0, 5).forEach((item, index) => {
+    lines.push(`${index + 1}) ${item.slug} — Score ${item.score} — CL${item.completionLevel} — Effort ${item.effortEstimate} — State ${item.state}`);
+    lines.push(`   Why: ${item.priorityWhy?.join('; ') ?? ''}`);
+    lines.push(`   Next: ${item.nextAction}`);
+  });
+
+  lines.push('');
+  return lines;
+}
+
+function renderMarkdownBandSection(title, items) {
+  const lines = [];
+  lines.push(`## ${title}`);
+  lines.push('');
+
+  if (items.length === 0) {
+    lines.push('- None');
+    lines.push('');
+    return lines;
+  }
+
+  items.slice(0, 5).forEach((item, index) => {
+    lines.push(`${index + 1}. **${item.slug}** — Score ${item.score} — CL${item.completionLevel} — Effort ${item.effortEstimate} — State ${item.state}`);
+    lines.push(`   - Why: ${item.priorityWhy?.join('; ') ?? ''}`);
+    lines.push(`   - Next: ${item.nextAction}`);
+  });
+
+  lines.push('');
+  return lines;
+}
+
+function buildStateBarLine(byState) {
+  const states = stateOrder();
+  const counts = states.map((state) => Number(byState[state] ?? 0));
+  const maxCount = Math.max(1, ...counts);
+
+  const segments = states.map((state) => {
+    const count = Number(byState[state] ?? 0);
+    const blocks = count <= 0 ? '' : '█'.repeat(Math.max(1, Math.round((count / maxCount) * 8)));
+    return `${state} ${blocks} ${count}`.replace(/\s+/g, ' ').trim();
+  });
+
+  return segments.join(' | ');
+}
+
+function renderAsciiMatrix(matrix) {
+  const effortKeys = effortOrder();
+  const header = ['Level', ...effortKeys.map((effort) => effort.toUpperCase())];
+  const widths = [5, 4, 4, 4, 4, 4];
+
+  const rows = [];
+  rows.push(formatRow(header, widths));
+  rows.push(formatRow(widths.map((width) => '-'.repeat(width)), widths));
+
+  for (let level = 0; level <= 5; level += 1) {
+    const key = `CL${level}`;
+    const row = matrix[key] ?? { xs: 0, s: 0, m: 0, l: 0, xl: 0 };
+    rows.push(
+      formatRow(
+        [key, String(row.xs), String(row.s), String(row.m), String(row.l), String(row.xl)],
+        widths
+      )
+    );
+  }
+
+  return rows.join('\n');
+}
+
+function formatRow(cells, widths) {
+  return cells
+    .map((cell, index) => String(cell).padEnd(widths[index], ' '))
+    .join(' ')
+    .trimEnd();
+}
+
+function escapeCell(value) {
+  return String(value ?? '').replaceAll('|', '\\|');
+}

package/src/utils/args.js

@@ -0,0 +1,32 @@
+export function parseArgs(argv) {
+  const positional = [];
+  const options = {};
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const current = argv[index];
+
+    if (!current.startsWith('--')) {
+      positional.push(current);
+      continue;
+    }
+
+    const [rawKey, inlineValue] = current.split('=', 2);
+    const key = rawKey.replace(/^--/, '');
+
+    if (inlineValue !== undefined) {
+      options[key] = inlineValue;
+      continue;
+    }
+
+    const next = argv[index + 1];
+    if (!next || next.startsWith('--')) {
+      options[key] = true;
+      continue;
+    }
+
+    options[key] = next;
+    index += 1;
+  }
+
+  return { positional, options };
+}

package/src/utils/concurrency.js

@@ -0,0 +1,26 @@
+export async function mapWithConcurrency(items, limit, mapper) {
+  if (!Array.isArray(items)) {
+    return [];
+  }
+
+  const concurrency = Math.max(1, Math.floor(limit));
+  const results = new Array(items.length);
+  let nextIndex = 0;
+
+  async function worker() {
+    while (true) {
+      const currentIndex = nextIndex;
+      nextIndex += 1;
+
+      if (currentIndex >= items.length) {
+        return;
+      }
+
+      results[currentIndex] = await mapper(items[currentIndex], currentIndex);
+    }
+  }
+
+  const workers = Array.from({ length: Math.min(concurrency, items.length) }, () => worker());
+  await Promise.all(workers);
+  return results;
+}

package/src/utils/header.js

@@ -0,0 +1,48 @@
+import { RESET, GRAY, AMBER, GREEN, BLUE, BOLD } from './output.js';
+import packageJson from '../../package.json' with { type: 'json' };
+
+const DIM = '\x1b[2m';
+
+const ASCII = `${BLUE}  ◉──●──●──●──◉${RESET}
+${DIM}         \\    /${RESET}
+${AMBER}          ◉──◉${RESET}
+${DIM}            ↓${RESET}
+${AMBER}  now  ████ ↑↑↑${RESET}
+${AMBER}  next ███░ ↑↑${RESET}
+${AMBER}  later█░░░ ↑${RESET}
+${DIM}            ↓${RESET}
+${GREEN}  ✓ report.json${RESET}`;
+
+export function printHeader({ command: _command, asOfDate, outputDir, hasToken, hasPolicy, version }) {
+  const node = process.version;
+  const user = process.env.GITHUB_USERNAME ?? '—';
+  const token = hasToken ? `${GREEN}✓ set${RESET}` : `${AMBER}not set${RESET}`;
+  const policy = hasPolicy ? `${GREEN}✓ set${RESET}` : `${GRAY}not set${RESET}`;
+  const ver = version ?? packageJson.version;
+
+  const info = [
+    `${BOLD}github-portfolio-analyzer${RESET}`,
+    `${GRAY}repo inventory → execution decisions${RESET}`,
+    ``,
+    `${GRAY}version    ${RESET}${GREEN}${ver}${RESET}`,
+    `${GRAY}node       ${RESET}${node}`,
+    `${GRAY}user       ${RESET}${user}`,
+    `${GRAY}as-of      ${RESET}${asOfDate ?? 'today UTC'}`,
+    `${GRAY}output     ${RESET}${outputDir ?? 'output/'}`,
+    `${GRAY}token      ${RESET}${token}`,
+    `${GRAY}policy     ${RESET}${policy}`,
+  ];
+
+  const artLines = ASCII.split('\n');
+  const maxLines = Math.max(artLines.length, info.length);
+
+  console.log('');
+  for (let i = 0; i < maxLines; i++) {
+    const left  = (artLines[i] ?? '').padEnd(26);
+    const right = info[i] ?? '';
+    console.log(`  ${left}  ${right}`);
+  }
+
+  const divider = `${GRAY}${'─'.repeat(56)}${RESET}`;
+  console.log(`\n  ${divider}\n`);
+}

package/src/utils/nextAction.js

@@ -0,0 +1,28 @@
+export function formatNextAction(verb, target, measurableCondition) {
+  return `${capitalize(verb)} ${target} — Done when: ${measurableCondition}`;
+}
+
+export function normalizeNextAction(value) {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    throw new Error('Invalid nextAction format. Required: "<Verb> <target> — Done when: <measurable condition>"');
+  }
+
+  const trimmed = value.trim();
+  if (trimmed.includes('— Done when:')) {
+    return trimmed;
+  }
+
+  if (trimmed.includes(' - Done when:')) {
+    return trimmed.replace(' - Done when:', ' — Done when:');
+  }
+
+  throw new Error('Invalid nextAction format. Required: "<Verb> <target> — Done when: <measurable condition>"');
+}
+
+function capitalize(value) {
+  if (value.length === 0) {
+    return value;
+  }
+
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}

package/src/utils/output.js

@@ -0,0 +1,15 @@
+export const RESET  = '\x1b[0m';
+export const GRAY   = '\x1b[90m';
+export const AMBER  = '\x1b[33m';
+export const GREEN  = '\x1b[32m';
+export const RED    = '\x1b[31m';
+export const BLUE   = '\x1b[34m';
+export const BOLD   = '\x1b[1m';
+
+export function info(msg)     { console.log(`${GRAY}${msg}${RESET}`); }
+export function progress(msg) { console.log(`${AMBER}${msg}${RESET}`); }
+export function success(msg)  { console.log(`${GREEN}${msg}${RESET}`); }
+export function error(msg)    { console.error(`${RED}${msg}${RESET}`); }
+export function warn(msg)     { console.log(`${AMBER}⚠ ${msg}${RESET}`); }
+export function fatal(msg)    { console.error(`${RED}✗ ${msg}${RESET}`); }
+export function dim(msg)      { process.stdout.write(`${GRAY}${msg}${RESET}`); }

package/src/utils/retry.js

@@ -0,0 +1,67 @@
+const DEFAULT_BASE_DELAY_MS = 500;
+const DEFAULT_MAX_DELAY_MS = 30_000;
+
+export function isRetryableStatus(status) {
+  return status === 403 || status === 429 || status >= 500;
+}
+
+export function computeRetryDelayMs({ responseHeaders, attempt, nowMs = Date.now() }) {
+  const retryAfter = parseRetryAfterMs(responseHeaders);
+  if (retryAfter !== null) {
+    return retryAfter;
+  }
+
+  const resetDelay = parseRateLimitResetMs(responseHeaders, nowMs);
+  if (resetDelay !== null) {
+    return resetDelay;
+  }
+
+  const exponential = DEFAULT_BASE_DELAY_MS * (2 ** attempt);
+  const jitter = Math.floor(Math.random() * 250);
+  return Math.min(DEFAULT_MAX_DELAY_MS, exponential + jitter);
+}
+
+export async function sleepMs(delayMs) {
+  if (delayMs <= 0) {
+    return;
+  }
+
+  await new Promise((resolve) => setTimeout(resolve, delayMs));
+}
+
+function parseRetryAfterMs(headers) {
+  if (!headers) {
+    return null;
+  }
+
+  const retryAfterRaw = headers.get('retry-after');
+  if (!retryAfterRaw) {
+    return null;
+  }
+
+  const seconds = Number.parseInt(retryAfterRaw, 10);
+  if (Number.isNaN(seconds) || seconds < 0) {
+    return null;
+  }
+
+  return seconds * 1000;
+}
+
+function parseRateLimitResetMs(headers, nowMs) {
+  if (!headers) {
+    return null;
+  }
+
+  const resetRaw = headers.get('x-ratelimit-reset');
+  if (!resetRaw) {
+    return null;
+  }
+
+  const secondsSinceEpoch = Number.parseInt(resetRaw, 10);
+  if (Number.isNaN(secondsSinceEpoch)) {
+    return null;
+  }
+
+  const resetTimeMs = secondsSinceEpoch * 1000;
+  return Math.max(0, resetTimeMs - nowMs);
+}

package/src/utils/slug.js

@@ -0,0 +1,8 @@
+export function slugify(value) {
+  return String(value ?? '')
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-');
+}

package/src/utils/time.js

@@ -0,0 +1,26 @@
+const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
+
+export function utcTodayDateString() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+export function resolveAsOfDate(input) {
+  if (typeof input === 'string' && input.length > 0) {
+    if (!ISO_DATE_PATTERN.test(input)) {
+      throw new Error(`Invalid --as-of value: ${input}. Expected YYYY-MM-DD.`);
+    }
+
+    const asDate = new Date(`${input}T00:00:00.000Z`);
+    if (Number.isNaN(asDate.getTime())) {
+      throw new Error(`Invalid --as-of value: ${input}. Expected YYYY-MM-DD.`);
+    }
+
+    return input;
+  }
+
+  return utcTodayDateString();
+}
+
+export function utcNowISOString() {
+  return new Date().toISOString();
+}