github-portfolio-analyzer 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -12,6 +12,19 @@ All notable changes to this project will be documented in this file.
 - Fallback count in analyze summary when structural inspection fails
 - Fatal error messages for missing token, auth failure, and rate limit
 
+## [1.2.0] — 2026-04-02
+
+### Added
+- `inferRepoCategory()` em `taxonomy.js`: inferência de categoria por heurística de nome, descrição e topics — detecta content, learning, template, library, infra, experiment, product; fallback: tooling
+- `CATEGORY_WEIGHTS` em `scoring.js`: pesos de scoring distintos por categoria — `hasLicense` e `hasTests` zerados para content/learning/experiment, baselines altos para experiment (45), learning (35), template (30) e content (25)
+- `category` exposto no output de `buildReportModel` em `report.js` — consumers do report (worker, frontend) agora recebem essa informação
+- `docs/SCORING_MODEL.md`: documentação completa com tabela de pesos, exemplos end-to-end por categoria, e seção para agentes/LLMs
+- Seção de scoring v2 no `AGENT_GUIDE.md`
+
+### Changed
+- `scoreRepository` agora lê `repository.category` para selecionar os pesos corretos; fallback para `tooling` se category ausente ou inválida
+- `sources.category` em `buildRepoTaxonomy` retorna `'inferred'` em vez de `'default'`
+
 ## [1.0.0] — 2026-03-31
 
 ### Added

package/README.md

@@ -98,14 +98,17 @@ Design goals:
 
 ## Installation
 
-Install dependencies and run the CLI locally:
+```bash
+npm install -g github-portfolio-analyzer
+```
+
+Verify the installation:
 
 ```bash
-npm install
 github-portfolio-analyzer --version
 ```
 
-If the global binary is not available yet, use:
+If the global binary is not available, run directly:
 
 ```bash
 node bin/github-portfolio-analyzer.js --version
@@ -497,7 +500,7 @@ Each `portfolio.json.items[]` entry includes:
 - `effort`: `xs | s | m | l | xl`
 - `value`: `low | medium | high | very-high`
 - `nextAction`: `"<Verb> <target> — Done when: <measurable condition>"`
-- `taxonomyMeta`: per-field provenance (`default | user | inferred`)
+- `taxonomyMeta`: per-field provenance (`default | user | inferred`). For repositories, `sources.category` is always `user` (when set manually) or `inferred` (heuristic) — never `default`.
 
 `inventory.json.items[]` includes the same taxonomy fields and `taxonomyMeta` for repositories.
 
@@ -508,50 +511,133 @@ Each `portfolio.json.items[]` entry includes:
 - `meta` (generatedAt, asOfDate, owner, counts)
 - `summary` (state counts, top10 by score, now/next/later/park)
 - `matrix.completionByEffort` (`CL0..CL5` by `xs..xl`)
-- `items[]` with decision fields (`completionLevel`, `effortEstimate`, `priorityBand`, `priorityWhy`)
+- `items[]` with decision fields (`completionLevel`, `effortEstimate`, `priorityBand`, `priorityWhy`, `category`)
 
 ## Decision Model (Report)
 
+Every repository passes through a deterministic scoring pipeline:
+
+```mermaid
+flowchart LR
+    subgraph top [ ]
+        direction LR
+        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)
+    end
+    E --> F
+    E -. feeds .-> J
+    G -. feeds .-> J
+    J --> park([park]) & later([later]) & next([next]) & now([now])
+```
+
+### Score
+
+Each repository receives a score from 0 to 100 based on observable signals.
+Signal weights depend on the project's **category**, inferred automatically
+from its name, description, and GitHub topics.
+
+| Signal | product | tooling | library | content | learning | infra | experiment | template |
+|---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| baseline | — | — | — | **25** | **35** | — | **45** | **30** |
+| pushed (90d) | 25 | 25 | 20 | 25 | 20 | 25 | 20 | 10 |
+| README | 15 | 15 | 20 | 15 | 15 | 20 | 15 | **25** |
+| license | 10 | 10 | **20** | ✗ | ✗ | 10 | ✗ | 10 |
+| tests | 25 | 20 | **25** | ✗ | ✗ | 10 | ✗ | 5 |
+| stars > 1 | 5 | 5 | 10 | 5 | 5 | 5 | 5 | 10 |
+| updated (180d) | 20 | 25 | 5 | **30** | **25** | **30** | 15 | 10 |
+
+`✗` = irrelevant for this category (weight 0). `library` penalizes missing
+license most heavily. `experiment` and `learning` skip tests and license entirely.
+
+Example — a `content` repo with no license and no tests still scores 95:
+
+```
+"prompt-library"  category: content
+────────────────────────────────────
+baseline          +25
+pushed 10d ago    +25
+has README        +15
+has license        +0  (irrelevant for content)
+has tests          +0  (irrelevant for content)
+updated this month +30
+────────────────────────────────────
+score              95
+```
+
+See [docs/SCORING_MODEL.md](docs/SCORING_MODEL.md) for the full weight table
+and numeric examples for every category.
+
 ### Completion Level
 
-- `CL0`: no README
-- `CL1`: has README
-- `CL2`: has package.json, or non-JS repo with size >= 500 KB
-- `CL3`: CL2 + CI
-- `CL4`: CL3 + tests
-- `CL5`: CL4 + score >= 70
-- Ideas default to `CL0`
+Reflects structural maturity, regardless of category. Ideas always default to CL 0.
 
-### Effort Estimate
+| CL | Label | Condition |
+|---|---|---|
+| 0 | Concept only | no README, or `type: idea` |
+| 1 | Documented | has README |
+| 2 | Structured baseline | has `package.json` (or non-JS repo ≥ 500 KB) |
+| 3 | Automated workflow | CL 2 + CI |
+| 4 | Tested workflow | CL 3 + tests |
+| 5 | Production-ready candidate | CL 4 + score ≥ 70 |
 
-Uses taxonomy `effort` unless `effort` source is `default`.
-If defaulted, infer by size and completion:
+### Effort Estimate
 
-- `xs`: size < 100 KB and CL <= 2
-- `s`: size < 500 KB and CL <= 3
-- `m`: size < 5000 KB
-- `l`: size < 20000 KB
-- `xl`: size >= 20000 KB
+How much work remains to bring a project to its next meaningful state.
+Inferred automatically from repository size and completion level when not set manually.
+`effortEstimate` is a report-only field — it never overwrites the taxonomy `effort`.
 
-`effortEstimate` is a report field only; it does not overwrite taxonomy `effort`.
+| Estimate | Size | CL | What it means |
+|---|---|---|---|
+| `xs` | < 100 KB | ≤ 2 | A few hours. Easy to restart from scratch. |
+| `s` | < 500 KB | ≤ 3 | A day or two. Focused sprint. |
+| `m` | < 5 MB | any | About a week. Needs planning. |
+| `l` | < 20 MB | any | Multiple weeks. Real commitment required. |
+| `xl` | ≥ 20 MB | any | A long-term project. Strategic investment. |
 
 ### Priority Band
 
-Internal score calculation:
+The base score is adjusted by state, completion, and effort to produce a
+final `priorityScore`, which determines the band.
 
-- base: `score`
-- `+10` if state `active`
-- `+5` if state `stale`
-- `-20` if state `abandoned` or `archived`
-- `+10` if completion is CL1..CL3
-- `-10` if effortEstimate is `l` or `xl`
+| Modifier | Condition | Effect |
+|---|---|---|
+| State boost | `active` | +10 |
+| State boost | `stale` | +5 |
+| State penalty | `abandoned` or `archived` | −20 |
+| Quick-win boost | CL 1, 2, or 3 | +10 |
+| Effort penalty | `l` or `xl` | −10 |
+
+`priorityScore` has no lower bound — it can go negative.
+
+| Band | Range | Meaning |
+|---|---|---|
+| `park` | < 45 | Needs a decision before any investment. Abandoned, 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. |
 
-Band mapping:
+Example — modifiers can push a `park`-bound project below zero:
 
-- `now`: >= 80
-- `next`: 65..79
-- `later`: 45..64
-- `park`: < 45
+```
+"old-monolith"  category: product
+──────────────────────────────────
+baseline         0
+pushed 400d ago +0   (> 90 days)
+has README      +15
+has license     +10
+no tests        +0
+updated 200d ago +0  (> 180 days)
+──────────────────────────────────
+score            25
+
+state=abandoned  −20
+effort=xl        −10
+──────────────────────────────────
+priorityScore    −5  → park
+```
 
 ## Determinism and Time Rules
 
@@ -654,10 +740,13 @@ npm test
 Coverage includes:
 
 - activity/maturity/scoring boundaries
+- category inference from repository name, description, and topics
+- category-aware scoring weights and category preservation for user-specified values
 - taxonomy presence and provenance behavior
 - `nextAction` validation and normalization
 - portfolio merge determinism
 - report completion logic, priority mapping, and deterministic model generation
+- `category` propagation to report items and all summary bands
 
 ## Troubleshooting
 

package/analyzer.manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "github-portfolio-analyzer",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "commands": [
     { "id": "analyze" },
     { "id": "ingest-ideas" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "github-portfolio-analyzer",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "CLI tool to analyze GitHub repos and portfolio ideas",
   "type": "module",
   "bin": {
@@ -17,7 +17,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/paulo-raoni/github-portfolio-analyzer.git"
+    "url": "git+https://github.com/paulo-raoni/github-portfolio-analyzer.git"
   },
   "files": [
     "bin/",

package/schemas/portfolio-report.schema.json

@@ -176,7 +176,11 @@
           "type": "array",
           "items": { "type": "string" }
         },
-        "nextAction": { "type": "string" }
+        "nextAction": { "type": "string" },
+        "category": {
+          "type": "string",
+          "enum": ["product", "tooling", "library", "learning", "content", "infra", "experiment", "template"]
+        }
       }
     },
     "item": {
@@ -244,6 +248,10 @@
         },
         "htmlUrl": { "type": "string" },
         "homepage": { "type": "string" },
+        "category": {
+          "type": "string",
+          "enum": ["product", "tooling", "library", "learning", "content", "infra", "experiment", "template"]
+        },
         "presentationState": {
           "type": "string",
           "enum": ["featured", "complete", "in-progress", "salvageable", "learning", "archived", "hidden"]

package/src/commands/analyze.js

@@ -73,17 +73,22 @@ export async function runAnalyzeCommand(options = {}) {
       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
+        maturity
       });
+      const { score, scoreBreakdown } = scoreRepository(
+        {
+          ...normalized,
+          structuralHealth,
+          pushedAt: normalized._pushedAt,
+          updatedAt: normalized._updatedAt,
+          category: taxonomy.category
+        },
+        asOfDate
+      );
 
       return stripInternalFields({
         ...normalized,
@@ -106,22 +111,22 @@ export async function runAnalyzeCommand(options = {}) {
         hasTests: false,
         hasCi: false
       };
+      const taxonomy = buildRepoTaxonomy({
+        ...normalized,
+        structuralHealth: fallbackStructuralHealth,
+        activity,
+        maturity
+      });
       const { score, scoreBreakdown } = scoreRepository(
         {
           ...normalized,
           structuralHealth: fallbackStructuralHealth,
           pushedAt: normalized._pushedAt,
-          updatedAt: normalized._updatedAt
+          updatedAt: normalized._updatedAt,
+          category: taxonomy.category
         },
         asOfDate
       );
-      const taxonomy = buildRepoTaxonomy({
-        ...normalized,
-        structuralHealth: fallbackStructuralHealth,
-        activity,
-        maturity,
-        score
-      });
 
       return stripInternalFields({
         ...normalized,

package/src/core/report.js

@@ -200,7 +200,8 @@ export function buildReportModel(portfolioData, inventoryData = null, options =
       ...(item.language != null ? { language: item.language } : {}),
       ...(Array.isArray(item.topics) && item.topics.length > 0 ? { topics: item.topics } : {}),
       ...(item.htmlUrl != null ? { htmlUrl: item.htmlUrl } : {}),
-      ...(item.homepage != null ? { homepage: item.homepage } : {})
+      ...(item.homepage != null ? { homepage: item.homepage } : {}),
+      ...(item.category != null ? { category: item.category } : {})
     };
   });
 
@@ -362,7 +363,8 @@ function toSummaryItem(item) {
     ...(item.priorityTag ? { priorityTag: item.priorityTag } : {}),
     priorityOverrides: item.priorityOverrides,
     priorityWhy: item.priorityWhy,
-    nextAction: item.nextAction
+    nextAction: item.nextAction,
+    ...(item.category != null ? { category: item.category } : {})
   };
 }
 

package/src/core/scoring.js

@@ -1,8 +1,49 @@
 import { daysSince } from './classification.js';
 
+const CATEGORY_WEIGHTS = {
+  product: {
+    pushedWithin90Days: 25, hasReadme: 15, hasLicense: 10,
+    hasTests: 25, starsOverOne: 5, updatedWithin180Days: 20, baseline: 0
+  },
+  tooling: {
+    pushedWithin90Days: 25, hasReadme: 15, hasLicense: 10,
+    hasTests: 20, starsOverOne: 5, updatedWithin180Days: 25, baseline: 0
+  },
+  library: {
+    pushedWithin90Days: 20, hasReadme: 20, hasLicense: 20,
+    hasTests: 25, starsOverOne: 10, updatedWithin180Days: 5, baseline: 0
+  },
+  content: {
+    pushedWithin90Days: 25, hasReadme: 15, hasLicense: 0,
+    hasTests: 0, starsOverOne: 5, updatedWithin180Days: 30, baseline: 25
+  },
+  learning: {
+    pushedWithin90Days: 20, hasReadme: 15, hasLicense: 0,
+    hasTests: 0, starsOverOne: 5, updatedWithin180Days: 25, baseline: 35
+  },
+  infra: {
+    pushedWithin90Days: 25, hasReadme: 20, hasLicense: 10,
+    hasTests: 10, starsOverOne: 5, updatedWithin180Days: 30, baseline: 0
+  },
+  experiment: {
+    pushedWithin90Days: 20, hasReadme: 15, hasLicense: 0,
+    hasTests: 0, starsOverOne: 5, updatedWithin180Days: 15, baseline: 45
+  },
+  template: {
+    pushedWithin90Days: 10, hasReadme: 25, hasLicense: 10,
+    hasTests: 5, starsOverOne: 10, updatedWithin180Days: 10, baseline: 30
+  }
+};
+
+const DEFAULT_WEIGHTS = CATEGORY_WEIGHTS.tooling;
+
 export function scoreRepository(repository, asOfDate) {
-  let score = 0;
+  const category = repository.category ?? 'tooling';
+  const weights = CATEGORY_WEIGHTS[category] ?? DEFAULT_WEIGHTS;
+
+  let score = weights.baseline ?? 0;
   const breakdown = {
+    baseline: weights.baseline ?? 0,
     pushedWithin90Days: 0,
     hasReadme: 0,
     hasLicense: 0,
@@ -11,34 +52,34 @@ export function scoreRepository(repository, asOfDate) {
     updatedWithin180Days: 0
   };
 
-  if (daysSince(repository.pushedAt, asOfDate) <= 90) {
-    score += 30;
-    breakdown.pushedWithin90Days = 30;
+  if (weights.pushedWithin90Days > 0 && daysSince(repository.pushedAt, asOfDate) <= 90) {
+    score += weights.pushedWithin90Days;
+    breakdown.pushedWithin90Days = weights.pushedWithin90Days;
   }
 
-  if (repository.structuralHealth?.hasReadme) {
-    score += 15;
-    breakdown.hasReadme = 15;
+  if (weights.hasReadme > 0 && repository.structuralHealth?.hasReadme) {
+    score += weights.hasReadme;
+    breakdown.hasReadme = weights.hasReadme;
   }
 
-  if (repository.structuralHealth?.hasLicense) {
-    score += 10;
-    breakdown.hasLicense = 10;
+  if (weights.hasLicense > 0 && repository.structuralHealth?.hasLicense) {
+    score += weights.hasLicense;
+    breakdown.hasLicense = weights.hasLicense;
   }
 
-  if (repository.structuralHealth?.hasTests) {
-    score += 20;
-    breakdown.hasTests = 20;
+  if (weights.hasTests > 0 && repository.structuralHealth?.hasTests) {
+    score += weights.hasTests;
+    breakdown.hasTests = weights.hasTests;
   }
 
-  if ((repository.stargazersCount ?? 0) > 1) {
-    score += 5;
-    breakdown.starsOverOne = 5;
+  if (weights.starsOverOne > 0 && (repository.stargazersCount ?? 0) > 1) {
+    score += weights.starsOverOne;
+    breakdown.starsOverOne = weights.starsOverOne;
   }
 
-  if (daysSince(repository.updatedAt, asOfDate) <= 180) {
-    score += 20;
-    breakdown.updatedWithin180Days = 20;
+  if (weights.updatedWithin180Days > 0 && daysSince(repository.updatedAt, asOfDate) <= 180) {
+    score += weights.updatedWithin180Days;
+    breakdown.updatedWithin180Days = weights.updatedWithin180Days;
   }
 
   return {

package/src/core/taxonomy.js

@@ -1,17 +1,57 @@
 import { formatNextAction, normalizeNextAction } from '../utils/nextAction.js';
 
+function inferRepoCategory(repository) {
+  const name = String(repository.name ?? '').toLowerCase();
+  const desc = String(repository.description ?? '').toLowerCase();
+  const topics = Array.isArray(repository.topics)
+    ? repository.topics.map((topic) => String(topic).toLowerCase())
+    : [];
+  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)) {
+    return 'learning';
+  }
+
+  if (/\b(template|templates|boilerplate|starter|scaffold|skeleton|seed|base|init)\b/.test(all)) {
+    return 'template';
+  }
+
+  if (/\b(lib|library|sdk|package|npm|module|plugin|extension|addon|util|utils|helper|helpers)\b/.test(all)) {
+    return 'library';
+  }
+
+  if (/\b(infra|infrastructure|docker|kubernetes|k8s|ci|cd|pipeline|deploy|devops|ansible|terraform|nginx|proxy)\b/.test(all)) {
+    return 'infra';
+  }
+
+  if (/\b(poc|proof|experiment|spike|demo|prototype|sandbox|playground|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)) {
+    return 'product';
+  }
+
+  return 'tooling';
+}
+
 export function buildRepoTaxonomy(repository) {
   const activityState = repository.activity;
   const state = repository.archived ? 'archived' : normalizeState(activityState, 'active');
 
-  const category = 'tooling';
+  const userCategory = normalizeCategory(repository.category);
+  const category = userCategory ?? inferRepoCategory(repository);
   const strategy = 'maintenance';
   const effort = 'm';
   const value = 'medium';
   const nextAction = defaultRepoNextAction(state);
 
   const sources = {
-    category: 'default',
+    category: userCategory ? 'user' : 'inferred',
     state: repository.archived ? 'inferred' : 'inferred',
     strategy: 'default',
     effort: 'default',

package/src/io/report.js

@@ -108,7 +108,8 @@ function renderAsciiBandSection(title, items) {
   }
 
   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}`);
+    const categoryPrefix = item.category == null ? '' : `[${item.category}] `;
+    lines.push(`${index + 1}) ${categoryPrefix}${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}`);
   });
@@ -129,7 +130,8 @@ function renderMarkdownBandSection(title, items) {
   }
 
   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}`);
+    const categoryPrefix = item.category == null ? '' : `\`${item.category}\` `;
+    lines.push(`${index + 1}. ${categoryPrefix}**${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}`);
   });