projscan 4.9.3 → 4.10.0

package/dist/utils/scoreCalculator.js

@@ -1,3 +1,9 @@
+const BASE_SCORE = 100;
+const SEVERITY_WEIGHTS = {
+    error: 20,
+    warning: 10,
+    info: 3,
+};
 /**
  * Calculate a project health score (0–100) and letter grade from detected issues.
  *
@@ -14,23 +20,78 @@
  *   F  < 60
  */
 export function calculateScore(issues) {
-    const errors = issues.filter((i) => i.severity === 'error').length;
-    const warnings = issues.filter((i) => i.severity === 'warning').length;
-    const infos = issues.filter((i) => i.severity === 'info').length;
-    const deductions = errors * 20 + warnings * 10 + infos * 3;
-    const score = Math.max(0, 100 - deductions);
-    let grade;
+    const errors = countSeverity(issues, 'error');
+    const warnings = countSeverity(issues, 'warning');
+    const infos = countSeverity(issues, 'info');
+    const uncappedPenalty = penaltyFor('error', errors) + penaltyFor('warning', warnings) + penaltyFor('info', infos);
+    const totalPenalty = Math.min(BASE_SCORE, uncappedPenalty);
+    const score = Math.max(0, BASE_SCORE - uncappedPenalty);
+    const grade = gradeForScore(score);
+    return {
+        score,
+        grade,
+        errors,
+        warnings,
+        infos,
+        scoreBreakdown: buildScoreBreakdown(issues, {
+            score,
+            grade,
+            errors,
+            warnings,
+            infos,
+            totalPenalty,
+            uncappedPenalty,
+        }),
+    };
+}
+function countSeverity(issues, severity) {
+    return issues.filter((issue) => issue.severity === severity).length;
+}
+function penaltyFor(severity, count) {
+    return count * SEVERITY_WEIGHTS[severity];
+}
+function gradeForScore(score) {
     if (score >= 90)
-        grade = 'A';
-    else if (score >= 80)
-        grade = 'B';
-    else if (score >= 70)
-        grade = 'C';
-    else if (score >= 60)
-        grade = 'D';
-    else
-        grade = 'F';
-    return { score, grade, errors, warnings, infos };
+        return 'A';
+    if (score >= 80)
+        return 'B';
+    if (score >= 70)
+        return 'C';
+    if (score >= 60)
+        return 'D';
+    return 'F';
+}
+function buildScoreBreakdown(issues, score) {
+    return {
+        baseScore: BASE_SCORE,
+        finalScore: score.score,
+        grade: score.grade,
+        totalPenalty: score.totalPenalty,
+        uncappedPenalty: score.uncappedPenalty,
+        bySeverity: {
+            error: severityBreakdown(score.errors, 'error'),
+            warning: severityBreakdown(score.warnings, 'warning'),
+            info: severityBreakdown(score.infos, 'info'),
+        },
+        byCategory: categoryBreakdown(issues),
+    };
+}
+function severityBreakdown(count, severity) {
+    const weight = SEVERITY_WEIGHTS[severity];
+    return { count, weight, penalty: count * weight };
+}
+function categoryBreakdown(issues) {
+    const categories = new Map();
+    for (const issue of issues) {
+        const category = issue.category || 'uncategorized';
+        const current = categories.get(category) ?? { count: 0, penalty: 0 };
+        current.count += 1;
+        current.penalty += SEVERITY_WEIGHTS[issue.severity];
+        categories.set(category, current);
+    }
+    return [...categories.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([category, value]) => ({ category, ...value }));
 }
 const GRADE_COLORS = {
     A: 'brightgreen',

package/dist/utils/scoreCalculator.js.map

@@ -1 +1 @@
-{"version":3,"file":"scoreCalculator.js","sourceRoot":"","sources":["../../src/utils/scoreCalculator.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,MAAe;IAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,MAAM,CAAC;IACnE,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,MAAM,CAAC;IACvE,MAAM,KAAK,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,MAAM,CAAC,CAAC,MAAM,CAAC;IAEjE,MAAM,UAAU,GAAG,MAAM,GAAG,EAAE,GAAG,QAAQ,GAAG,EAAE,GAAG,KAAK,GAAG,CAAC,CAAC;IAC3D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,GAAG,UAAU,CAAC,CAAC;IAE5C,IAAI,KAA2B,CAAC;IAChC,IAAI,KAAK,IAAI,EAAE;QAAE,KAAK,GAAG,GAAG,CAAC;SACxB,IAAI,KAAK,IAAI,EAAE;QAAE,KAAK,GAAG,GAAG,CAAC;SAC7B,IAAI,KAAK,IAAI,EAAE;QAAE,KAAK,GAAG,GAAG,CAAC;SAC7B,IAAI,KAAK,IAAI,EAAE;QAAE,KAAK,GAAG,GAAG,CAAC;;QAC7B,KAAK,GAAG,GAAG,CAAC;IAEjB,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,YAAY,GAAyC;IACzD,CAAC,EAAE,aAAa;IAChB,CAAC,EAAE,OAAO;IACV,CAAC,EAAE,QAAQ;IACX,CAAC,EAAE,QAAQ;IACX,CAAC,EAAE,KAAK;CACT,CAAC;AAEF,MAAM,UAAU,QAAQ,CAAC,KAA2B;IAClD,MAAM,KAAK,GAAG,YAAY,CAAC,KAAK,CAAC,CAAC;IAClC,OAAO,yCAAyC,KAAK,IAAI,KAAK,EAAE,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAA2B;IACvD,OAAO,uBAAuB,QAAQ,CAAC,KAAK,CAAC,iDAAiD,CAAC;AACjG,CAAC"}
+{"version":3,"file":"scoreCalculator.js","sourceRoot":"","sources":["../../src/utils/scoreCalculator.ts"],"names":[],"mappings":"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"}

package/docs/GUIDE.md

@@ -551,13 +551,14 @@ Natural follow-up to `projscan hotspots` - once hotspots tells you _which_ file
 projscan ci
 ```
 
-A CI-pipeline-friendly health gate. Runs the full health check and exits with code 1 if the score falls below a threshold. No spinners or banners - clean output for CI logs.
+A CI-pipeline-friendly health gate. Runs the full health check and exits with code 1 if the score falls below a threshold and at least one finding meets the `failOn` severity floor. No spinners or banners - clean output for CI logs.
 
 **Options:**
 
 | Flag               | Description                                      | Default                                                     |
 | ------------------ | ------------------------------------------------ | ----------------------------------------------------------- |
 | `--min-score <n>`  | Minimum passing score (0–100)                    | `minScore` from `.projscanrc`, else 70                      |
+| `--fail-on <severity>` | Lowest severity that can fail a below-threshold gate: `info`, `warning`, or `error` | `failOn` from `.projscanrc`, else `warning` |
 | `--changed-only`   | Gate only on issues in files changed vs base ref | off                                                         |
 | `--base-ref <ref>` | Git base ref for `--changed-only`                | auto (origin/main → origin/master → main → master → HEAD~1) |
 
@@ -566,7 +567,7 @@ A CI-pipeline-friendly health gate. Runs the full health check and exits with co
 ```bash
 $ projscan ci --min-score 80
 
-projscan: B (82/100) - 0 errors, 2 warnings, 1 info - PASS (threshold: 80)
+projscan: B (82/100) - 0 errors, 2 warnings, 1 info - PASS (threshold: 80, failOn: warning)
 ```
 
 <img src="npx%20projscan%20ci%20--min-score%2070.gif" alt="npx projscan ci" width="700">
@@ -574,7 +575,8 @@ projscan: B (82/100) - 0 errors, 2 warnings, 1 info - PASS (threshold: 80)
 **Exit codes:**
 
 - `0` - Score meets or exceeds the threshold
-- `1` - Score is below the threshold
+- `0` - Score is below the threshold but no finding meets the `failOn` floor
+- `1` - Score is below the threshold and at least one finding meets the `failOn` floor
 
 **JSON output** (useful for scripts):
 
@@ -582,6 +584,10 @@ projscan: B (82/100) - 0 errors, 2 warnings, 1 info - PASS (threshold: 80)
 projscan ci --min-score 70 --format json
 ```
 
+Every `ci.issues[]` item keeps the original issue fields and adds
+annotation-friendly fields: `ruleId`, `message`, primary `location`, all
+`locations`, and `remediation` when a fix hint is available.
+
 **SARIF output** (for GitHub Code Scanning or any SARIF consumer):
 
 ```bash
@@ -887,6 +893,9 @@ Use it before broader rollout. The report includes feedback questions for the fi
 ## Health Score
 
 Every `projscan doctor` and `projscan badge` run calculates a health score from 0 to 100 based on detected issues.
+`doctor --format json` and `ci --format json` include `scoreBreakdown` so scripts
+and reviewers can see the base score, per-severity weights, category penalties,
+total penalty, final score, and grade.
 
 **Scoring:**
 
@@ -909,7 +918,8 @@ Every `projscan doctor` and `projscan badge` run calculates a health score from
 The score appears in all output formats:
 
 - **Console**: Shown at the top of the doctor report
-- **JSON**: Included as `health.score` and `health.grade` fields
+- **JSON**: Included as `health.score`, `health.grade`, and `health.scoreBreakdown`
+  fields. CI uses the same structure under `ci.scoreBreakdown`.
 - **Markdown**: Shown as a heading with an auto-generated shields.io badge
 - **HTML**: Shown in the health summary card
 - **SARIF**: Not surfaced directly - SARIF is per-issue, not per-project. The score still drives `ci`'s exit code.
@@ -1005,6 +1015,7 @@ ProjScan loads a project-wide config from one of:
 ```json
 {
   "minScore": 80,
+  "failOn": "warning",
   "baseRef": "origin/main",
   "ignore": ["**/fixtures/**", "**/generated/**"],
   "scan": {
@@ -1013,6 +1024,9 @@ ProjScan loads a project-wide config from one of:
     "offline": false
   },
   "disableRules": ["missing-editorconfig", "large-*"],
+  "suppress": {
+    "hardcoded-secret": ["src/firebase.ts"]
+  },
   "severityOverrides": {
     "missing-prettier": "info"
   },
@@ -1034,12 +1048,14 @@ ProjScan loads a project-wide config from one of:
 | Field                 | Type                                             | Effect                                                                                                                                                        |
 | --------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `minScore`            | number (0–100)                                   | Default threshold for `projscan ci`. Clamped to 0–100.                                                                                                        |
+| `failOn`              | `'info' \| 'warning' \| 'error'`                 | Lowest severity that can fail a below-threshold `projscan ci` gate. Default `warning`; set `info` for legacy strictness or `error` for error-only blocking. |
 | `baseRef`             | string                                           | Default base ref for `--changed-only`.                                                                                                                        |
 | `ignore`              | string[]                                         | Extra glob patterns added to the built-in ignore list (`node_modules`, `.git`, `dist`, `build`, `coverage`, `.next`, `.nuxt`, `.cache`, `.turbo`, `.output`). |
 | `scan.includeIgnored` | boolean                                          | Explicitly include files hidden by Git ignore rules. Default `false`.                                                                                         |
 | `scan.scanEnvValues`  | boolean                                          | Explicitly read `.env*` contents during secret-pattern checks. Default `false`; `.env` files are path-only.                                                   |
 | `scan.offline`        | boolean                                          | Block projscan network-capable features: telemetry sending, `audit`, registry checks, and optional semantic model loading. Default `false`.                   |
 | `disableRules`        | string[]                                         | Silence rules by id. Exact match (`missing-prettier`) or wildcard prefix (`large-*`).                                                                         |
+| `suppress`            | `Record<string, string[]>`                       | Silence a rule only for matching paths/globs, for example `{ "hardcoded-secret": ["src/firebase.ts"] }`. Other rules still run on that file.                  |
 | `severityOverrides`   | `Record<string, 'info' \| 'warning' \| 'error'>` | Remap a rule's severity. Useful for downgrading project-specific false positives without disabling them.                                                      |
 | `reportPolicies`      | `Record<string, { reportScope?: string[]; redactPaths?: boolean }>` | Named evidence export presets selected with `--report-policy <name>` on `analyze`, `doctor`, and `ci`.                                      |
 | `hotspots.limit`      | number (1–100)                                   | Default limit for `projscan hotspots`.                                                                                                                        |
@@ -1047,6 +1063,12 @@ ProjScan loads a project-wide config from one of:
 
 Invalid JSON in a discovered config file is a hard error - projscan exits rather than silently ignoring it.
 
+Use inline suppressions for a single confirmed false positive:
+
+```ts
+const firebaseKey = "AIza..." // projscan-ignore-line hardcoded-secret -- Firebase web keys are public identifiers
+```
+
 ### Embedded config in `package.json`
 
 If you prefer to keep everything in `package.json`:
@@ -1564,8 +1586,10 @@ If you'd rather skip Code Scanning, `projscan init github-action` writes a pull-
 The `ci` command is purpose-built for pipelines:
 
 ```bash
-projscan ci                                 # Fail if score < 70 (default)
+projscan ci                                 # Fail if score < 70 and warning/error findings exist
 projscan ci --min-score 80                  # Custom threshold
+projscan ci --fail-on info                  # Legacy strictness: info can fail the gate
+projscan ci --fail-on error                 # Only errors can fail a below-threshold gate
 projscan ci --changed-only                  # Gate only on PR diff
 projscan ci --format json                   # JSON output for scripts
 projscan ci --format sarif > projscan.sarif # SARIF for any consumer
@@ -1577,9 +1601,15 @@ projscan ci --format sarif > projscan.sarif # SARIF for any consumer
 result=$(projscan ci --min-score 0 --format json)
 pass=$(echo "$result" | jq '.ci.pass')
 score=$(echo "$result" | jq '.ci.score')
-echo "Score: $score, Pass: $pass"
+fail_on=$(echo "$result" | jq -r '.ci.failOn')
+echo "Score: $score, Pass: $pass, FailOn: $fail_on"
 ```
 
+For PR annotation tooling, read `.ci.issues[]`. Each issue includes `ruleId`,
+`severity`, `message`, primary `location`, all `locations`, and `remediation`
+when available. Gate metadata lives at `.ci.failOn`, `.ci.scorePass`, and
+`.ci.severityFloorMet`.
+
 ### Tracking health over time in CI
 
 Combine `ci` with `diff` to track regressions:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "4.9.3",
+  "version": "4.10.0",
   "description": "Local code intelligence for agent-assisted engineering. Focused daily workflows for repo orientation before edits, proof before handoff or commit, and release-candidate review, with AST-backed evidence through an MCP server and CLI. Runs locally by default.",
   "type": "module",
   "main": "./dist/index.js",