RepoSense

Backend transaction, side-effect, and upgrade-context system for AI-assisted projects.

RepoSense turns repositories into evidence-backed engineering facts, side-effect maps, and upgrade-ready context. RepoSense turns repositories into auditable engineering facts, deterministic patterns, and grounded engineering insights.

Language: English | 简体中文

Why RepoSense

AI can generate a first backend version quickly. The harder part usually starts in the second and third version: maintainability, upgrade confidence, and safe handoff context.

Teams often cannot clearly see:

• which APIs write data,
• where transaction boundaries are observed or missing,
• where queue dispatch and consume signals appear,
• where cache state changes happen,
• which side effects may affect the next AI-assisted change,
• what upgrade context should be handed to the next assistant or engineer.

RepoSense addresses this by converting code into evidence-backed Facts, deterministic Patterns, and grounded Insights that can be replayed and reviewed.

What RepoSense Helps You Answer

• Which backend APIs trigger writes and side effects?
• Where are transaction signals observed or not observed?
• Which side effects may affect the next change?
• What changed between two runs?
• Is this repository ready for the next AI-assisted upgrade?
• What context should be handed to the next AI-assisted upgrade?

Core Flow

Code Repo
  -> Facts
  -> Patterns
  -> Insights
       \
        -> Learn

Context Pack turns these outputs into explicit upgrade context for the next AI-assisted maintenance or upgrade cycle.

Boundary

RepoSense performs conservative, evidence-backed detection. It helps expose backend transaction, side-effect, and upgrade-context signals, but it does not guarantee full backend correctness or safe upgrades.

3-Minute Quickstart

Run from repository root (PowerShell on Windows):

powershell -ExecutionPolicy Bypass -File tools/demo_run.ps1

After Running the Demo, You Will See

• report.html
• backend_verifier_report.json and backend_verifier_report.md
• patterns.json and pattern_summary.json
• ai_summary.md
• ai_risks/risks.md
• ai_explain/*/explain.md (at least one)
• exports/context_pack.zip
• run_manifest.json

Studio UI

RepoSense includes a local Studio UI for interactive analysis.

Start it with:

python -m reposense studio serve --port 8010

Or, when using the local virtual environment:

.\.venv\Scripts\python.exe -m reposense studio serve --port 8010

Then open:

http://127.0.0.1:8010

Studio UI

Studio currently supports two local workflows:

1. Upload repository ZIP.
2. Analyze a local repository path.

Current Studio flow:

• Import by ZIP upload or local path.
• Start an analysis run.
• Track run status.
• Open generated artifacts:
  • report.html
  • Learn UI
  • SARIF
  • Context Pack
  • run manifest
  • backend verifier / AI-derived outputs when available

Studio can also surface Repository Review artifacts, including human review required items, Code Health, Permission Review, AuthZ Matrix, and the Context Pack REVIEW section when those artifacts are generated.

For a complete review demo run that feeds the Studio Review panel and release screenshots:

powershell -ExecutionPolicy Bypass -File tools/review_demo.ps1

The canonical output is .reposense_review_demo/current/.

Boundary:

• Studio is a local developer UI.
• Local path analysis is for local Studio use on your machine.
• Browser workflow does not upload the full local directory to a hosted cloud service by default.
• RepoSense performs static reading for analysis and does not execute repository code.
• CLI remains recommended for scripted/local automation.

CLI local directory example:

python -m reposense ci run --repo <path-to-repo> --out .reposense_runs --profile demo --with-context-pack

What RepoSense Can Do Today

OSS Local Capabilities

• Findings / Events / Evidence
• report.json and report.html
• event_graph.json
• api_surface.json
• Context Pack export
• SARIF export
• Quality Gate
• Baseline & Diff
• Run Manifest
• Repository Review Mode, Code Health Radar MVP, Permission Auditor MVP, and optional AuthZ Matrix
• Learn local site (learn/index.html)
• Deterministic pattern outputs:
  • patterns.json / pattern_summary.json
• Local, evidence-backed, limited AI-derived outputs:
  • ai summary
  • ai risks
  • ai explain
  • ai ask (constrained)

Roadmap / Hosted Enhancements

• Guided repair playbooks
• Multi-run history and trend workspace
• Team collaboration workspace
• Enterprise/compliance reporting templates
• Long-term upgrade advisor

Context Pack / Upgrade Context

Context Pack is the handoff layer for the next AI-assisted change.

It packages API surface, backend events, findings, evidence, quality gate, baseline diff, and run manifest into a reproducible context bundle.

Context Pack now includes a REVIEW/ section for AI-assisted maintenance and human review handoff.

What RepoSense Is Not

• Not a general AI code chat.
• Not a proof of full backend correctness.
• Not a tool that guarantees all transactions are correct.
• Not a tool that lets models freely roam your entire repository by default.

Four Product Surfaces

• Analysis: extracts Findings, Events, and Evidence from code repositories.
• Learn: Concepts -> Cases -> Evidence for grounded learning.
• AI Insights: summary, risks, explain, ask on top of Facts + Patterns.
• Studio: local run viewer for reports, risks, explain, and evidence/snippet links.

Trust Principles

• Evidence-first
• Deterministic
• Facts first, source on demand

AI Grounded Principles

RepoSense AI outputs follow a grounded contract: Facts-only by default, constrained source drill-down only when needed, and explicit confirmed / inferred / unknown separation.

Documentation Entry Points

• docs/DEMO_QUICKSTART.md
• docs/ARCHITECTURE.md
• docs/reports/BACKEND_VERIFIER_REPORT.md
• docs/review/REPOSITORY_REVIEW_MODE.md
• docs/review/CODE_HEALTH_RADAR.md
• docs/review/PERMISSION_AUDITOR.md
• docs/review/AUTHZ_MATRIX.md
• docs/context-pack/CONTEXT_PACK_SPEC.md
• docs/AI_GROUNDED_PRINCIPLES.md
• Full docs index: docs/INDEX.md

Screenshots / Demo Assets

Release screenshots are tracked in docs/assets/ASSET_INDEX.md.

Canonical release screenshots are captured from:

• .reposense_release_demo/current/
• Regenerate with: powershell -ExecutionPolicy Bypass -File tools/release_demo.ps1

Current stable screenshot targets include:

• Overview
• Backend Events
• API Surface

Learn / AI Risks / AI Explain screenshots are captured from the same canonical release demo run.

More Repository Review screenshots are tracked in docs/assets/ASSET_INDEX.md, including Human Review Required, Code Health, Permission Review, AuthZ Matrix, and Context Pack REVIEW section.

Screenshots

RepoSense generates local, evidence-backed reports for backend transaction, side-effect, and upgrade-context inspection.

Backend Events

API Surface

Backend Verifier Report

More screenshots and release assets are tracked in docs/assets/ASSET_INDEX.md.

FAQ

Q1. Why not let AI read the whole repository directly?

RepoSense optimizes for cost, stability, and auditability. Default reasoning is Facts-only; source drill-down is on-demand and evidence-constrained.

Q2. How is RepoSense different from a normal lint/code scanner?

RepoSense outputs not only Findings, but also Events, Event Graph, Evidence references, deterministic Patterns, and grounded Insights.

Q3. How is RepoSense different from AI code chat tools?

RepoSense is Facts-first, deterministic, and evidence-backed. Outputs can be replayed and audited via run artifacts.

Q4. What is Learn for?

Learn is not a static docs page. It is a Concepts -> Cases -> Evidence learning path for grounded engineering understanding.

Q5. What languages are supported today?

Current OSS coverage centers on Python, TypeScript/JavaScript, Java, and SQL signals. See docs/LANGUAGE_SUPPORT_MATRIX.md for the exact current matrix.

Development

python -m unittest -v

License & Security

• License: LICENSE
• Contributing: CONTRIBUTING.md
• Security: SECURITY.md