github-portfolio-analyzer 1.1.0

package/src/core/scoring.js

@@ -0,0 +1,92 @@
+import { daysSince } from './classification.js';
+
+export function scoreRepository(repository, asOfDate) {
+  let score = 0;
+  const breakdown = {
+    pushedWithin90Days: 0,
+    hasReadme: 0,
+    hasLicense: 0,
+    hasTests: 0,
+    starsOverOne: 0,
+    updatedWithin180Days: 0
+  };
+
+  if (daysSince(repository.pushedAt, asOfDate) <= 90) {
+    score += 30;
+    breakdown.pushedWithin90Days = 30;
+  }
+
+  if (repository.structuralHealth?.hasReadme) {
+    score += 15;
+    breakdown.hasReadme = 15;
+  }
+
+  if (repository.structuralHealth?.hasLicense) {
+    score += 10;
+    breakdown.hasLicense = 10;
+  }
+
+  if (repository.structuralHealth?.hasTests) {
+    score += 20;
+    breakdown.hasTests = 20;
+  }
+
+  if ((repository.stargazersCount ?? 0) > 1) {
+    score += 5;
+    breakdown.starsOverOne = 5;
+  }
+
+  if (daysSince(repository.updatedAt, asOfDate) <= 180) {
+    score += 20;
+    breakdown.updatedWithin180Days = 20;
+  }
+
+  return {
+    score: clamp(score, 0, 100),
+    scoreBreakdown: breakdown
+  };
+}
+
+export function scoreIdea(idea) {
+  let score = 30;
+  const breakdown = {
+    baseline: 30,
+    scopeOrProblem: 0,
+    targetUser: 0,
+    mvp: 0,
+    nextAction: 0
+  };
+
+  if (hasText(idea.scope) || hasText(idea.problem)) {
+    score += 20;
+    breakdown.scopeOrProblem = 20;
+  }
+
+  if (hasText(idea.targetUser)) {
+    score += 15;
+    breakdown.targetUser = 15;
+  }
+
+  if (hasText(idea.mvp)) {
+    score += 15;
+    breakdown.mvp = 15;
+  }
+
+  if (hasText(idea.nextAction)) {
+    score += 20;
+    breakdown.nextAction = 20;
+  }
+
+  return {
+    score: clamp(score, 0, 100),
+    scoreBreakdown: breakdown
+  };
+}
+
+function hasText(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}

package/src/core/taxonomy.js

@@ -0,0 +1,155 @@
+import { formatNextAction, normalizeNextAction } from '../utils/nextAction.js';
+
+export function buildRepoTaxonomy(repository) {
+  const activityState = repository.activity;
+  const state = repository.archived ? 'archived' : normalizeState(activityState, 'active');
+
+  const category = 'tooling';
+  const strategy = 'maintenance';
+  const effort = 'm';
+  const value = 'medium';
+  const nextAction = defaultRepoNextAction(state);
+
+  const sources = {
+    category: 'default',
+    state: repository.archived ? 'inferred' : 'inferred',
+    strategy: 'default',
+    effort: 'default',
+    value: 'default',
+    nextAction: 'default'
+  };
+
+  return {
+    type: 'repo',
+    category,
+    state,
+    strategy,
+    effort,
+    value,
+    nextAction: normalizeNextAction(nextAction),
+    taxonomyMeta: {
+      defaulted: Object.values(sources).includes('default'),
+      sources,
+      inferenceSignals: repository.archived ? ['repository.archived=true'] : ['activity classification']
+    }
+  };
+}
+
+export function buildIdeaTaxonomy(idea) {
+  const inferredState = mapIdeaStatusToState(idea.status);
+
+  const category = normalizeCategory(idea.category) ?? 'experiment';
+  const state = normalizeState(idea.state, inferredState);
+  const strategy = normalizeStrategy(idea.strategy) ?? 'parked';
+  const effort = normalizeEffort(idea.effort) ?? 'm';
+  const value = normalizeValue(idea.value) ?? 'medium';
+  const nextAction = normalizeNextAction(
+    typeof idea.nextAction === 'string' && idea.nextAction.trim().length > 0
+      ? idea.nextAction
+      : formatNextAction('Define', 'MVP in 7 bullets', 'issue includes scope, target user, and acceptance checks')
+  );
+
+  const sources = {
+    category: normalizeCategory(idea.category) ? 'user' : 'default',
+    state: normalizeState(idea.state, null) ? 'user' : 'inferred',
+    strategy: normalizeStrategy(idea.strategy) ? 'user' : 'default',
+    effort: normalizeEffort(idea.effort) ? 'user' : 'default',
+    value: normalizeValue(idea.value) ? 'user' : 'default',
+    nextAction: typeof idea.nextAction === 'string' && idea.nextAction.trim().length > 0 ? 'user' : 'default'
+  };
+
+  const inferenceSignals = [];
+  if (sources.state === 'inferred') {
+    inferenceSignals.push('status mapping');
+  }
+
+  return {
+    type: 'idea',
+    category,
+    state,
+    strategy,
+    effort,
+    value,
+    nextAction,
+    taxonomyMeta: {
+      defaulted: Object.values(sources).includes('default'),
+      sources,
+      ...(inferenceSignals.length > 0 ? { inferenceSignals } : {})
+    }
+  };
+}
+
+export function mapIdeaStatusToState(status) {
+  const value = String(status ?? '').trim().toLowerCase();
+
+  if (value === 'active' || value === 'in-progress') {
+    return 'active';
+  }
+
+  if (value === 'stale' || value === 'on-hold') {
+    return 'stale';
+  }
+
+  if (value === 'abandoned' || value === 'dropped') {
+    return 'abandoned';
+  }
+
+  if (value === 'archived') {
+    return 'archived';
+  }
+
+  if (value === 'reference-only' || value === 'reference') {
+    return 'reference-only';
+  }
+
+  return 'idea';
+}
+
+function defaultRepoNextAction(state) {
+  if (state === 'active') {
+    return formatNextAction('Ship', 'one meaningful improvement', 'one PR with tests and updated docs is merged');
+  }
+
+  if (state === 'stale') {
+    return formatNextAction('Refresh', 'execution documentation', 'README run steps are validated in a clean environment');
+  }
+
+  if (state === 'abandoned') {
+    return formatNextAction('Decide', 'retain or archive status', 'README contains a documented decision and rationale');
+  }
+
+  if (state === 'archived') {
+    return formatNextAction('Document', 'reference usage', 'README states archive reason and replacement options');
+  }
+
+  return formatNextAction('Clarify', 'project direction', 'next milestone and owner are documented');
+}
+
+function normalizeCategory(value) {
+  return normalizeEnum(value, ['product', 'tooling', 'library', 'learning', 'content', 'infra', 'experiment', 'template']);
+}
+
+function normalizeState(value, fallback) {
+  return normalizeEnum(value, ['idea', 'active', 'stale', 'abandoned', 'archived', 'reference-only']) ?? fallback;
+}
+
+function normalizeStrategy(value) {
+  return normalizeEnum(value, ['strategic-core', 'strategic-support', 'opportunistic', 'maintenance', 'parked']);
+}
+
+function normalizeEffort(value) {
+  return normalizeEnum(value, ['xs', 's', 'm', 'l', 'xl']);
+}
+
+function normalizeValue(value) {
+  return normalizeEnum(value, ['low', 'medium', 'high', 'very-high']);
+}
+
+function normalizeEnum(value, allowed) {
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+
+  return allowed.includes(normalized) ? normalized : null;
+}

package/src/errors.js

@@ -0,0 +1,7 @@
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+    this.exitCode = 2;
+  }
+}

package/src/github/client.js

@@ -0,0 +1,76 @@
+const GITHUB_API_BASE_URL = 'https://api.github.com';
+import { computeRetryDelayMs, isRetryableStatus, sleepMs } from '../utils/retry.js';
+
+export class GithubApiError extends Error {
+  constructor(message, options) {
+    super(message);
+    this.name = 'GithubApiError';
+    this.status = options.status;
+    this.data = options.data;
+    this.headers = options.headers;
+  }
+}
+
+export class GithubClient {
+  constructor(token) {
+    this.token = token;
+    this.maxRetries = 4;
+  }
+
+  async request(path, init = {}) {
+    const url = `${GITHUB_API_BASE_URL}${path}`;
+    const requestInit = {
+      ...init,
+      headers: {
+        Accept: 'application/vnd.github+json',
+        Authorization: `Bearer ${this.token}`,
+        'User-Agent': 'github-portfolio-analyzer',
+        ...init.headers
+      }
+    };
+
+    for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+      const response = await fetch(url, requestInit);
+      const data = await safeJson(response);
+
+      if (response.ok) {
+        return data;
+      }
+
+      if (attempt < this.maxRetries && isRetryableStatus(response.status)) {
+        const delayMs = computeRetryDelayMs({
+          responseHeaders: response.headers,
+          attempt
+        });
+        await sleepMs(delayMs);
+        continue;
+      }
+
+      const details = data?.message ? ` (${data.message})` : '';
+      throw new GithubApiError(`GitHub API request failed: ${response.status}${details}`, {
+        status: response.status,
+        data,
+        headers: response.headers
+      });
+    }
+
+    throw new Error('GitHub request retry loop exited unexpectedly.');
+  }
+
+  async getAuthenticatedUser() {
+    return this.request('/user');
+  }
+}
+
+async function safeJson(response) {
+  const contentType = response.headers.get('content-type') ?? '';
+  if (!contentType.includes('application/json')) {
+    return null;
+  }
+
+  try {
+    return await response.json();
+  } catch {
+    return null;
+  }
+}

package/src/github/repo-inspection.js

@@ -0,0 +1,87 @@
+import { GithubApiError } from './client.js';
+
+export async function inspectRepositoryStructure(client, repository) {
+  const [hasReadme, packageJsonContent, rootContents, workflowContents] = await Promise.all([
+    checkReadme(client, repository),
+    readPackageJson(client, repository),
+    readDirectory(client, repository, ''),
+    readDirectory(client, repository, '.github/workflows')
+  ]);
+
+  const hasPackageJson = packageJsonContent !== null;
+  const hasTests = detectTests(packageJsonContent, rootContents);
+  const hasCi = Array.isArray(workflowContents) && workflowContents.length > 0;
+
+  return {
+    hasReadme,
+    hasLicense: Boolean(repository.hasLicense),
+    hasPackageJson,
+    hasTests,
+    hasCi
+  };
+}
+
+async function checkReadme(client, repository) {
+  try {
+    await client.request(repoApiPath(repository, 'readme'));
+    return true;
+  } catch (error) {
+    if (isNotFound(error)) {
+      return false;
+    }
+    throw error;
+  }
+}
+
+async function readPackageJson(client, repository) {
+  try {
+    const response = await client.request(repoApiPath(repository, 'contents/package.json'));
+    if (response?.content && response?.encoding === 'base64') {
+      const decoded = Buffer.from(response.content, 'base64').toString('utf8');
+      return JSON.parse(decoded);
+    }
+    return null;
+  } catch (error) {
+    if (isNotFound(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+async function readDirectory(client, repository, directoryPath) {
+  const suffix = directoryPath.length > 0 ? `contents/${directoryPath}` : 'contents';
+
+  try {
+    const response = await client.request(repoApiPath(repository, suffix));
+    return Array.isArray(response) ? response : [];
+  } catch (error) {
+    if (isNotFound(error)) {
+      return [];
+    }
+    throw error;
+  }
+}
+
+function detectTests(packageJson, rootContents) {
+  const scripts = packageJson?.scripts;
+  if (scripts && typeof scripts.test === 'string') {
+    const normalized = scripts.test.trim().toLowerCase();
+    if (normalized.length > 0 && !normalized.includes('no test specified')) {
+      return true;
+    }
+  }
+
+  const rootNames = new Set((rootContents ?? []).map((entry) => String(entry.name).toLowerCase()));
+  const commonTestPaths = ['test', 'tests', '__tests__', 'spec', 'specs'];
+
+  return commonTestPaths.some((name) => rootNames.has(name));
+}
+
+function repoApiPath(repository, suffix) {
+  return `/repos/${encodeURIComponent(repository.ownerLogin)}/${encodeURIComponent(repository.name)}/${suffix}`;
+}
+
+function isNotFound(error) {
+  return error instanceof GithubApiError && error.status === 404;
+}

package/src/github/repos.js

@@ -0,0 +1,58 @@
+const PAGE_SIZE = 100;
+
+export async function fetchAllRepositories(client) {
+  const repositories = [];
+
+  for (let page = 1; ; page += 1) {
+    const params = new URLSearchParams({
+      per_page: String(PAGE_SIZE),
+      page: String(page),
+      sort: 'full_name',
+      direction: 'asc',
+      visibility: 'all'
+    });
+
+    const pageItems = await client.request(`/user/repos?${params.toString()}`);
+
+    if (!Array.isArray(pageItems) || pageItems.length === 0) {
+      break;
+    }
+
+    repositories.push(...pageItems);
+
+    if (pageItems.length < PAGE_SIZE) {
+      break;
+    }
+  }
+
+  repositories.sort((left, right) => left.full_name.localeCompare(right.full_name));
+  return repositories;
+}
+
+export function normalizeRepository(repo) {
+  return {
+    id: repo.id,
+    nodeId: repo.node_id,
+    name: repo.name,
+    ownerLogin: repo.owner?.login ?? '',
+    fullName: repo.full_name,
+    private: repo.private,
+    archived: repo.archived,
+    fork: repo.fork,
+    htmlUrl: repo.html_url,
+    description: repo.description,
+    language: repo.language,
+    homepage: typeof repo.homepage === 'string' && repo.homepage.trim().length > 0
+      ? repo.homepage.trim()
+      : null,
+    stargazersCount: repo.stargazers_count,
+    forksCount: repo.forks_count,
+    openIssuesCount: repo.open_issues_count,
+    sizeKb: repo.size,
+    defaultBranch: repo.default_branch,
+    topics: Array.isArray(repo.topics) ? repo.topics : [],
+    hasLicense: Boolean(repo.license),
+    _updatedAt: repo.updated_at,
+    _pushedAt: repo.pushed_at
+  };
+}

package/src/io/csv.js

@@ -0,0 +1,61 @@
+import path from 'node:path';
+import { writeTextFile } from './files.js';
+
+export async function writeInventoryCsv(outputDir, items) {
+  const filePath = path.join(outputDir, 'inventory.csv');
+  const header = [
+    'id',
+    'fullName',
+    'type',
+    'private',
+    'archived',
+    'language',
+    'stargazersCount',
+    'sizeKb',
+    'activity',
+    'maturity',
+    'score',
+    'state',
+    'strategy',
+    'effort',
+    'value',
+    'nextAction'
+  ];
+
+  const rows = [header.join(',')];
+
+  for (const item of items) {
+    const row = [
+      item.id,
+      item.fullName,
+      item.type,
+      item.private,
+      item.archived,
+      item.language ?? '',
+      item.stargazersCount ?? 0,
+      item.sizeKb ?? 0,
+      item.activity ?? '',
+      item.maturity ?? '',
+      item.score ?? 0,
+      item.state ?? '',
+      item.strategy ?? '',
+      item.effort ?? '',
+      item.value ?? '',
+      item.nextAction ?? ''
+    ].map(csvEscape);
+
+    rows.push(row.join(','));
+  }
+
+  await writeTextFile(filePath, `${rows.join('\n')}\n`);
+  return filePath;
+}
+
+function csvEscape(value) {
+  const stringValue = String(value ?? '');
+  if (!/[",\n]/.test(stringValue)) {
+    return stringValue;
+  }
+
+  return `"${stringValue.replaceAll('"', '""')}"`;
+}

package/src/io/files.js

@@ -0,0 +1,39 @@
+import { access, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+export async function ensureDirectory(dirPath) {
+  await mkdir(dirPath, { recursive: true });
+}
+
+export async function writeJsonFile(filePath, value) {
+  await ensureDirectory(path.dirname(filePath));
+  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+export async function writeTextFile(filePath, content) {
+  await ensureDirectory(path.dirname(filePath));
+  await writeFile(filePath, content, 'utf8');
+}
+
+export async function readJsonFile(filePath) {
+  const content = await readFile(filePath, 'utf8');
+  return JSON.parse(content);
+}
+
+export async function readJsonFileIfExists(filePath) {
+  const exists = await fileExists(filePath);
+  if (!exists) {
+    return null;
+  }
+
+  return readJsonFile(filePath);
+}
+
+export async function fileExists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}