github-portfolio-analyzer 1.1.0

package/analyzer.manifest.json

@@ -0,0 +1,18 @@
+{
+  "name": "github-portfolio-analyzer",
+  "version": "1.0.0",
+  "commands": [
+    { "id": "analyze" },
+    { "id": "ingest-ideas" },
+    { "id": "build-portfolio" },
+    { "id": "report", "flags": ["--policy", "--explain", "--output", "--format", "--quiet"] }
+  ],
+  "outputs": [
+    "output/inventory.json",
+    "output/portfolio.json",
+    "output/portfolio-report.json"
+  ],
+  "schemas": {
+    "portfolioReport": "schemas/portfolio-report.schema.json"
+  }
+}

package/bin/github-portfolio-analyzer.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(`Error: ${error.message}`);
+  process.exitCode = Number.isInteger(error?.exitCode) ? error.exitCode : 1;
+});

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "github-portfolio-analyzer",
+  "version": "1.1.0",
+  "description": "CLI tool to analyze GitHub repos and portfolio ideas",
+  "type": "module",
+  "bin": {
+    "github-portfolio-analyzer": "bin/github-portfolio-analyzer.js"
+  },
+  "scripts": {
+    "start": "node bin/github-portfolio-analyzer.js",
+    "analyze": "node bin/github-portfolio-analyzer.js analyze",
+    "ingest-ideas": "node bin/github-portfolio-analyzer.js ingest-ideas",
+    "build-portfolio": "node bin/github-portfolio-analyzer.js build-portfolio",
+    "report": "node bin/github-portfolio-analyzer.js report",
+    "lint": "eslint .",
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/paulo-raoni/github-portfolio-analyzer.git"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "schemas/",
+    "analyzer.manifest.json",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "dependencies": {
+    "dotenv": "^17.0.0"
+  },
+  "devDependencies": {
+    "eslint": "^10.0.2"
+  }
+}

package/schemas/portfolio-report.schema.json

@@ -0,0 +1,266 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github-portfolio-analyzer.local/schemas/portfolio-report.schema.json",
+  "title": "GitHub Portfolio Analyzer Report",
+  "type": "object",
+  "additionalProperties": true,
+  "required": ["meta", "summary", "matrix", "items"],
+  "properties": {
+    "meta": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["generatedAt", "asOfDate", "owner", "counts"],
+      "properties": {
+        "generatedAt": { "type": "string" },
+        "asOfDate": {
+          "type": ["string", "null"],
+          "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+        },
+        "owner": { "type": ["string", "null"] },
+        "counts": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["total", "repos", "ideas"],
+          "properties": {
+            "total": { "type": "number" },
+            "repos": { "type": "number" },
+            "ideas": { "type": "number" }
+          }
+        }
+      },
+      "allOf": [
+        {
+          "if": {
+            "properties": { "asOfDate": { "type": "string" } }
+          },
+          "then": {
+            "properties": {
+              "asOfDate": {
+                "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+              }
+            }
+          }
+        }
+      ]
+    },
+    "summary": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["byState", "top10ByScore", "now", "next", "later", "park"],
+      "properties": {
+        "byState": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["active", "stale", "abandoned", "archived", "idea", "reference-only"],
+          "properties": {
+            "active": { "type": "number" },
+            "stale": { "type": "number" },
+            "abandoned": { "type": "number" },
+            "archived": { "type": "number" },
+            "idea": { "type": "number" },
+            "reference-only": { "type": "number" }
+          }
+        },
+        "top10ByScore": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/summaryItem" }
+        },
+        "now": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/summaryItem" }
+        },
+        "next": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/summaryItem" }
+        },
+        "later": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/summaryItem" }
+        },
+        "park": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/summaryItem" }
+        }
+      }
+    },
+    "matrix": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["completionByEffort"],
+      "properties": {
+        "completionByEffort": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["CL0", "CL1", "CL2", "CL3", "CL4", "CL5"],
+          "properties": {
+            "CL0": { "$ref": "#/$defs/matrixRow" },
+            "CL1": { "$ref": "#/$defs/matrixRow" },
+            "CL2": { "$ref": "#/$defs/matrixRow" },
+            "CL3": { "$ref": "#/$defs/matrixRow" },
+            "CL4": { "$ref": "#/$defs/matrixRow" },
+            "CL5": { "$ref": "#/$defs/matrixRow" }
+          }
+        }
+      }
+    },
+    "items": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/item" }
+    }
+  },
+  "$defs": {
+    "priorityOverride": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["ruleId", "boost", "reason"],
+      "properties": {
+        "ruleId": { "type": "string" },
+        "boost": { "type": "number" },
+        "forceBand": {
+          "type": "string",
+          "enum": ["now", "next", "later", "park"]
+        },
+        "reason": { "type": "string" }
+      }
+    },
+    "summaryItem": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "slug",
+        "type",
+        "score",
+        "state",
+        "effort",
+        "effortEstimate",
+        "value",
+        "completionLevel",
+        "basePriorityScore",
+        "finalPriorityScore",
+        "priorityBand",
+        "priorityOverrides",
+        "priorityWhy",
+        "nextAction"
+      ],
+      "properties": {
+        "slug": { "type": "string" },
+        "type": {
+          "type": "string",
+          "enum": ["repo", "idea"]
+        },
+        "score": { "type": "number" },
+        "state": { "type": "string" },
+        "effort": { "type": "string" },
+        "effortEstimate": {
+          "type": "string",
+          "enum": ["xs", "s", "m", "l", "xl"]
+        },
+        "value": { "type": "string" },
+        "completionLevel": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 5
+        },
+        "basePriorityScore": { "type": "number" },
+        "finalPriorityScore": { "type": "number" },
+        "priorityBand": {
+          "type": "string",
+          "enum": ["now", "next", "later", "park"]
+        },
+        "priorityTag": { "type": "string" },
+        "priorityOverrides": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/priorityOverride" }
+        },
+        "priorityWhy": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "nextAction": { "type": "string" }
+      }
+    },
+    "item": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "slug",
+        "type",
+        "title",
+        "score",
+        "state",
+        "effort",
+        "value",
+        "completionLevel",
+        "completionLabel",
+        "effortEstimate",
+        "basePriorityScore",
+        "finalPriorityScore",
+        "priorityBand",
+        "priorityOverrides",
+        "priorityWhy",
+        "nextAction"
+      ],
+      "properties": {
+        "slug": { "type": "string" },
+        "type": {
+          "type": "string",
+          "enum": ["repo", "idea"]
+        },
+        "title": { "type": "string" },
+        "score": { "type": "number" },
+        "state": { "type": "string" },
+        "effort": { "type": "string" },
+        "value": { "type": "string" },
+        "completionLevel": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 5
+        },
+        "completionLabel": { "type": "string" },
+        "effortEstimate": {
+          "type": "string",
+          "enum": ["xs", "s", "m", "l", "xl"]
+        },
+        "basePriorityScore": { "type": "number" },
+        "finalPriorityScore": { "type": "number" },
+        "priorityBand": {
+          "type": "string",
+          "enum": ["now", "next", "later", "park"]
+        },
+        "priorityTag": { "type": "string" },
+        "priorityOverrides": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/priorityOverride" }
+        },
+        "priorityWhy": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "nextAction": { "type": "string" },
+        "language": { "type": "string" },
+        "topics": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "htmlUrl": { "type": "string" },
+        "homepage": { "type": "string" },
+        "presentationState": {
+          "type": "string",
+          "enum": ["featured", "complete", "in-progress", "salvageable", "learning", "archived", "hidden"]
+        }
+      }
+    },
+    "matrixRow": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["xs", "s", "m", "l", "xl"],
+      "properties": {
+        "xs": { "type": "number" },
+        "s": { "type": "number" },
+        "m": { "type": "number" },
+        "l": { "type": "number" },
+        "xl": { "type": "number" }
+      }
+    }
+  }
+}

package/src/cli.js

@@ -0,0 +1,103 @@
+import { runAnalyzeCommand } from './commands/analyze.js';
+import { runIngestIdeasCommand } from './commands/ingestIdeas.js';
+import { runBuildPortfolioCommand } from './commands/buildPortfolio.js';
+import { runReportCommand } from './commands/report.js';
+import { parseArgs } from './utils/args.js';
+import packageJson from '../package.json' with { type: 'json' };
+import { UsageError } from './errors.js';
+
+const GLOBAL_OPTIONS = new Set(['help', 'strict', 'version']);
+const COMMAND_OPTIONS = {
+  analyze: new Set(['as-of', 'output-dir']),
+  'ingest-ideas': new Set(['input', 'prompt', 'output-dir']),
+  'build-portfolio': new Set(['output-dir']),
+  report: new Set(['output-dir', 'output', 'format', 'policy', 'priorities', 'explain', 'quiet'])
+};
+
+export async function runCli(argv) {
+  const { positional, options } = parseArgs(argv);
+  const [command] = positional;
+  const strictMode = options.strict === true || options.strict === 'true';
+
+  if (strictMode) {
+    validateStrictOptions(command, options);
+  }
+
+  if ((options.version === true && !command) || (command === '-v' && positional.length === 1)) {
+    console.log(packageJson.version);
+    return;
+  }
+
+  switch (command) {
+    case 'analyze':
+      await runAnalyzeCommand(options);
+      return;
+    case 'ingest-ideas':
+      await runIngestIdeasCommand(options);
+      return;
+    case 'build-portfolio':
+      await runBuildPortfolioCommand(options);
+      return;
+    case 'report':
+      await runReportCommand(options);
+      return;
+    case '-v':
+      console.log(packageJson.version);
+      return;
+    case '--help':
+    case '-h':
+    case undefined:
+      printHelp();
+      return;
+    default:
+      throw new UsageError(`Invalid command: ${command}`);
+  }
+}
+
+function printHelp() {
+  console.log('github-portfolio-analyzer');
+  console.log('Usage: github-portfolio-analyzer <command> [options]');
+  console.log('  --strict               Global: fail on unknown flags (exit code 2)');
+  console.log('Commands:');
+  console.log('  analyze          Analyze GitHub repositories and build inventory outputs');
+  console.log('  ingest-ideas     Add or update manual project ideas');
+  console.log('  build-portfolio  Merge repos and ideas into the portfolio outputs');
+  console.log('  report           Generate decision-oriented portfolio reports');
+  console.log('');
+  console.log('Analyze options:');
+  console.log('  --as-of YYYY-MM-DD     Snapshot date in UTC (defaults to today UTC)');
+  console.log('  --output-dir PATH      Output directory (default: output)');
+  console.log('');
+  console.log('Ingest ideas options:');
+  console.log('  --input PATH           Input JSON file (default: ideas/input.json)');
+  console.log('  --prompt               Add ideas interactively');
+  console.log('  --output-dir PATH      Output directory (default: output)');
+  console.log('');
+  console.log('Build portfolio options:');
+  console.log('  --output-dir PATH      Output directory (default: output)');
+  console.log('');
+  console.log('Report options:');
+  console.log('  --output-dir PATH      Output directory (default: output)');
+  console.log('  --format VALUE         ascii|md|json|all (default: all)');
+  console.log('  --policy PATH          Optional policy overlay JSON file');
+  console.log('  --priorities PATH      Alias for --policy');
+  console.log('  --explain              Print NOW ranking explainability to console');
+  console.log('  --quiet                Suppress non-error logs');
+}
+
+function validateStrictOptions(command, options) {
+  const allowedOptions = new Set(GLOBAL_OPTIONS);
+  const commandOptions = COMMAND_OPTIONS[command];
+
+  if (commandOptions) {
+    for (const key of commandOptions) {
+      allowedOptions.add(key);
+    }
+  }
+
+  const unknown = Object.keys(options).filter((key) => !allowedOptions.has(key));
+  if (unknown.length > 0) {
+    const unknownFlags = unknown.map((key) => `--${key}`).join(', ');
+    throw new UsageError(`Unknown option(s): ${unknownFlags}`);
+  }
+}

package/src/commands/analyze.js

@@ -0,0 +1,172 @@
+import path from 'node:path';
+import { getEnv, requireGithubToken } from '../config.js';
+import { GithubClient } from '../github/client.js';
+import { fetchAllRepositories, normalizeRepository } from '../github/repos.js';
+import { inspectRepositoryStructure } from '../github/repo-inspection.js';
+import { classifyActivity, classifyMaturity } from '../core/classification.js';
+import { scoreRepository } from '../core/scoring.js';
+import { buildRepoTaxonomy } from '../core/taxonomy.js';
+import { writeJsonFile } from '../io/files.js';
+import { writeInventoryCsv } from '../io/csv.js';
+import { mapWithConcurrency } from '../utils/concurrency.js';
+import { resolveAsOfDate, utcNowISOString } from '../utils/time.js';
+import { printHeader } from '../utils/header.js';
+import { progress, success, error, warn, fatal } from '../utils/output.js';
+
+export async function runAnalyzeCommand(options = {}) {
+  const startTime = Date.now();
+  const env = getEnv();
+
+  let token;
+  try {
+    token = requireGithubToken(env);
+  } catch (err) {
+    fatal('GITHUB_TOKEN missing — set it in .env: GITHUB_TOKEN=your_token');
+    throw err;
+  }
+
+  const github = new GithubClient(token);
+  const asOfDate = resolveAsOfDate(typeof options['as-of'] === 'string' ? options['as-of'] : undefined);
+  const outputDir = typeof options['output-dir'] === 'string' ? options['output-dir'] : 'output';
+
+  printHeader({
+    command: 'analyze',
+    asOfDate,
+    outputDir,
+    hasToken: Boolean(token),
+    hasPolicy: false,
+  });
+
+  let user;
+  try {
+    user = await github.getAuthenticatedUser();
+  } catch (err) {
+    if (err && (err.status === 401 || err.status === 403)) {
+      fatal('GitHub authentication failed — check your GITHUB_TOKEN permissions');
+    } else if (err && err.status === 429) {
+      fatal('GitHub API rate limit exceeded — wait or use a different token');
+    }
+    throw err;
+  }
+
+  let repositories;
+  try {
+    repositories = await fetchAllRepositories(github);
+  } catch (err) {
+    if (err && (err.status === 401 || err.status === 403)) {
+      fatal('GitHub authentication failed — check your GITHUB_TOKEN permissions');
+    } else if (err && err.status === 429) {
+      fatal('GitHub API rate limit exceeded — wait or use a different token');
+    }
+    throw err;
+  }
+
+  let analyzed = 0;
+  let fallbacks = 0;
+
+  const items = await mapWithConcurrency(repositories, 5, async (repo) => {
+    analyzed++;
+    const index = String(analyzed).padStart(String(repositories.length).length, ' ');
+    const normalized = normalizeRepository(repo);
+    try {
+      progress(`Analyzing ${index}/${repositories.length}: ${repo.name}`);
+      const structuralHealth = await inspectRepositoryStructure(github, normalized);
+      const activity = classifyActivity(normalized._pushedAt, asOfDate);
+      const maturity = classifyMaturity(normalized.sizeKb);
+      const { score, scoreBreakdown } = scoreRepository(
+        { ...normalized, structuralHealth, pushedAt: normalized._pushedAt, updatedAt: normalized._updatedAt },
+        asOfDate
+      );
+      const taxonomy = buildRepoTaxonomy({
+        ...normalized,
+        structuralHealth,
+        activity,
+        maturity,
+        score
+      });
+
+      return stripInternalFields({
+        ...normalized,
+        structuralHealth,
+        activity,
+        maturity,
+        score,
+        scoreBreakdown,
+        ...taxonomy
+      });
+    } catch (err) {
+      fallbacks++;
+      error(`✗ Analyzing ${index}/${repositories.length}: ${repo.name} — structural analysis failed, using fallback`);
+      const activity = classifyActivity(normalized._pushedAt, asOfDate);
+      const maturity = classifyMaturity(normalized.sizeKb);
+      const fallbackStructuralHealth = {
+        hasReadme: false,
+        hasLicense: Boolean(normalized.hasLicense),
+        hasPackageJson: false,
+        hasTests: false,
+        hasCi: false
+      };
+      const { score, scoreBreakdown } = scoreRepository(
+        {
+          ...normalized,
+          structuralHealth: fallbackStructuralHealth,
+          pushedAt: normalized._pushedAt,
+          updatedAt: normalized._updatedAt
+        },
+        asOfDate
+      );
+      const taxonomy = buildRepoTaxonomy({
+        ...normalized,
+        structuralHealth: fallbackStructuralHealth,
+        activity,
+        maturity,
+        score
+      });
+
+      return stripInternalFields({
+        ...normalized,
+        structuralHealth: fallbackStructuralHealth,
+        activity,
+        maturity,
+        score,
+        scoreBreakdown,
+        ...taxonomy,
+        analysisErrors: [`Structural analysis failed: ${err.message}`]
+      });
+    }
+  });
+
+  items.sort((left, right) => left.fullName.localeCompare(right.fullName));
+
+  const inventoryPath = path.join(outputDir, 'inventory.json');
+
+  await writeJsonFile(inventoryPath, {
+    meta: {
+      generatedAt: utcNowISOString(),
+      asOfDate,
+      owner: user.login,
+      count: items.length
+    },
+    items
+  });
+  const inventoryCsvPath = await writeInventoryCsv(outputDir, items);
+
+  const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+
+  if (fallbacks > 0) {
+    warn(`${fallbacks} repo(s) used fallback scoring — structural inspection failed`);
+  }
+  success(`✓ Analyzed ${repositories.length} repositories (${repositories.length - fallbacks} ok${fallbacks > 0 ? `, ${fallbacks} fallback` : ''}) in ${elapsed}s`);
+  success(`✓ Wrote ${inventoryPath}`);
+  success(`✓ Wrote ${inventoryCsvPath}`);
+}
+
+function stripInternalFields(item) {
+  const output = {};
+  for (const [key, value] of Object.entries(item)) {
+    if (!key.startsWith('_')) {
+      output[key] = value;
+    }
+  }
+  return output;
+}

package/src/commands/buildPortfolio.js

@@ -0,0 +1,8 @@
+import { buildPortfolio } from '../core/portfolio.js';
+import { info, success } from '../utils/output.js';
+
+export async function runBuildPortfolioCommand(options = {}) {
+  info('Building portfolio...');
+  const result = await buildPortfolio(options);
+  success(`✓ Built portfolio — ${result.count} items → ${result.portfolioPath}`);
+}

package/src/commands/ingestIdeas.js

@@ -0,0 +1,8 @@
+import { ingestIdeas } from '../core/ideas.js';
+import { info, success } from '../utils/output.js';
+
+export async function runIngestIdeasCommand(options = {}) {
+  info('Ingesting ideas...');
+  const result = await ingestIdeas(options);
+  success(`✓ Ingested ${result.count} ideas → ${result.outputPath}`);
+}