github-portfolio-analyzer 1.1.0

package/src/commands/report.js

@@ -0,0 +1,202 @@
+import path from 'node:path';
+import { buildReportModel } from '../core/report.js';
+import { loadPresentationOverrides, applyPresentationOverrides } from '../core/presentationOverrides.js';
+import { readJsonFile, readJsonFileIfExists } from '../io/files.js';
+import { writeReportAscii, writeReportJson, writeReportMarkdown } from '../io/report.js';
+import { UsageError } from '../errors.js';
+import { printHeader } from '../utils/header.js';
+import { success } from '../utils/output.js';
+
+const ALLOWED_FORMATS = new Set(['ascii', 'md', 'json', 'all']);
+
+export async function runReportCommand(options = {}) {
+  const inputDir = typeof options['output-dir'] === 'string' ? options['output-dir'] : 'output';
+  const outputDir = typeof options.output === 'string' ? options.output : inputDir;
+  const formatOption = typeof options.format === 'string' ? options.format.toLowerCase() : 'all';
+  const policyPath = resolvePolicyPath(options);
+  const explain = options.explain === true;
+  const quiet = options.quiet === true || options.quiet === 'true';
+
+  if (!quiet) {
+    printHeader({
+      command: 'report',
+      outputDir,
+      hasToken: false,
+      hasPolicy: Boolean(policyPath),
+    });
+  }
+
+  if (!ALLOWED_FORMATS.has(formatOption)) {
+    throw new UsageError('Invalid --format value. Allowed values: ascii|md|json|all');
+  }
+
+  const portfolioPath = path.join(inputDir, 'portfolio.json');
+  const inventoryPath = path.join(inputDir, 'inventory.json');
+
+  const portfolio = await readJsonFile(portfolioPath).catch((error) => {
+    if (error && error.code === 'ENOENT') {
+      throw new Error(`Missing required input: ${portfolioPath}. Run build-portfolio before report.`);
+    }
+
+    throw error;
+  });
+
+  const inventory = await readJsonFileIfExists(inventoryPath);
+  const policyOverlay = await loadPolicyOverlay(policyPath);
+  const presentationOverridesPath = resolvePresentationOverridesPath(options);
+  const presentationOverrides = await loadPresentationOverrides(presentationOverridesPath);
+  const reportModel = buildReportModel(portfolio, inventory, { policyOverlay });
+
+  if (presentationOverrides.size > 0) {
+    reportModel.items = applyPresentationOverrides(reportModel.items, presentationOverrides);
+  }
+
+  const writtenPaths = [];
+
+  if (formatOption === 'json' || formatOption === 'all') {
+    writtenPaths.push(await writeReportJson(outputDir, reportModel));
+  }
+
+  if (formatOption === 'md' || formatOption === 'all') {
+    writtenPaths.push(await writeReportMarkdown(outputDir, reportModel));
+  }
+
+  if (formatOption === 'ascii' || formatOption === 'all') {
+    writtenPaths.push(await writeReportAscii(outputDir, reportModel));
+  }
+
+  if (!quiet) {
+    success(`✓ Generated portfolio decision report for ${reportModel.meta.counts.total} items`);
+    for (const filePath of writtenPaths) {
+      success(`✓ Wrote ${filePath}`);
+    }
+  }
+
+  if (formatOption === 'json') {
+    process.stdout.write(`${JSON.stringify(reportModel, null, 2)}\n`);
+  }
+
+  if (explain && !quiet) {
+    printNowExplain(reportModel);
+  }
+}
+
+function resolvePresentationOverridesPath(options) {
+  if (typeof options['presentation-overrides'] === 'string') {
+    return options['presentation-overrides'];
+  }
+  return 'priorities/presentation-overrides.json';
+}
+
+function resolvePolicyPath(options) {
+  if (typeof options.policy === 'string') {
+    return options.policy;
+  }
+
+  if (typeof options.priorities === 'string') {
+    return options.priorities;
+  }
+
+  return null;
+}
+
+async function loadPolicyOverlay(policyPath) {
+  if (!policyPath) {
+    return null;
+  }
+
+  const policy = await readJsonFile(policyPath).catch((error) => {
+    if (error && error.code === 'ENOENT') {
+      throw new Error(`Policy file not found: ${policyPath}`);
+    }
+
+    throw error;
+  });
+
+  validatePolicyOverlay(policy, policyPath);
+  return policy;
+}
+
+function validatePolicyOverlay(policy, policyPath) {
+  if (policy === null || typeof policy !== 'object' || Array.isArray(policy)) {
+    throw new Error(`Invalid policy file at ${policyPath}: expected a JSON object.`);
+  }
+
+  if (policy.version !== undefined && policy.version !== 1) {
+    throw new Error(`Invalid policy file at ${policyPath}: unsupported version ${policy.version}. Expected 1.`);
+  }
+}
+
+function printNowExplain(reportModel) {
+  const nowItems = Array.isArray(reportModel?.items)
+    ? reportModel.items.filter((item) => item.priorityBand === 'now')
+    : [];
+
+  console.log('');
+  console.log('Explain mode: NOW ranking');
+  if (nowItems.length === 0) {
+    console.log('No items in NOW band.');
+    return;
+  }
+
+  for (const item of nowItems) {
+    const boosts = (item.priorityOverrides ?? [])
+      .filter((entry) => Number(entry.boost ?? 0) !== 0)
+      .map((entry) => `${formatSignedNumber(entry.boost)} (${entry.ruleId})`);
+    const reasons = (item.priorityOverrides ?? [])
+      .map((entry) => entry.reason)
+      .filter((entry) => typeof entry === 'string' && entry.trim().length > 0);
+
+    console.log(item.slug);
+    console.log(`  Base score: ${item.basePriorityScore}`);
+    console.log(`  Repo score: ${item.score}`);
+    console.log(`  Signals: ${buildBaseSignalsLine(item)}`);
+    console.log(`  Boosts: ${boosts.length > 0 ? boosts.join(', ') : 'none'}`);
+    console.log(`  Final score: ${item.finalPriorityScore}`);
+    console.log(`  Final band: ${item.priorityBand}`);
+    console.log(`  Reason(s): ${reasons.length > 0 ? reasons.join('; ') : 'none'}`);
+    console.log(`  Next: ${item.nextAction}`);
+  }
+}
+
+function buildBaseSignalsLine(item) {
+  const state = String(item.state ?? '').toLowerCase();
+  const completionLevel = Number(item.completionLevel ?? 0);
+  const effortEstimate = String(item.effortEstimate ?? '').toLowerCase();
+
+  const stateAdjustment = computeStateAdjustment(state);
+  const completionAdjustment = completionLevel >= 1 && completionLevel <= 3 ? 10 : 0;
+  const effortAdjustment = effortEstimate === 'l' || effortEstimate === 'xl' ? -10 : 0;
+
+  return [
+    `score=${Number(item.score ?? 0)}`,
+    `state(${state || 'unknown'})=${formatSignedNumber(stateAdjustment)}`,
+    `completion(CL${completionLevel})=${formatSignedNumber(completionAdjustment)}`,
+    `effort(${effortEstimate || 'm'})=${formatSignedNumber(effortAdjustment)}`
+  ].join('; ');
+}
+
+function computeStateAdjustment(state) {
+  if (state === 'active') {
+    return 10;
+  }
+
+  if (state === 'stale') {
+    return 5;
+  }
+
+  if (state === 'abandoned' || state === 'archived') {
+    return -20;
+  }
+
+  return 0;
+}
+
+function formatSignedNumber(value) {
+  const numeric = Number(value);
+  if (!Number.isFinite(numeric)) {
+    return '+0';
+  }
+
+  return numeric >= 0 ? `+${numeric}` : String(numeric);
+}

package/src/config.js

@@ -0,0 +1,18 @@
+import dotenv from 'dotenv';
+
+dotenv.config({ quiet: true });
+
+export function getEnv() {
+  return {
+    githubToken: process.env.GITHUB_TOKEN ?? '',
+    githubUsername: process.env.GITHUB_USERNAME ?? ''
+  };
+}
+
+export function requireGithubToken(env = getEnv()) {
+  if (!env.githubToken) {
+    throw new Error('Missing GITHUB_TOKEN. Add it to your .env file before running analyze.');
+  }
+
+  return env.githubToken;
+}

package/src/core/classification.js

@@ -0,0 +1,47 @@
+const DAY_IN_MS = 24 * 60 * 60 * 1000;
+
+export function classifyActivity(pushedAt, asOfDate) {
+  const ageDays = daysSince(pushedAt, asOfDate);
+
+  if (ageDays <= 90) {
+    return 'active';
+  }
+
+  if (ageDays <= 365) {
+    return 'stale';
+  }
+
+  return 'abandoned';
+}
+
+export function classifyMaturity(sizeKb) {
+  if (sizeKb < 500) {
+    return 'experimental';
+  }
+
+  if (sizeKb <= 5000) {
+    return 'early';
+  }
+
+  if (sizeKb <= 50000) {
+    return 'structured';
+  }
+
+  return 'large';
+}
+
+export function daysSince(dateInput, asOfDate) {
+  const source = new Date(dateInput);
+  const reference = new Date(`${asOfDate}T00:00:00.000Z`);
+
+  if (Number.isNaN(source.getTime()) || Number.isNaN(reference.getTime())) {
+    return Number.POSITIVE_INFINITY;
+  }
+
+  const diffMs = reference.getTime() - source.getTime();
+  if (diffMs <= 0) {
+    return 0;
+  }
+
+  return Math.floor(diffMs / DAY_IN_MS);
+}

package/src/core/ideas.js

@@ -0,0 +1,170 @@
+import path from 'node:path';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { readJsonFileIfExists, writeJsonFile } from '../io/files.js';
+import { scoreIdea } from './scoring.js';
+import { buildIdeaTaxonomy } from './taxonomy.js';
+import { normalizeNextAction } from '../utils/nextAction.js';
+import { slugify } from '../utils/slug.js';
+import { utcNowISOString } from '../utils/time.js';
+
+export async function ingestIdeas(options = {}) {
+  const outputDir = typeof options['output-dir'] === 'string' ? options['output-dir'] : 'output';
+  const inputPath = typeof options.input === 'string' ? options.input : path.join('ideas', 'input.json');
+  const shouldPrompt = options.prompt === true;
+
+  const existingIdeas = await loadExistingIdeas(path.join(outputDir, 'ideas.json'));
+  const fromFile = await loadIdeasFromFile(inputPath);
+  const fromPrompt = shouldPrompt ? await promptIdeas() : [];
+  const incomingIdeas = [...fromFile, ...fromPrompt];
+
+  if (incomingIdeas.length === 0 && existingIdeas.length === 0) {
+    throw new Error(`No ideas to ingest. Add entries to ${inputPath} or use --prompt.`);
+  }
+
+  const merged = new Map(existingIdeas.map((item) => [item.slug, item]));
+
+  for (const rawIdea of incomingIdeas) {
+    const normalized = normalizeIdea(rawIdea);
+    const taxonomy = buildIdeaTaxonomy(normalized);
+    const scored = scoreIdea({
+      ...normalized,
+      nextAction: taxonomy.nextAction
+    });
+
+    const item = {
+      ...normalized,
+      ...taxonomy,
+      score: scored.score,
+      scoreBreakdown: scored.scoreBreakdown
+    };
+
+    merged.set(item.slug, item);
+  }
+
+  const items = Array.from(merged.values()).sort((left, right) => left.slug.localeCompare(right.slug));
+  const outputPath = path.join(outputDir, 'ideas.json');
+
+  await writeJsonFile(outputPath, {
+    meta: {
+      generatedAt: utcNowISOString(),
+      count: items.length
+    },
+    items
+  });
+
+  return { outputPath, count: items.length };
+}
+
+async function loadExistingIdeas(filePath) {
+  const value = await readJsonFileIfExists(filePath);
+  if (!value || !Array.isArray(value.items)) {
+    return [];
+  }
+
+  return value.items;
+}
+
+async function loadIdeasFromFile(filePath) {
+  const value = await readJsonFileIfExists(filePath);
+  if (!value) {
+    return [];
+  }
+
+  if (!Array.isArray(value)) {
+    throw new Error(`Ideas input must be a JSON array: ${filePath}`);
+  }
+
+  return value;
+}
+
+function normalizeIdea(inputIdea) {
+  const title = String(inputIdea?.title ?? '').trim();
+  if (!title) {
+    throw new Error('Each idea must include a non-empty title.');
+  }
+
+  const slug = slugify(inputIdea.slug || title);
+  if (!slug) {
+    throw new Error(`Unable to derive slug for idea title: ${title}`);
+  }
+
+  const nextActionRaw = typeof inputIdea.nextAction === 'string' ? inputIdea.nextAction : '';
+
+  return {
+    id: `idea:${slug}`,
+    slug,
+    title,
+    description: textOrNull(inputIdea.description),
+    problem: textOrNull(inputIdea.problem),
+    scope: textOrNull(inputIdea.scope),
+    targetUser: textOrNull(inputIdea.targetUser),
+    mvp: textOrNull(inputIdea.mvp),
+    status: textOrDefault(inputIdea.status, 'draft'),
+    tags: normalizeTags(inputIdea.tags),
+    category: textOrNull(inputIdea.category),
+    state: textOrNull(inputIdea.state),
+    strategy: textOrNull(inputIdea.strategy),
+    effort: textOrNull(inputIdea.effort),
+    value: textOrNull(inputIdea.value),
+    ...(nextActionRaw.trim().length > 0 ? { nextAction: normalizeNextAction(nextActionRaw) } : {})
+  };
+}
+
+async function promptIdeas() {
+  const rl = readline.createInterface({ input, output });
+  const results = [];
+
+  try {
+    while (true) {
+      const title = (await rl.question('Idea title (leave empty to finish): ')).trim();
+      if (!title) {
+        break;
+      }
+
+      const problem = (await rl.question('Problem: ')).trim();
+      const scope = (await rl.question('Scope: ')).trim();
+      const targetUser = (await rl.question('Target user: ')).trim();
+      const mvp = (await rl.question('MVP: ')).trim();
+      const nextAction = (await rl.question('Next action (<Verb> <target> — Done when: <measurable condition>): ')).trim();
+
+      results.push({
+        title,
+        problem,
+        scope,
+        targetUser,
+        mvp,
+        nextAction: nextAction || undefined
+      });
+    }
+  } finally {
+    rl.close();
+  }
+
+  return results;
+}
+
+function textOrNull(value) {
+  if (typeof value !== 'string') {
+    return null;
+  }
+
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function textOrDefault(value, defaultValue) {
+  const normalized = textOrNull(value);
+  return normalized ?? defaultValue;
+}
+
+function normalizeTags(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  return value
+    .map((item) => String(item).trim().toLowerCase())
+    .filter((item) => item.length > 0)
+    .sort((left, right) => left.localeCompare(right));
+}

package/src/core/portfolio.js

@@ -0,0 +1,101 @@
+import path from 'node:path';
+import { readJsonFileIfExists, writeJsonFile } from '../io/files.js';
+import { writePortfolioSummary, writeProjectMarkdownFiles } from '../io/markdown.js';
+import { buildRepoTaxonomy, buildIdeaTaxonomy } from './taxonomy.js';
+import { slugify } from '../utils/slug.js';
+import { utcNowISOString } from '../utils/time.js';
+
+export async function buildPortfolio(options = {}) {
+  const outputDir = typeof options['output-dir'] === 'string' ? options['output-dir'] : 'output';
+  const inventoryPath = path.join(outputDir, 'inventory.json');
+  const ideasPath = path.join(outputDir, 'ideas.json');
+  const portfolioPath = path.join(outputDir, 'portfolio.json');
+
+  const inventoryData = await readJsonFileIfExists(inventoryPath);
+  const ideasData = await readJsonFileIfExists(ideasPath);
+
+  const repos = Array.isArray(inventoryData?.items)
+    ? inventoryData.items.map((item) => hydrateRepoItem(item))
+    : [];
+  const ideas = Array.isArray(ideasData?.items)
+    ? ideasData.items.map((item) => hydrateIdeaItem(item))
+    : [];
+
+  const items = [...repos, ...ideas].sort((left, right) => {
+    if ((right.score ?? 0) !== (left.score ?? 0)) {
+      return (right.score ?? 0) - (left.score ?? 0);
+    }
+
+    return left.slug.localeCompare(right.slug);
+  });
+
+  const generatedAt = utcNowISOString();
+  const asOfDate = inventoryData?.meta?.asOfDate ?? null;
+
+  const payload = {
+    meta: {
+      generatedAt,
+      asOfDate,
+      count: items.length
+    },
+    items
+  };
+
+  await writeJsonFile(portfolioPath, payload);
+  await writeProjectMarkdownFiles(outputDir, items);
+  await writePortfolioSummary(outputDir, {
+    generatedAt,
+    asOfDate,
+    items
+  });
+
+  return { portfolioPath, count: items.length };
+}
+
+function hydrateRepoItem(item) {
+  const slug = slugify(item.slug || item.fullName || item.name || String(item.id));
+  const taxonomy = hasTaxonomy(item) ? pickTaxonomy(item) : buildRepoTaxonomy(item);
+
+  return {
+    ...item,
+    slug,
+    ...taxonomy,
+    type: 'repo'
+  };
+}
+
+function hydrateIdeaItem(item) {
+  const slug = slugify(item.slug || item.title || String(item.id));
+  const taxonomy = hasTaxonomy(item) ? pickTaxonomy(item) : buildIdeaTaxonomy(item);
+
+  return {
+    ...item,
+    slug,
+    ...taxonomy,
+    type: 'idea'
+  };
+}
+
+function hasTaxonomy(item) {
+  return Boolean(
+    item?.category &&
+      item?.state &&
+      item?.strategy &&
+      item?.effort &&
+      item?.value &&
+      item?.nextAction &&
+      item?.taxonomyMeta
+  );
+}
+
+function pickTaxonomy(item) {
+  return {
+    category: item.category,
+    state: item.state,
+    strategy: item.strategy,
+    effort: item.effort,
+    value: item.value,
+    nextAction: item.nextAction,
+    taxonomyMeta: item.taxonomyMeta
+  };
+}

package/src/core/presentationOverrides.js

@@ -0,0 +1,40 @@
+import { readJsonFileIfExists } from '../io/files.js';
+
+const VALID_PRESENTATION_STATES = new Set([
+  'featured',
+  'complete',
+  'in-progress',
+  'salvageable',
+  'learning',
+  'archived',
+  'hidden'
+]);
+
+export async function loadPresentationOverrides(filePath) {
+  const data = await readJsonFileIfExists(filePath);
+  if (!data) return new Map();
+
+  if (!Array.isArray(data.items)) return new Map();
+
+  const map = new Map();
+  for (const entry of data.items) {
+    const slug = typeof entry?.slug === 'string' ? entry.slug.trim() : null;
+    const state = typeof entry?.presentationState === 'string'
+      ? entry.presentationState.trim()
+      : null;
+
+    if (!slug || !state) continue;
+    if (!VALID_PRESENTATION_STATES.has(state)) continue;
+
+    map.set(slug, { presentationState: state });
+  }
+  return map;
+}
+
+export function applyPresentationOverrides(items, overridesMap) {
+  return items.map((item) => {
+    const override = overridesMap.get(item.slug);
+    if (!override) return item;
+    return { ...item, ...override };
+  });
+}