docs: rewrite health score page for v2 methodology

[joanagmaia]

Summary

• Rewrites docs/metrics/health-score/index.md for the v2 methodology, which replaces the original four-category equal-weight model with three independent assessments: Lifecycle state, Health Score (Maintainer 40 + Security & Supply Chain 35 + Development Activity 25), and Impact Score (package-mediated, 0–100)
• Adds per-signal rubric tables with point tiers and thresholds for all 12 sub-signals across the three Health Score categories
• Documents two-layer missing-data redistribution so projects on GitLab, Gerrit, or without published packages are not penalized for unavailable signals
• Adds platform coverage section explicitly addressing GitLab, Gerrit, no-package projects, and partial multi-repo scenarios
• Adds migration comparison table (original vs current methodology) with explanation of why the original approach had structural gaps
• Links to community discussion LF Health Score v2 - adding lifecycle & impact to Insights #1939 where the methodology changes were shaped
• Fixes a pre-commit hook race condition in frontend/.husky/pre-commit where git add -u and npx lint-staged --no-stash wrote to the git index while GPG held a lock during git commit -S, silently turning docs-only commits into pure deletions of staged files. Fix: guard both eslint --fix/git add -u and lint-staged to only run when JS/TS/Vue files are staged. Also replaces npx lint-staged with pnpm exec lint-staged per workspace conventions (.claude/rules/pnpm-workspace-commands.md).

Note on hook fix scope: Copilot flagged this as an unrelated change. The hook fix was discovered while authoring this PR (docs-only commits reproducibly deleted staged files). A separate fix PR would have been blocked by the same bug. The fix is contained to one file with no logic changes beyond the file-type guards and the npx→pnpm exec swap.

Test plan

• cd frontend && pnpm docs:dev — open /docs/metrics/health-score/ and verify all three assessment sections render
• VitePress callouts (warning/info/tip) render as styled panels
• Sidebar entry still reads "Health Score"
• All internal links resolve (no 404s in the docs nav)
• Make a docs-only commit on a branch to verify the pre-commit hook no longer deletes staged files

Closes IN-1236

[Copilot]

Pull request overview

Documents Health Score v2 while adjusting frontend pre-commit behavior.

Changes:

• Documents Lifecycle, Health, and Impact assessments.
• Adds scoring rubrics and missing-data handling.
• Restricts linting hooks to JS/TS/Vue files.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 11 comments.

File	Description
frontend/docs/metrics/health-score/index.md	Rewrites Health Score methodology documentation.
frontend/.husky/pre-commit	Guards linting and staging by file type.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Suppressed comments (6)

Previously missed (1) — in code that hasn't changed since the last review.

frontend/docs/metrics/health-score/index.md:286

• This page says v2 replaces the original model, but other published docs still present v1 as current: docs/index.md:25-27 calls Health Score a single metric, docs/more/faq/index.md:22-23 and docs/more/glossary/index.md:41-43 describe four dimensions, and docs/features/community-collections/index.md:36 lists the old rating thresholds. Update those references in this migration so users do not receive contradictory methodology depending on entry point.

The original Insights Health Score was a single 0–100 value, computed as an equal-weight mean of four sub-scores: Contributors (25 pts), Popularity (25 pts), Development (25 pts), and Security and Best Practices (25 pts). The current methodology replaces that with three independent assessments and re-weighted health categories.

frontend/docs/metrics/health-score/index.md:3

• This says every project gets all three assessments, but the same page later says projects without tracked packages receive no Impact Score (line 217). Qualify the opening so users are not promised an assessment that cannot exist for many projects.

LFX Insights now surfaces **three independent assessments** for every project: a **Lifecycle state**, a **Health Score**, and an **Impact Score**. Together, these replace the previous single composite score and answer three distinct questions:

frontend/docs/metrics/health-score/index.md:19

• The current frontend cannot display this sixth state: frontend/config/trust-score.ts:54-68 maps only active/stable/declining/abandoned/archived, and health-breakdown-templates.ts:23-59 also has no inert case, so an emitted inert value appears as “Unknown” with the generic no-data description. Add inert support before documenting it as a current UI output.

| **Lifecycle** | What state is this project in? | One of six states: Active, Stable, Declining, Inert, Abandoned, Archived |

frontend/docs/metrics/health-score/index.md:154

• No development floor is defined in the detailed rubric, even though line 295 explicitly credits a “development floor” for protecting stable projects. The listed tiers instead assign zero for no commits and no closed issues, so this claim cannot be reproduced from the documentation. Specify the floor amount and eligibility rule, or remove both floor-based claims.

A finished library with no open issues, no CVEs, and a recent release can score well here without recent commits. Intentionally low-activity projects are not penalized.

frontend/.husky/pre-commit:7

• This whole-file git add -u silently stages unrelated unstaged hunks whenever a developer partially stages a JS/TS/Vue file: ESLint edits the working-tree file, then git add -u <path> adds every change in that path, not just the formatter output. Preserve and restore unstaged patches (or use lint-staged's partial-staging support) instead of force-staging the complete file.

    ([ -z "$ESLINT_FILES" ] || (pnpm exec eslint --fix $ESLINT_FILES && git add -u $(git diff --name-only --diff-filter=d --cached --relative | grep -E '\.(js|ts|vue)$'))) && \

frontend/.husky/pre-commit:23

• Use the repository's required package runner here. .claude/rules/pnpm-workspace-commands.md:7 explicitly prohibits npx; invoking it can bypass the workspace's pinned tool resolution. Replace it with pnpm exec.

  npx lint-staged --no-stash

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (5)

Previously missed (1) — in code that hasn't changed since the last review.

frontend/docs/metrics/health-score/index.md:116

• The rubric leaves low-severity advisories undefined. The first tier says 10 points requires no open vulnerabilities, but the deduction list assigns penalties only to Critical, High, and Moderate findings. Please state whether Low advisories deduct points or whether 10 points actually means no open Moderate-or-higher findings, so the score is reproducible.

- **10 pts:** No open vulnerabilities
- Points deducted per open advisory: 6 per Critical, 3 per High, 1 per Moderate (minimum 0)

frontend/.husky/pre-commit:23

• This still invokes npx, despite the PR's stated pnpm exec migration and the repository rule that commands must never use npm/npx (.claude/rules/pnpm-workspace-commands.md:7). Use the workspace-installed binary so the hook does not bypass pnpm or fetch an unexpected version.

  npx lint-staged --no-stash

frontend/.husky/pre-commit:7

• git add -u stages every working-tree change in each listed path, not just ESLint's edits. If a JS/TS/Vue file is partially staged, this silently pulls its intentionally unstaged hunks into the commit. Preserve the staged patch or run ESLint through a partial-staging-safe lint-staged setup instead of force-adding whole files.

    ([ -z "$ESLINT_FILES" ] || (pnpm exec eslint --fix $ESLINT_FILES && git add -u $(git diff --name-only --diff-filter=d --cached --relative | grep -E '\.(js|ts|vue)$'))) && \

frontend/docs/metrics/health-score/index.md:19

• The shipped lifecycle mapping currently supports only active, stable, declining, abandoned, and archived (frontend/config/trust-score.ts:54-62), and the lifecycle-description switch also lacks inert. An inert value therefore renders as “Unknown” with the generic no-data explanation. Either add application support for this documented state or do not present it as currently available.

| **Lifecycle** | What state is this project in? | One of six states: Active, Stable, Declining, Inert, Abandoned, Archived |

frontend/docs/metrics/health-score/index.md:127

• This rubric does not match the four security-practice inputs shown by the current UI. health-breakdown-templates.ts:421-426 tracks SECURITY.md, branch protection, required reviews, and required status checks; it does not track disclosure-process documentation or signed releases. Publishing different criteria makes the score impossible for users to reproduce.

- **2 pts:** `SECURITY.md` file present
- **2 pts:** Vulnerability disclosure process documented
- **2 pts:** Branch protection enabled on the default branch
- **2 pts:** Releases are cryptographically signed

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (5)

Previously missed (2) — in code that hasn't changed since the last review.

frontend/docs/metrics/health-score/index.md:51

• The documented 12-month abandonment threshold conflicts with the current UI explanation, which says “No maintainer activity in over 18 months” (frontend/config/health-breakdown-templates.ts:41-52). The linked methodology discussion also leaves the exact threshold subject to empirical validation. Confirm the scorer's actual threshold and align the documentation and UI so users do not receive contradictory criteria.

2. **Abandoned:** open issues or pull requests have received no non-author response for an extended period (90 to 180 days), and maintainers have had no activity in the last 12 months.

frontend/docs/metrics/health-score/index.md:154

• No rule in the documented Development Activity rubric gives Stable projects special treatment. A finished project with no commits, issues, or PRs receives zero for those three signals and at most 8/25 from a recent release, so the claim that it “can score well here” is not supported. Document the lifecycle-based floor/adjustment if one exists, or revise this statement.

A finished library with no open issues, no CVEs, and a recent release can score well here without recent commits. Intentionally low-activity projects are not penalized.

frontend/.husky/pre-commit:23

• npx remains here, so the hook does not implement the PR's stated npx → pnpm exec change and still violates the repository rule to never use npx (.claude/rules/pnpm-workspace-commands.md:7). Resolve the workspace-managed binary through pnpm instead.

  npx lint-staged --no-stash

frontend/docs/metrics/health-score/index.md:19

• This documents Inert as a current lifecycle output, but the current UI only maps Active, Stable, Declining, Abandoned, and Archived (frontend/config/trust-score.ts:54-68). An inert result therefore renders as Unknown with the generic no-data description. Add Inert support to the UI as part of this rollout, or avoid presenting it as currently available.

| **Lifecycle** | What state is this project in? | One of six states: Active, Stable, Declining, Inert, Abandoned, Archived |

frontend/docs/metrics/health-score/index.md:127

• This 8-point rubric does not match the v2 inputs currently exposed to the UI: the contract tracks a security policy plus branch protection enabled, required reviews, and required status checks (frontend/types/overview/responses.types.ts:114-120), with no disclosure-process or signed-release fields. The linked discussion likewise says branch-protection enforcement settings are scored. Align this table with the actual scorer, or implement the two advertised inputs before publishing them as point-earning criteria.

- **2 pts:** `SECURITY.md` file present
- **2 pts:** Vulnerability disclosure process documented
- **2 pts:** Branch protection enabled on the default branch
- **2 pts:** Releases are cryptographically signed

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Suppressed comments (2)

frontend/docs/metrics/health-score/index.md:19

• The new Inert state cannot currently be rendered as documented. frontend/config/trust-score.ts:54-68 only maps active/stable/declining/abandoned/archived, and getLifecycleDescription has no inert branch, so an inert API value appears as “Unknown” with the generic unindexed-data explanation. Add the inert mapping and description before promising this sixth state.

| **Lifecycle** | What state is this project in? | One of six states: Active, Stable, Declining, Inert, Abandoned, Archived |

frontend/.husky/pre-commit:17

• The comment still names npx lint-staged even though this change replaces the invocation with pnpm exec lint-staged. Update the rationale to match the actual command and avoid retaining a command prohibited by the workspace convention in contributor-facing hook documentation.

# Guard: only run when JS/TS/Vue files are staged. When only non-lintable
# files (e.g. .md) are staged, `npx lint-staged --no-stash` races with the
# GPG signing transaction and silently turns commits into pure deletions of
# every staged file (disk content intact). Skipping it when there is no
# matching work eliminates that race.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

Suppressed comments (10)

Previously missed (5) — in code that hasn't changed since the last review.

frontend/docs/metrics/health-score/index.md:135

• This documents an unattainable 8-point rubric. The shipped calculation caps Security Practices at 7: required reviews and status checks are 1 point each, and disabling force pushes supplies the omitted final point.

#### 2.2 Security Practices (max 8 pts)

Checks whether the repository has adopted documented security practices:

- **2 pts:** `SECURITY.md` file present
- **2 pts:** Branch protection enabled on the default branch
- **2 pts:** Required code reviews on pull requests
- **2 pts:** Required status checks before merging

frontend/docs/metrics/health-score/index.md:178

• The implementation has a fallback that is missing from this rubric: when no cleaned commit rows exist, it awards 4 points for a repository lastCommitAt under 3 months old, 2 points under 12 months, otherwise 0. Without this, readers cannot reproduce scores for the majority of repositories that use enrichment fallback data.

Counts commits authored in the last 6 months on the cleaned activity stream (bots and automation excluded).

frontend/docs/metrics/health-score/index.md:220

• Gerrit changesets are ingested into the PR analysis path, and the shipped development calculation can derive PR Merge Health from those records. It is only blocked when a repository has no PR/changeset rows, so declaring the signal unavailable for all Gerrit repositories is inaccurate.

Gerrit repositories do not ingest pull request data. This sub-signal is blocked for Gerrit-only projects and its weight redistributes within Development Activity.

frontend/docs/metrics/health-score/index.md:284

• This platform summary repeats that PR Merge Health is typically blocked, but the v2 pipeline explicitly maps Gerrit channels and analyzes changesets as PR data. Keep Issue Resolution blocked, but describe PR Merge Health as available when changeset data was ingested.

Gerrit does not ingest issue or PR data in the same format as GitHub and GitLab. Issue Resolution, PR Merge Health, and Security Practices are typically blocked. Commit Activity and Bus Factor remain available. Development Activity may compute from a reduced set of sub-signals.

frontend/docs/metrics/health-score/index.md:104

• The shipped query counts distinct organizations across all contributor activity in the last 12 months; it does not restrict the count to active maintainers. This wording overstates what the signal measures and can mislead readers when occasional contributors come from several organizations.

Measures how many distinct organizations the active maintainers are affiliated with, using contributor affiliation data. Projects maintained by contributors from multiple independent organizations are more resilient to any single organization withdrawing support.

frontend/docs/metrics/health-score/index.md:19

• The implementation can return no lifecycle state when every activity signal is unusable, so this output is not always one of the six named states. Document the unavailable case to keep consumers from treating missing data as Active.

| **Lifecycle** | What state is this project in? | One of six states: Active, Stable, Declining, Inert, Abandoned, Archived |

frontend/docs/metrics/health-score/index.md:40

• These state definitions do not match the shipped lifecycle pipe: Stable does not test maintainer reachability, Abandoned uses 12 months without any commits plus an unanswered item aged at least 90 days, and Archived only checks the repository flag. As written, users will infer classifications from signals that are not evaluated.

| **Stable** | Low activity by design. The project is mature and does not need frequent changes. Maintainers are still reachable. |
| **Declining** | Activity dropped more than 50% in the last 6 months while issue volume increased; a sign the project is under pressure |
| **Inert** | No commits in 18+ months, but no open issues or pull requests either. Nothing to judge responsiveness by. A quiet project, not a neglected one. |
| **Abandoned** | No maintainer activity in 12+ months, with open issues or pull requests that have gone unanswered for an extended period |
| **Archived** | Explicitly archived in the repository host or marked deprecated in the package registry |

frontend/docs/metrics/health-score/index.md:54

• The detailed decision tree repeats signals that the shipped pipe does not use: package deprecation/yanking is not queried, and Abandoned is based on a 12-month no-commit gate plus a 90-day unanswered item—not 18 months of maintainer inactivity. Align these rules with the calculation so readers can reproduce classifications.

1. **Archived:** the repository's archived flag is set, or the package registry marks the package as deprecated or yanked.
2. **Abandoned:** open issues or pull requests have received no non-author response for an extended period (90 to 180 days), and maintainers have had no activity in the last 18 months.
3. **Inert:** no commits in the last 18 months, and no open issues or pull requests in that window (nothing to judge responsiveness by).
4. **Declining:** commits in the last 6 months are less than 50% of the prior 6 months, and the volume of newly opened issues is higher than the prior period.
5. **Stable:** the latest release is within the last 12 months, fewer than 50 issues are open, no critical vulnerabilities are open, and commits have dropped more than 50% vs. the prior period.

frontend/docs/metrics/health-score/index.md:55

• Active is not the fallback for repositories with no usable activity signal; the lifecycle pipe returns null before evaluating the decision tree. Qualify this fallback so it agrees with the unavailable case documented above.

6. **Active:** all other projects.

frontend/docs/metrics/health-score/index.md:314

• The Health formula remains activity-based for Stable projects; the lifecycle state does not change or floor Development points. Saying these libraries are “not penalized” contradicts the methodology above and should instead explain that Stable contextualizes a potentially lower score.

| **Stable "done" libraries** | Penalized: low commits meant a low score | Not penalized: the Stable state recognizes intentionally low-activity projects |

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (7)

Previously missed (2) — in code that hasn't changed since the last review.

frontend/docs/metrics/health-score/index.md:39

• The Abandoned summary still says 12+ months, while the classification rule below and the current UI description use 18 months. Use one threshold so readers are not given two definitions of the same lifecycle state.

This issue also appears in the following locations of the same file:

• line 54
• line 291
• line 322

| **Abandoned** | No maintainer activity in 12+ months, with open issues or pull requests that have gone unanswered for an extended period |

frontend/docs/metrics/health-score/index.md:3

• Other entry points still describe the retired model: frontend/docs/index.md:25-27 calls Health Score a single unified metric, frontend/docs/more/faq/index.md:19-23 says it is a weighted sum of four dimensions, and frontend/docs/more/glossary/index.md:41-43 repeats the four-dimension composite. Update those references with this rewrite; otherwise users receive contradictory methodology depending on where they enter the docs.

LFX Insights surfaces up to **three independent assessments** for open source projects: a **Lifecycle state**, a **Health Score**, and when applicable an **Impact Score**. Together, these replace the previous single composite score and answer three distinct questions:

frontend/docs/metrics/health-score/index.md:54

• This rule can classify a project as Stable without any evidence that maintainers are reachable, contradicting the Stable definition above and the UI description in frontend/config/health-breakdown-templates.ts:27-29. Either include responsiveness in the classifier criteria or remove the reachability guarantee from the user-facing descriptions.

5. **Stable:** the latest release is within the last 12 months, fewer than 50 issues are open, no critical vulnerabilities are open, and commits have dropped more than 50% vs. the prior period.

frontend/docs/metrics/health-score/index.md:88

• “No response data available” also covers a blocked responsiveness signal, but blocked signals are redistributed rather than scored zero. The API explicitly exposes responsivenessAvailable, and the UI handles false as blocked (health-breakdown-templates.ts:303-308). Limit this zero-point tier to an available signal with no interactions so it does not contradict the missing-data policy.

- **0 pts:** Median response time 3 months or more, or no response data available

frontend/.husky/pre-commit:14

• This explanatory comment still names npx lint-staged even though the hook now invokes pnpm exec lint-staged. Refer to lint-staged generically so future debugging does not incorrectly attribute the behavior to the removed runner.

# files (e.g. .md) are staged, `npx lint-staged --no-stash` races with the

frontend/docs/metrics/health-score/index.md:322

• Under the documented original formula, Development contributed at most 25 points, so few commits alone could not reduce an otherwise healthy project to the Critical band. Describe the broader activity-based penalty instead of attributing the result solely to commits.

- **Stable libraries were penalized.** A mature utility with no bugs, no CVEs, and no need for active development scored near Critical simply because it had few recent commits.

frontend/docs/metrics/health-score/index.md:291

• The current API exposes only per-signal availability booleans and no partial-repository coverage state or counts (frontend/types/overview/responses.types.ts:91-143), so the UI cannot always show the coverage details promised here. Remove this guarantee until partial coverage is surfaced, or add the required API/UI data.

Health Score comparisons across projects with different platform or data coverage are not directly comparable. A project with full GitHub and package data is scored on more signals than one on Gerrit with no published packages. Coverage details are always shown alongside the score.

[Copilot]

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

frontend/docs/metrics/health-score/index.md:274

• The UI cannot uphold this guarantee for partial multi-repository coverage: HealthBreakdownResults exposes only project-level availability booleans, with no contributing-repository counts or partial state, and the breakdown renders no Supply Chain Integrity row at all. Remove the claim that coverage details are always shown, or add the missing API/UI coverage data before documenting it.

Health Score comparisons across projects with different platform or data coverage are not directly comparable. A project with full GitHub and package data is scored on more signals than one on Gerrit with no published packages. Coverage details are always shown alongside the score.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.

Suppressed comments (3)

Previously missed (1) — in code that hasn't changed since the last review.

frontend/docs/metrics/health-score/index.md:31

• This reintroduces the Active definition that the earlier review thread corrected. Active is the fallback when none of the other lifecycle states match; requiring both recent commits and responsiveness leaves fallback cases undocumented. Restore the fallback definition so this table matches the intended classifier.

This issue also appears on line 46 of the same file.

| **Active** | Regular commits in the last 6 months and maintainer is responsive to issues and pull requests. |

frontend/docs/metrics/health-score/index.md:46

• Poor responsiveness alone does not guarantee a low Health Score: this sub-signal is worth 15 points, so a project scoring zero here and full points elsewhere can still score 85 (Excellent). Describe the actual bounded effect rather than promising a low overall score.

The Health Score measures how well-maintained a project is, independent of how popular or critical it is. A widely-used project with poor maintainer responsiveness will score low here, even if its Impact Score is high.

frontend/.husky/pre-commit:14

• This new comment still names npx lint-staged, although the command below was deliberately changed to pnpm exec lint-staged. Update the explanation so it documents the actual command and does not reintroduce the prohibited npx form as guidance.

# files (e.g. .md) are staged, `npx lint-staged --no-stash` races with the

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

frontend/docs/metrics/health-score/index.md:35

• The bounded “90 to 180 days” interval means an item unanswered for more than 180 days no longer satisfies the documented Abandoned rule. Discussion #1939 describes 90–180 days as the candidate range for one eventual cutoff, not as a window. State the shipped rule as “at least N days” using the actual selected threshold so the classification remains valid after that point.

| **Abandoned** | Open issues or pull requests have gone unanswered for 90 to 180 days, and no maintainer activity in the last 18 months. |

frontend/docs/metrics/health-score/index.md:274

• The UI does not always show the promised coverage details. HealthBreakdownResults exposes only per-signal availability booleans, not the documented partial repository coverage or contributing-repository counts, and the breakdown omits Supply Chain Integrity entirely. Remove this guarantee unless those details are added to the API and UI.

Health Score comparisons across projects with different platform or data coverage are not directly comparable. A project with full GitHub and package data is scored on more signals than one on Gerrit with no published packages. Coverage details are always shown alongside the score.

[joanagmaia]

@jonathimer merging this one and deploying since the UI is already released - want to prevent the docs mismatching the real calculations. Feel free to still check out the documentation and suggest any further additions, improvements or fixes. We can open follow up PRs if needed