Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs(commercial): security layer v2 statuses (#458)
Raghav Chamadiya0f07acd76b3a
diff --git a/docs/CODE_HEALTH.md b/docs/CODE_HEALTH.mdindex 588aa063f..2bd1407aa 100644--- a/docs/CODE_HEALTH.md+++ b/docs/CODE_HEALTH.md@@ -63,7 +63,9 @@ reproduced by `local-stash/calibrate_health_weights.py` and documented inThe final score is clamped to `[1.0, 10.0]`. The three repo-level KPIs:-- **Hotspot Health** — NLOC-weighted average over the top-25 % hotspot files.+- **Hotspot Health** — NLOC-weighted average over the files classified as+ hotspots by the git layer (high churn percentile plus minimum-activity+ floors), not a fixed top-N slice.- **Average Health** — NLOC-weighted average over all files.- **Worst Performer** — single lowest-scoring file.@@ -318,17 +320,20 @@ Per-file overrides live in `.repowise/health-rules.json`:"disabled_biomarkers": ["primitive_obsession"],"rules": [{- "glob": "tests/**/*.py",+ "path": "tests/**/*.py","disabled_biomarkers": ["large_method", "complex_method"]},{- "glob": "src/legacy/**",+ "path": "src/legacy/**","disabled_biomarkers": ["dry_violation"]}]}```+`path` holds an fnmatch-style glob over the repo-relative POSIX path+(`path_glob` and `glob` are accepted aliases).+## Incremental updates`repowise update` only re-scores the changed files. Findings and metrics fordiff --git a/docs/COMMERCIAL.md b/docs/COMMERCIAL.mdindex d538a2a8a..7b9e53b93 100644--- a/docs/COMMERCIAL.md+++ b/docs/COMMERCIAL.md@@ -119,18 +119,18 @@ the items that matter most to you can be prioritized.| Local dashboard (incl. local security pattern scan) | ✅ | ✅ || Auto-sync (hooks, watcher, webhooks) | ✅ | ✅ || Auto-generated CLAUDE.md | ✅ | ✅ |-| Graph-aware enhanced security scanning | — | ✅ *(dev)* |+| Graph-aware enhanced security scanning | — | ✅ *(GA on hosted)* || Language-specific security rulesets | — | ✅ *(dev)* || CVE-aware dependency analysis (KEV / EPSS / priority-scored) | — | ✅ *(GA on hosted)* || Usage-aware CVE triage (imports × dead code) | — | ✅ *(GA on hosted)* |-| Function-level reachability triage | — | ✅ *(planned)* |+| Function-level reachability triage | — | ✅ *(GA on hosted — per-language coverage)* || Secret detection across full git history | — | ✅ *(GA on hosted)* |-| SBOM generation (CycloneDX) + diffs | — | ✅ *(GA on hosted)* |-| Compliance reporting (PCI-DSS / SOC 2) | — | ✅ *(planned)* |-| Audit trail (in-product + JSON / CSV export) | — | ✅ *(GA on hosted — security surface)* |+| SBOM generation (CycloneDX) + VEX export + diffs | — | ✅ *(GA on hosted)* |+| Compliance reporting (PCI-DSS / SOC 2) | — | ✅ *(GA on hosted — Teams)* |+| Audit trail (in-product + JSON / CSV export + webhook stream) | — | ✅ *(GA on hosted — security surface)* || Jira / Confluence integration | — | ✅ *(rolling out)* || GitHub Enterprise / Azure DevOps / GitLab / Bitbucket | — | ✅ *(rolling out)* |-| Slack / Teams alerting | — | ✅ *(rolling out)* |+| Slack / Teams security alerting (signed webhooks) | — | ✅ *(GA on hosted — Teams)* || SAML / OIDC SSO + SCIM | — | ✅ *(rolling out)* || RBAC + multi-tenant | — | ✅ *(planned)* || Air-gapped install bundle | — | ✅ *(planned)* |@@ -146,13 +146,15 @@ the items that matter most to you can be prioritized.### 5.1 Security & Compliance-- **Security scanning layer** *(GA: local pattern scan; dev: graph-aware- enrichment)* — pattern-based detection for dangerous APIs (`eval`/`exec`,- `pickle.loads`, `shell=True`, `os.system`, hardcoded secrets, concat / f-string- SQL, `verify=False`, weak hashes) runs locally today in the dashboard's Security- view. Graph-aware enrichment — linking findings to graph nodes and surfacing them- through `get_risk` so AI agents see security context before modifying a file — is- in development.+- **Security scanning layer** *(GA: local pattern scan; GA on hosted:+ graph-aware enrichment)* — pattern-based detection for dangerous APIs+ (`eval`/`exec`, `pickle.loads`, `shell=True`, `os.system`, hardcoded secrets,+ concat / f-string SQL, `verify=False`, weak hashes) runs locally today in the+ dashboard's Security view. On the hosted platform, findings are graph-aware:+ every vulnerable import site carries hotspot and centrality context from the+ code graph (feeding a bounded priority bump), and AI agents see security+ state before modifying a file through the hosted `get_security` MCP tool and+ the security section `get_risk` attaches.- **Language-specific security rulesets** *(dev)* — rulesets built on top of theper-language dynamic-hint extractors and framework edges. For .NET, planned checksinclude `[Authorize]` coverage on controllers and Minimal API endpoints,@@ -172,24 +174,39 @@ the items that matter most to you can be prioritized.sites as clickable evidence), cross-referencing the existing parse anddead-code layers. Unmappable packages are labeled `unknown` honestly — neverguessed.-- **Function-level reachability triage** *(planned)* — the next precision step:- classifying CVEs by whether the vulnerable *function* is reachable through the- resolved call graph. Precision is language- and pattern-dependent; we report it- honestly per language rather than quoting one global number.-- **SBOM generation** *(available on the hosted platform, Pro+)* — CycloneDX 1.6- output per snapshot with per-dependency license detection and license-risk- classification, downloadable in-product, plus dependency diffs between any two- snapshots. SPDX and cross-format conversion on the extended roadmap.-- **Compliance reporting** *(planned)* — framework-mapping reports tying findings- back to specific files, owners, and decisions. Initial scope: **PCI-DSS** and- **SOC 2** control coverage. ISO 27001 Annex A and GDPR / data-residency mappings on- the extended roadmap — we'd rather ship two solid mappings than four shallow ones.+- **Function-level reachability triage** *(available on the hosted platform,+ Pro+)* — classifies CVEs by whether the advisory's affected packages or+ symbols are actually imported, crossing OSV symbol data with the per-import+ names the indexer captures. Coverage is per-ecosystem and reported honestly+ in-product: Go is import-path-reliable (the Go vulndb lists affected+ packages per advisory), PyPI / npm / cargo are assessed only when both the+ advisory and the code name symbols, and other ecosystems stay at+ package-level triage. Provably-unreachable findings are discounted, never+ hidden; nothing is ever claimed without evidence on both sides.+- **SBOM generation + VEX export** *(available on the hosted platform, Pro+)* —+ CycloneDX 1.6 SBOM per snapshot with per-dependency license detection and+ license-risk classification, downloadable in-product, plus dependency diffs+ between any two snapshots — and a CycloneDX 1.6 **VEX** document that maps+ the platform's triage, reachability, and human status decisions onto the+ standard impact-analysis states, generated fresh at download so it always+ reflects current triage. SPDX and cross-format conversion on the extended+ roadmap.+- **Compliance reporting** *(available on the hosted platform, Teams+)* —+ **PCI-DSS 4.0** and **SOC 2** control-coverage reports derived from the live+ security findings, with per-control evidence drill-ins and JSON / Markdown+ export. Framed honestly in-product and in every export: coverage signals,+ not an audit or certification — controls automated findings cannot evidence+ are marked for manual attestation rather than silently passed. ISO 27001+ Annex A and GDPR / data-residency mappings on the extended roadmap — we'd+ rather ship two solid mappings than four shallow ones.- **Audit trail** *(available on the hosted platform for the security surface,Teams+)* — security reads and actions (scans triggered, vulnerability and- secret views, SBOM exports, finding-status changes) logged insert-only with- user, IP, and timestamp, queryable in-product and exportable to JSON / CSV.- Coverage beyond the security surface (decisions, overrides) is in development;- streaming export to SIEM (Splunk / Datadog / Elastic / syslog) on the roadmap.+ secret views, SBOM / VEX exports, compliance views, finding-status changes,+ and MCP reads by AI agents) logged insert-only with user, IP, and timestamp,+ queryable in-product and exportable to JSON / CSV — plus an opt-in+ SIEM-lite stream that forwards audit events to any HTTPS endpoint as signed+ webhooks. Coverage beyond the security surface (decisions, overrides) is in+ development; native Splunk / Datadog / Elastic connectors on the roadmap.- **Secret-in-code detection** *(available on the hosted platform, Pro+)* —scanning across full git history (not just `HEAD`), with live-at-`HEAD`flagging and incremental re-scans. Only a fingerprint and a redacted preview@@ -211,8 +228,13 @@ integrations beyond this list are available on request.PR-comment bot that posts blast-radius and reviewer suggestions, and abranch-protection check that blocks merges touching hotspots without a reviewerfrom the ownership list.-- **Slack & Microsoft Teams** — alerts on hotspot drift, bus-factor warnings,- decision staleness, and security findings, routed by ownership.+- **Slack & Microsoft Teams** — security alerting is available today on the+ hosted platform (Teams+) as HMAC-signed webhooks with a Slack-compatible+ format (works with Slack, Microsoft Teams, and Mattermost inbound+ webhooks): new critical CVEs, live secrets, failed scans, and+ rotation-overdue reminders, plus the opt-in audit-event stream. Alerts on+ hotspot drift, bus-factor warnings, and decision staleness are rolling out+ on the same plumbing, routed by ownership.- **SAML / OIDC SSO** — Okta, Entra ID, Auth0, Google Workspace, generic SAML 2.0.- **SCIM provisioning** — automatic user / group lifecycle.diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.mdindex 44507a025..6faca45b7 100644--- a/docs/architecture/code-health.md+++ b/docs/architecture/code-health.md@@ -93,6 +93,8 @@ analysis/health/├── base.py # Biomarker Protocol + FileContext + BiomarkerResult├── registry.py # detector list + detect_all()├── brain_method.py+ ├── low_cohesion.py+ ├── god_class.py├── nested_complexity.py├── bumpy_road.py├── complex_method.py@@ -101,6 +103,7 @@ analysis/health/├── dry_violation.py├── untested_hotspot.py├── coverage_gap.py+ ├── coverage_gradient.py├── developer_congestion.py├── knowledge_loss.py├── hidden_coupling.py@@ -111,6 +114,9 @@ analysis/health/├── churn_risk.py├── change_entropy.py├── co_change_scatter.py+ ├── prior_defect.py+ ├── large_assertion_block.py+ ├── duplicated_assertion_block.py└── error_handling.py```@@ -749,19 +755,21 @@ User-authored (the **only** JSON file in the layer). Loaded by"disabled_biomarkers": ["primitive_obsession"],"rules": [{- "glob": "tests/**/*.py",+ "path": "tests/**/*.py","disabled_biomarkers": ["large_method", "complex_method"]},{- "glob": "src/legacy/**",+ "path": "src/legacy/**","disabled_biomarkers": ["dry_violation"]}]}```-`to_analyzer_config(file_paths)` resolves globs to per-file disabled-sets, which the engine honors in `_evaluate_file()`.+`path` is an fnmatch glob over the repo-relative POSIX path; `path_glob`+and `glob` are accepted aliases. `to_analyzer_config(file_paths)` resolves+globs to per-file disabled sets, which the engine honors in+`_evaluate_file()`.---@@ -859,10 +867,11 @@ phases may revisit; the constraints kept v1 shippable.- **No `complexity_estimate` propagation backfill.** The walker writesthe field as a side effect during the current run; old indexes don'tget touched until a re-index.-- **No PR-mode delta in v1.** `get_risk(changed_files=...)` returns the- current health score, not before/after. Phase 5.-- **No predictive ML.** `Predicted Decline` is a 3-snapshot direction- check, not a model. Phase 5.+- **No predictive ML on trends.** `Predicted Decline` is a 3-snapshot+ direction check, not a model. (Commit-level change risk is a separate,+ shipped surface: the `analysis/change_risk/` package behind+ `repowise risk` scores a commit or base..head range with a calibrated+ logistic model.)---diff --git a/packages/core/src/repowise/core/analysis/health/README.md b/packages/core/src/repowise/core/analysis/health/README.mdindex 9c0204cbe..593e0f186 100644--- a/packages/core/src/repowise/core/analysis/health/README.md+++ b/packages/core/src/repowise/core/analysis/health/README.md@@ -1,9 +1,9 @@# Code Health analysis layerFifth intelligence layer alongside Graph, Git, Docs, and Decisions. Computes a-per-file health score (1.0–10.0) from twelve deterministic biomarkers, ingests-test-coverage data, tracks repo-level KPIs over time, and surfaces refactoring-targets ranked by impact-per-effort.+per-file health score (1.0–10.0) from twenty-six deterministic biomarkers,+ingests test-coverage data, tracks repo-level KPIs over time, and surfaces+refactoring targets ranked by impact-per-effort.**Zero LLM calls.** Pure Python over tree-sitter + git data. Designed to finishin under 30 s on a 3 000-file repo (see `tests/integration/test_health_perf_benchmark.py`).@@ -87,7 +87,9 @@ expose NLOC-weighted module aggregates and accept `module:foo` targets.- `duplication/` — Rabin–Karp over tree-sitter tokens. Co-change correlationvia `git_meta_map[path]["co_change_partners_json"]`.- `biomarkers/` — one detector per file. Implements the `Biomarker`- Protocol from `biomarkers/base.py`. Twelve total in v1.+ Protocol from `biomarkers/base.py`. Twenty-six registered (see+ `biomarkers/registry.py` and `biomarkers/README.md` for the full list),+ plus three governance findings written by a separate additive pass.Each sub-package has its own `README.md` covering inputs, outputs, andextension points.diff --git a/packages/core/src/repowise/core/analysis/health/config.py b/packages/core/src/repowise/core/analysis/health/config.pyindex 5f9fc0462..eeeafcb3c 100644--- a/packages/core/src/repowise/core/analysis/health/config.py+++ b/packages/core/src/repowise/core/analysis/health/config.py@@ -80,7 +80,10 @@ class HealthConfig:for entry in raw.get("rules") or []:if not isinstance(entry, dict):continue- glob = entry.get("path") or entry.get("path_glob")+ # ``path`` is canonical; ``path_glob`` and ``glob`` are accepted+ # aliases (the docs showed ``glob`` for a while, so a silent+ # rejection here would invalidate working configs users copied).+ glob = entry.get("path") or entry.get("path_glob") or entry.get("glob")if not isinstance(glob, str) or not glob:continuedisabled_for = [diff --git a/tests/unit/health/test_health_config.py b/tests/unit/health/test_health_config.pyindex 79f6fee20..a225a043f 100644--- a/tests/unit/health/test_health_config.py+++ b/tests/unit/health/test_health_config.py@@ -75,6 +75,24 @@ def test_to_analyzer_config_shape(tmp_path: Path):assert "test/bar.py" not in pfd+def test_glob_and_path_glob_aliases_accepted(tmp_path: Path):+ """``glob`` (shown in older docs) and ``path_glob`` work like ``path``."""+ _write(+ tmp_path,+ {+ "rules": [+ {"glob": "tests/**", "disabled_biomarkers": ["large_method"]},+ {"path_glob": "src/legacy/*", "disabled_biomarkers": ["dry_violation"]},+ ]+ },+ )+ cfg = HealthConfig.load(tmp_path)+ assert [r.path_glob for r in cfg.rules] == ["tests/**", "src/legacy/*"]+ pfd = cfg.per_file_disabled(["tests/unit/test_x.py", "src/legacy/old.py"])+ assert pfd["tests/unit/test_x.py"] == {"large_method"}+ assert pfd["src/legacy/old.py"] == {"dry_violation"}++def test_malformed_file_falls_back_silently(tmp_path: Path):repowise = tmp_path / ".repowise"repowise.mkdir()