Sentinel Risk
Sentinel Risk is an offline, language-agnostic static analysis engine built as a
VS Code extension.
It helps developers identify bug-prone and hard-to-maintain code early by
analyzing control flow, complexity, and mutation patterns — not formatting rules.
🚫 Not a linter
🚫 Not a formatter
✅ A risk-based static analysis extension
🎯 Vision
Most tools tell you what rule you broke.
Sentinel Risk focuses on why your code is risky.
It highlights:
- complex decision logic
- deeply nested control flow
- unsafe state mutation
All offline, fast, and language-agnostic.
🚀 Current Status
Phase 5.3 — Status Bar Risk Indicator (COMPLETED)
Sentinel Risk now provides precise, line-level warnings directly inside the editor
and is ready for public publishing.
🧩 Development Phases (Tracked)
✅ Phase 1 — Foundation (COMPLETED)
✔ VS Code extension scaffold
✔ Tree-sitter integration
✔ JavaScript / TypeScript parsing
✔ Universal Syntax Tree (UST) abstraction
✔ Centralized logging system
✅ Phase 2 — Core Analysis Engine (COMPLETED)
Phase 2.1 — UST Traversal
✔ Language-agnostic traversal utilities
Phase 2.2 — Cyclomatic Complexity
✔ Counts logical decision paths
Phase 2.3 — Control-Flow / Nesting Depth
✔ Human-perceived nesting depth
Phase 2.4 — Mutation / Reassignment Risk
✔ Detects state mutation & reassignment
Phase 2.5 — Rule Engine
✔ Unified execution of all analysis rules
📌 Outcome:
A complete, reusable, language-agnostic static analysis engine.
✅ Phase 3.1 — Diagnostics & Problems Panel (COMPLETED)
✔ VS Code Problems panel integration
✔ Severity-based diagnostics
✔ File-level warnings
✔ Runs automatically on file save
✔ No configuration required
📌 Outcome:
Sentinel Risk now provides immediate, visible feedback to developers.
✅ Phase 3.2 — Line-Level Diagnostics (COMPLETED)
✔ Precise squiggly highlights on risky code
✔ Diagnostics linked to exact source locations
✔ Click-to-jump navigation from Problems panel
✔ No diagnostic noise
📌 Outcome:
Developers can immediately see where the risk exists in the code.
✅ Phase 3.3 — Hover Explanations (COMPLETED)
✔ Rich hover tooltips for diagnostics
✔ Clear explanations of why code is risky
✔ Rule-driven, language-agnostic guidance
✔ Zero configuration required
📌 Outcome:
Sentinel Risk now explains what is risky and why, directly in the editor.
✅ Phase 4.1 — Adapter Interface & Registry (COMPLETED)
✔ Formal language adapter contract
✔ Central adapter registry
✔ Language selection via VS Code languageId
✔ No rule or UI changes required
📌 Outcome:
Sentinel Risk now supports plug-and-play language adapters.
✅ Phase 4.2 — Universal Adapter Registry (COMPLETED)
✔ Capability-based adapter selection
✔ Priority resolution (FULL → PARTIAL → BASIC)
✔ Future-proof adapter dispatch
✔ No rule or UI changes
📌 Outcome:
Sentinel Risk can now intelligently select the best available adapter for a file.
✅ Phase 4.3 — Generic Fallback Adapter (COMPLETED)
✔ Sentinel Risk now runs on ANY language
✔ Heuristic-based analysis when AST is unavailable
✔ Graceful degradation with LOW confidence tagging
✔ No silent skips or crashes
📌 Outcome:
Sentinel Risk provides best-effort risk detection across all file types.
✅ Phase 4.4 — Strategy-Based Centralized Parsing (COMPLETED)
✔ Sentinel Risk no longer depends on language-specific parsers
✔ Centralized parsing pipeline with multiple strategies
✔ Heuristic analysis enabled by default for all languages
✔ Optional AST strategies can enhance accuracy without blocking usage
📌 Outcome:
Sentinel Risk is now a true centralized, ready-to-use static analysis tool.
✅ Phase 5 — Risk Scoring & Severity (COMPLETED)
✔ Unified risk score per file
✔ Clear severity levels (LOW / MEDIUM / HIGH)
✔ Weighted risk model based on real bug patterns
✔ Problems panel now prioritizes risky files
📌 Outcome:
Developers can immediately understand how risky a file is, not just individual metrics.
✅ Phase 5.2 — File-Level Risk Summary (COMPLETED)
✔ Single file-level risk diagnostic
✔ Aggregated risk score & severity shown at top of file
✔ Problems panel now prioritizes risky files
✔ Line-level diagnostics preserved
📌 Outcome:
Developers can instantly understand overall file risk before
reviewing individual warnings.
✅ Phase 5.3 — Status Bar Risk Indicator (COMPLETED)
✔ Live file-level risk indicator in VS Code status bar
✔ Color-coded severity (LOW / MEDIUM / HIGH)
✔ Updates automatically on file save
✔ Click-to-open Problems panel
📌 Outcome:
Developers can see code risk instantly, without leaving the editor.
🔢 Risk Scoring Model
Sentinel Risk combines all detected signals into a single risk score.
| Metric |
Contribution |
| Cyclomatic Complexity |
+1 per decision |
| Control-Flow Depth |
+2 per level |
| Mutation Inside Loops |
+3 per mutation |
Severity Levels
| Score |
Severity |
| 0–4 |
LOW |
| 5–9 |
MEDIUM |
| 10+ |
HIGH |
📊 Metrics Implemented
| Metric |
Description |
| Cyclomatic Complexity |
Decision path complexity |
| Control-Flow Depth |
Logical nesting depth |
| Mutation Risk |
State reassignment & mutation in loops |
| Rule Engine |
Unified rule execution |
🖥 What Users See
- ⚠ Problems panel warnings
- ✨ Line-level squiggly highlights
- 💡 Hover explanations with reasoning
- 🔗 Click-to-jump navigation
- ⚡ Instant feedback on save
- 🚦 File-level risk severity (LOW / MEDIUM / HIGH)
- 📌 File-level risk summary in Problems panel
- 🚦 Live risk indicator in the status bar
No logs. No debug mode. Just results.
🌍 What “Works on All Languages” Means
| Strategy |
Coverage |
Confidence |
| Heuristic |
All languages |
🔴 Low |
| Structural |
Most languages |
🟡 Medium |
| AST (optional) |
Popular languages |
🟢 High |
Sentinel Risk never crashes and never silently skips files.
Instead, it provides the best possible signal for every language.
🌍 Supported Languages
| Language |
Support Level |
| JavaScript / TypeScript |
🟢 Full (AST) |
| Python |
🔜 Planned |
| PHP |
🔜 Planned |
| Java |
🔜 Planned |
| All others |
🔴 Basic (Heuristic) |
Sentinel Risk supports all languages by default using heuristic analysis.
Accuracy automatically improves when better parsing strategies are available.
🏗 Architecture Overview
VS Code Editor
↓
Language Detection (languageId)
↓
Adapter Registry (Capability-Aware)
├── AST Adapter (FULL / 🟢 High Confidence)
│ ├── JavaScript / TypeScript
│ ├── (Python – planned)
│ ├── (PHP – planned)
│
└── Generic Fallback Adapter (BASIC / 🔴 Low Confidence)
├── Any unsupported or unknown language
├── Heuristic-based parsing
└── Safe, best-effort analysis
↓
Strategy Selector
├── Heuristic Strategy (default)
├── Structural Strategy (optional)
└── AST Strategy (optional)
↓
Universal Syntax Tree (UST)
├── type
├── children
├── startPosition (row, column)
└── endPosition (row, column)
↓
Rule Engine (Language-Agnostic)
├── Cyclomatic Complexity
├── Control-Flow Depth
└── Mutation Risk
↓
Rule Results (+ Confidence Level)
├── HIGH → AST-based
└── LOW → Heuristic-based
↓
Editor UI
├── Problems Panel
├── Line-Level Highlights
├── Hover Explanations
└── Quick Fix Suggestions
🔑 Architecture Principles
- Rules are written once and reused across all languages
- Parsing is language-specific, analysis is not
- UST contains only raw syntax positions, never editor concepts
- Confidence is explicit, never implied
- Graceful degradation over silent failure
🧠 Why This Architecture Matters
This design allows Sentinel Risk to:
- scale to new languages without rewriting rules
- support CLI and CI use cases in the future
- remain honest about analysis accuracy
- accept community-contributed adapters safely
This is the same architectural philosophy used by
enterprise static analysis tools.
📁 Project Structure
src/
├── parsing/
│ ├── parseStrategy.ts
│ ├── heuristic.strategy.ts
│ └── strategySelector.ts
├── extension.ts
│ └── VS Code lifecycle, adapter dispatch, diagnostics wiring
│
├── adapters/
│ ├── languageAdapter.ts
│ │ └── Adapter contract (parse → UST, capability declaration)
│ │
│ ├── capabilities.ts
│ │ └── Adapter capability model (FULL / PARTIAL / BASIC)
│ │
│ ├── adapterRegistry.ts
│ │ └── Capability-aware adapter selection & fallback logic
│ │
│ ├── javascript.adapter.ts
│ │ └── JavaScript / TypeScript Tree-sitter adapter (FULL)
│ │
│ ├── genericFallback.adapter.ts
│ │ └── Heuristic-based adapter for all unsupported languages (BASIC)
│ │
│
├── core/
│ ├── model/
│ │ └── USTModel.ts
│ │ └── Universal Syntax Tree definition (language-agnostic)
│ │
│ ├── utils/
│ │ └── traverse.ts
│ │ └── Generic UST traversal helpers
│ │
│ ├── rules/
│ │ ├── cyclomaticComplexity.ts
│ │ ├── controlFlowDepth.ts
│ │ └── mutationRisk.ts
│ │ └── Pure, language-agnostic analysis rules
│ │
│ └── engine/
│ ├── ruleEngine.ts
│ │ └── Executes all rules and propagates confidence
│ │
│ └── ruleTypes.ts
│ └── RuleResult, location & confidence models
│
├── vscode/
│ ├── diagnostics.ts
│ │ └── Problems panel & line-level diagnostics
│ │
│ └── codeActions.ts
│ └── Quick fix suggestions (Ctrl + .)
│
└── utils/
└── logger.ts
└── Centralized logging utility
🔑 How This Structure Scales
- Adding a new language requires only a new adapter file
- Rules never change when new languages are added
- UI code remains isolated from parsing & analysis
- Heuristic fallback guarantees coverage for all languages
🚧 What’s Next
- Phase 4 — Multi-language adapters
- Phase 5 — Risk scoring & sensitivity modes
- Phase 6 — CLI & CI integration
📌 Disclaimer
Sentinel Risk is under active development.
APIs may change until v1.0.
👤 Author
Built by Atul Pratap Singh
Focus: static analysis, developer productivity, and engineering correctness.
