github-portfolio-analyzer 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to this project will be documented in this file.
 
 ## [Unreleased]
 
+## [1.4.0] — 2026-04-03
+
+### Added
+- Smoke tests for `--version` and `--help`
+- Analyze command integration coverage for env-token execution and generated inventory fields
+- `dormant` state in report summaries and documentation, while preserving manual `abandoned` compatibility
+
+### Changed
+- Automatic inactivity classification now returns `dormant` instead of `abandoned`
+- Repository taxonomy inference now prioritizes `experiment` before `library`, broadens `learning` signals, and classifies simple apps like clocks/calculators/games as `product`
+- Fork fallback classification now uses recent fork activity when upstream compare metadata is unavailable
+
 ## [1.3.0] — 2026-04-03
 
 ### Added

package/README.md

@@ -495,7 +495,8 @@ Each `portfolio.json.items[]` entry includes:
 
 - `type`: `repo | idea`
 - `category`: `product | tooling | library | learning | content | infra | experiment | template`
-- `state`: `idea | active | stale | abandoned | archived | reference-only`
+- `state`: `idea | active | stale | dormant | abandoned | archived | reference-only`
+- Auto-classified repository inactivity uses `dormant`; `abandoned` remains supported for manual curation.
 - `strategy`: `strategic-core | strategic-support | opportunistic | maintenance | parked`
 - `effort`: `xs | s | m | l | xl`
 - `value`: `low | medium | high | very-high`
@@ -521,11 +522,11 @@ Every repository passes through a deterministic scoring pipeline:
 flowchart LR
     subgraph top [ ]
         direction LR
-        A([repo metadata]) --> B(inferRepoCategory) --> C([category]) --> D(scoreRepository) --> E([score 0–100])
+        A([repo metadata]) --> B(inferRepoCategory) --> C([category]) --> D(scoreRepository) --> E([score 0-100])
     end
     subgraph mid [ ]
         direction RL
-        J(computePriorityBand) <-- I([effort xs–xl]) <-- H(computeEffortEstimate) <-- G([CL 0–5]) <-- F(computeCompletionLevel)
+        J(computePriorityBand) <-- I([effort xs-xl]) <-- H(computeEffortEstimate) <-- G([CL 0-5]) <-- F(computeCompletionLevel)
     end
     E --> F
     E -. feeds .-> J
@@ -606,7 +607,7 @@ final `priorityScore`, which determines the band.
 |---|---|---|
 | State boost | `active` | +10 |
 | State boost | `stale` | +5 |
-| State penalty | `abandoned` or `archived` | −20 |
+| State penalty | `dormant`, `abandoned`, or `archived` | −20 |
 | Quick-win boost | CL 1, 2, or 3 | +10 |
 | Effort penalty | `l` or `xl` | −10 |
 
@@ -614,7 +615,7 @@ final `priorityScore`, which determines the band.
 
 | Band | Range | Meaning |
 |---|---|---|
-| `park` | < 45 | Needs a decision before any investment. Abandoned, low signal, or intentionally paused. |
+| `park` | < 45 | Needs a decision before any investment. Dormant, low signal, or intentionally paused. |
 | `later` | 45–64 | Viable but not urgent. Can return when backlog has room. |
 | `next` | 65–79 | Strong candidate. High score but large effort, or active with average score. |
 | `now` | ≥ 80 | High confidence. Active project, good score, low effort — or manually pinned. |
@@ -633,7 +634,7 @@ updated 200d ago +0  (> 180 days)
 ──────────────────────────────────
 score            25
 
-state=abandoned  −20
+state=dormant    −20
 effort=xl        −10
 ──────────────────────────────────
 priorityScore    −5  → park

package/analyzer.manifest.json

@@ -1,11 +1,21 @@
 {
   "name": "github-portfolio-analyzer",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "commands": [
     { "id": "analyze" },
     { "id": "ingest-ideas" },
     { "id": "build-portfolio" },
-    { "id": "report", "flags": ["--policy", "--explain", "--output", "--format", "--quiet"] }
+    {
+      "id": "report",
+      "flags": [
+        "--policy",
+        "--explain",
+        "--output",
+        "--format",
+        "--quiet",
+        "--presentation-overrides"
+      ]
+    }
   ],
   "outputs": [
     "output/inventory.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-portfolio-analyzer",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "CLI tool to analyze GitHub repos and portfolio ideas",
   "type": "module",
   "bin": {

package/schemas/portfolio-report.schema.json

@@ -51,10 +51,11 @@
         "byState": {
           "type": "object",
           "additionalProperties": true,
-          "required": ["active", "stale", "abandoned", "archived", "idea", "reference-only"],
+          "required": ["active", "stale", "dormant", "abandoned", "archived", "idea", "reference-only"],
           "properties": {
             "active": { "type": "number" },
             "stale": { "type": "number" },
+            "dormant": { "type": "number" },
             "abandoned": { "type": "number" },
             "archived": { "type": "number" },
             "idea": { "type": "number" },

package/src/cli.js

@@ -20,7 +20,7 @@ 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'])
+  report: new Set(['output-dir', 'output', 'format', 'policy', 'priorities', 'explain', 'quiet', 'presentation-overrides'])
 };
 
 export async function runCli(argv) {
@@ -97,6 +97,8 @@ function printHelp() {
   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('  --presentation-overrides PATH');
+  console.log('                         Optional presentation overrides JSON file');
   console.log('  --explain              Print NOW ranking explainability to console');
   console.log('  --quiet                Suppress non-error logs');
 }

package/src/commands/analyze.js

@@ -22,12 +22,7 @@ export async function runAnalyzeCommand(options = {}) {
     required: [
       { key: 'githubToken', label: 'GitHub Personal Access Token' }
     ],
-    optional: [
-      { key: 'githubUsername', label: 'GitHub Username' },
-      { key: 'openaiKey', label: 'OpenAI API Key' },
-      { key: 'geminiKey', label: 'Gemini API Key' },
-      { key: 'anthropicKey', label: 'Anthropic API Key' }
-    ]
+    optional: []
   });
 
   let token;
@@ -65,7 +60,7 @@ export async function runAnalyzeCommand(options = {}) {
 
   let repositories;
   try {
-    repositories = await fetchAllRepositories(github);
+    repositories = await fetchAllRepositories(github, asOfDate);
   } catch (err) {
     if (err && (err.status === 401 || err.status === 403)) {
       fatal('GitHub authentication failed — check your GITHUB_TOKEN permissions');

package/src/commands/report.js

@@ -235,7 +235,7 @@ function computeStateAdjustment(state) {
     return 5;
   }
 
-  if (state === 'abandoned' || state === 'archived') {
+  if (state === 'dormant' || state === 'abandoned' || state === 'archived') {
     return -20;
   }
 

package/src/core/classification.js

@@ -11,7 +11,7 @@ export function classifyActivity(pushedAt, asOfDate) {
     return 'stale';
   }
 
-  return 'abandoned';
+  return 'dormant';
 }
 
 export function classifyMaturity(sizeKb) {

package/src/core/report.js

@@ -1,6 +1,6 @@
 import { utcNowISOString } from '../utils/time.js';
 
-const STATE_ORDER = ['active', 'stale', 'abandoned', 'archived', 'idea', 'reference-only'];
+const STATE_ORDER = ['active', 'stale', 'dormant', 'abandoned', 'archived', 'idea', 'reference-only'];
 const EFFORT_ORDER = ['xs', 's', 'm', 'l', 'xl'];
 const BAND_STRENGTH = {
   park: 0,
@@ -109,9 +109,9 @@ export function computePriorityBand(input) {
   } else if (state === 'stale') {
     priorityScore += 5;
     reasons.push('State boost: stale (+5)');
-  } else if (state === 'abandoned' || state === 'archived') {
+  } else if (state === 'dormant' || state === 'abandoned' || state === 'archived') {
     priorityScore -= 20;
-    reasons.push('State penalty: abandoned/archived (-20)');
+    reasons.push('State penalty: dormant/abandoned/archived (-20)');
   }
 
   if (completionLevel >= 1 && completionLevel <= 3) {
@@ -309,6 +309,7 @@ function buildByStateSummary(reportItems) {
   const summary = {
     active: 0,
     stale: 0,
+    dormant: 0,
     abandoned: 0,
     archived: 0,
     idea: 0,

package/src/core/taxonomy.js

@@ -6,13 +6,14 @@ function inferRepoCategory(repository) {
   const topics = Array.isArray(repository.topics)
     ? repository.topics.map((topic) => String(topic).toLowerCase())
     : [];
+  const nameAndTopics = [name, ...topics].join(' ');
   const all = [name, desc, ...topics].join(' ');
 
   if (/\b(prompt|note|notes|snippet|snippets|cheatsheet|doc|docs|documentation|knowledge|wiki|resource|resources|writing|content|guide|guides|cookbook)\b/.test(all)) {
     return 'content';
   }
 
-  if (/\b(learn|learning|study|exercise|exercises|course|tutorial|tutorials|practice|training|bootcamp|challenge|challenges|kata)\b/.test(all)) {
+  if (/\b(learn|learning|study|exercise|exercises|course|tutorial|tutorials|practice|training|bootcamp|challenge|challenges|kata|curriculum|syllabus)\b/.test(all)) {
     return 'learning';
   }
 
@@ -20,6 +21,10 @@ function inferRepoCategory(repository) {
     return 'template';
   }
 
+  if (/\b(poc|proof|experiment|spike|prototype|sandbox|playground)\b/.test(nameAndTopics)) {
+    return 'experiment';
+  }
+
   if (/\b(lib|library|sdk|package|npm|module|plugin|extension|addon|util|utils|helper|helpers)\b/.test(all)) {
     return 'library';
   }
@@ -28,11 +33,11 @@ function inferRepoCategory(repository) {
     return 'infra';
   }
 
-  if (/\b(poc|proof|experiment|spike|demo|prototype|sandbox|playground|try|trying)\b/.test(all)) {
+  if (/\b(demo|try|trying)\b/.test(all)) {
     return 'experiment';
   }
 
-  if (/\b(app|application|system|platform|service|api|backend|frontend|web|mobile|dashboard|portal|saas)\b/.test(all)) {
+  if (/\b(app|application|system|platform|service|api|backend|frontend|web|mobile|dashboard|portal|saas|clock|calculator|game|games|viewer|weather|timer|todo|player|tracker)\b/.test(all)) {
     return 'product';
   }
 
@@ -130,6 +135,10 @@ export function mapIdeaStatusToState(status) {
     return 'stale';
   }
 
+  if (value === 'dormant') {
+    return 'dormant';
+  }
+
   if (value === 'abandoned' || value === 'dropped') {
     return 'abandoned';
   }
@@ -154,7 +163,7 @@ function defaultRepoNextAction(state) {
     return formatNextAction('Refresh', 'execution documentation', 'README run steps are validated in a clean environment');
   }
 
-  if (state === 'abandoned') {
+  if (state === 'dormant' || state === 'abandoned') {
     return formatNextAction('Decide', 'retain or archive status', 'README contains a documented decision and rationale');
   }
 
@@ -170,7 +179,7 @@ function normalizeCategory(value) {
 }
 
 function normalizeState(value, fallback) {
-  return normalizeEnum(value, ['idea', 'active', 'stale', 'abandoned', 'archived', 'reference-only']) ?? fallback;
+  return normalizeEnum(value, ['idea', 'active', 'stale', 'dormant', 'abandoned', 'archived', 'reference-only']) ?? fallback;
 }
 
 function normalizeStrategy(value) {

package/src/github/client.js

@@ -15,6 +15,7 @@ export class GithubClient {
   constructor(token) {
     this.token = token;
     this.maxRetries = 4;
+    this._delay = sleepMs;
   }
 
   async request(path, init = {}) {
@@ -42,7 +43,7 @@ export class GithubClient {
           responseHeaders: response.headers,
           attempt
         });
-        await sleepMs(delayMs);
+        await this._delay(delayMs);
         continue;
       }
 

package/src/github/repo-inspection.js

@@ -37,8 +37,12 @@ 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);
+      try {
+        const decoded = Buffer.from(response.content, 'base64').toString('utf8');
+        return JSON.parse(decoded);
+      } catch {
+        return null;
+      }
     }
     return null;
   } catch (error) {

package/src/github/repos.js

@@ -1,17 +1,24 @@
+import { daysSince } from '../core/classification.js';
+
 const PAGE_SIZE = 100;
 
 /**
  * Classifies a fork as active or passive.
- * Active forks have commits ahead of the upstream default branch.
+ * Active forks are either ahead of the upstream default branch or recently active
+ * when upstream comparison metadata is unavailable.
  */
-export async function classifyFork(client, repo) {
+export async function classifyFork(client, repo, asOfDate = new Date().toISOString().slice(0, 10)) {
   if (!repo?.fork) {
     return null;
   }
 
   const parent = repo.parent;
+  const pushedAt = repo._pushedAt ?? repo.pushed_at ?? repo.pushedAt ?? null;
+  const isRecentlyActive = pushedAt ? daysSince(pushedAt, asOfDate) <= 90 : false;
+  const fallbackForkType = isRecentlyActive ? 'active' : 'passive';
+
   if (!parent) {
-    return 'passive';
+    return fallbackForkType;
   }
 
   const ownerLogin = repo.owner?.login ?? repo.ownerLogin;
@@ -20,7 +27,7 @@ export async function classifyFork(client, repo) {
   const branch = repo.default_branch ?? repo.defaultBranch ?? 'main';
 
   if (!ownerLogin || !parentOwner || !repo.name) {
-    return 'passive';
+    return fallbackForkType;
   }
 
   try {
@@ -30,11 +37,11 @@ export async function classifyFork(client, repo) {
 
     return (comparison?.ahead_by ?? 0) > 0 ? 'active' : 'passive';
   } catch {
-    return 'passive';
+    return fallbackForkType;
   }
 }
 
-export async function fetchAllRepositories(client) {
+export async function fetchAllRepositories(client, asOfDate = new Date().toISOString().slice(0, 10)) {
   const repositories = [];
 
   for (let page = 1; ; page += 1) {
@@ -66,7 +73,7 @@ export async function fetchAllRepositories(client) {
     const batch = forks.slice(index, index + 5);
     await Promise.all(
       batch.map(async (repository) => {
-        repository.forkType = await classifyFork(client, repository);
+        repository.forkType = await classifyFork(client, repository, asOfDate);
       })
     );
   }

package/src/io/markdown.js

@@ -109,7 +109,7 @@ function renderPortfolioSummary(payload) {
 
   lines.push('');
 
-  for (const state of ['active', 'stale', 'abandoned', 'idea']) {
+  for (const state of ['active', 'stale', 'dormant', 'abandoned', 'idea']) {
     lines.push(`## State: ${state}`);
     lines.push('');
 

package/src/utils/time.js

@@ -14,6 +14,9 @@ export function resolveAsOfDate(input) {
     if (Number.isNaN(asDate.getTime())) {
       throw new Error(`Invalid --as-of value: ${input}. Expected YYYY-MM-DD.`);
     }
+    if (asDate.toISOString().slice(0, 10) !== input) {
+      throw new Error(`Invalid --as-of value: ${input}. Date does not exist in the calendar.`);
+    }
 
     return input;
   }