Documentation
¶
Overview ¶
Package codequality assembles the code-quality findings for a source tree: it runs the deterministic maintainability/reliability rule engine and layers on the metric-derived signals (duplication, and complexity when an AST backend is available), mapping everything to first-party finding.Finding values (Kind=quality/reliability, ungated, publishable like SAST). No LLM, no persistence – a read-only producer the CLI (and, later, the scan pipeline + UI) consume.
Index ¶
- Constants
- type Option
- func WithBehavioralHotspotsUnavailable(reason string) Option
- func WithBugs(b ports.BugDetector) Option
- func WithComplexity(m ports.CodeMetricsProvider, threshold int) Option
- func WithComplexityMetricsOnly(m ports.CodeMetricsProvider) Option
- func WithCoupling(analyzer ports.CouplingAnalyzer) Option
- func WithDuplication(d ports.DuplicationScanner) Option
- func WithGitHistory(collector ports.GitHistoryCollector, depth int, head ...string) Option
- func WithInventory(inv ports.CodeInventoryScanner) Option
- func WithStructuralAnalyzer(a ports.CodeAnalyzer) Option
- func WithTestScopedSmells(include bool) Option
- type Report
- type Service
Constants ¶
const DefaultComplexityThreshold = 15
DefaultComplexityThreshold is the cyclomatic complexity above which a function earns a maintainability finding (a widely used "refactor" line). Configurable via WithComplexityThreshold.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Option ¶
type Option func(*Service)
Option configures a Service.
func WithBehavioralHotspotsUnavailable ¶ added in v0.2.0
WithBehavioralHotspotsUnavailable records why behavioral hotspots cannot be collected in this deployment. It is intended for deliberately disabled infrastructure, so new analyses remain distinguishable from legacy analyses that predate behavioral hotspot snapshots.
func WithBugs ¶
func WithBugs(b ports.BugDetector) Option
WithBugs wires the deeper AST bug detector (unreachable code, constant conditions), emitting its findings as Kind=reliability. Requires the synapse-ast sidecar; degrades to nothing without it.
func WithComplexity ¶
func WithComplexity(m ports.CodeMetricsProvider, threshold int) Option
WithComplexity adds high-complexity maintainability findings (functions over threshold), using the AST metrics provider. threshold <= 0 uses DefaultComplexityThreshold.
func WithComplexityMetricsOnly ¶ added in v0.2.0
func WithComplexityMetricsOnly(m ports.CodeMetricsProvider) Option
WithComplexityMetricsOnly adds complexity measurement to reports without emitting maintainability findings or changing quality gates.
func WithCoupling ¶ added in v0.2.0
func WithCoupling(analyzer ports.CouplingAnalyzer) Option
WithCoupling adds deterministic first-party module dependency measures to full reports. It does not create findings or change the default quality gate.
func WithDuplication ¶
func WithDuplication(d ports.DuplicationScanner) Option
WithDuplication adds duplicated-block maintainability findings.
func WithGitHistory ¶ added in v0.2.0
func WithGitHistory(collector ports.GitHistoryCollector, depth int, head ...string) Option
WithGitHistory adds bounded git history evidence to compute behavioral hotspots on full reports.
func WithInventory ¶
func WithInventory(inv ports.CodeInventoryScanner) Option
WithInventory wires the code-size inventory, enabling Report() to compute ratings + a health summary.
func WithStructuralAnalyzer ¶
func WithStructuralAnalyzer(a ports.CodeAnalyzer) Option
WithStructuralAnalyzer adds language-aware AST findings. It is optional; an unavailable sidecar returns no findings through its adapter.
func WithTestScopedSmells ¶
WithTestScopedSmells controls whether info-severity code smells located in test code (src/test, *_test.*, *.spec.*, __tests__, testdata, ...) are emitted. They are SUPPRESSED by default: a rule like commented-out-code fires heavily in tests and otherwise drowns the higher-value findings (complexity, duplication, reliability). Pass true to restore full verbosity. Only Info-severity smells are affected; medium/high findings (and every non-test finding) are always kept.
Because the filter lives in the single analyze() chokepoint, it also applies to BuildReport and thus to rating.Compute: test-scoped Info smells (5 debt-minutes each) are excluded from the technical-debt total and the maintainability grade by default, which is intentional (test TODOs are not production debt).
type Report ¶
type Report struct {
Inventory measure.Inventory `json:"inventory"`
Findings []finding.Finding `json:"findings"`
Duplication *measure.DuplicationReport `json:"duplication,omitempty"`
Complexity *measure.ComplexityReport `json:"complexity,omitempty"`
Coupling *measure.CouplingReport `json:"coupling,omitempty"`
BehavioralHotspots *measure.BehavioralHotspotsReport `json:"behavioral_hotspots,omitempty"`
Truncated bool `json:"truncated,omitempty"`
Rating rating.Report `json:"rating"`
}
Report is the full code-quality dashboard payload for a source tree: the per-language inventory, the findings, the duplication summary, and the rolled-up A-E health ratings + technical debt.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service produces code-quality findings. analyzer is required; dup, metrics and inventory are optional enrichers.
func New ¶
func New(analyzer ports.CodeAnalyzer, opts ...Option) *Service
New returns a Service. analyzer is required.
func (*Service) Analyze ¶
Analyze returns the code-quality findings for root, sorted deterministically by dedup key.
func (*Service) BuildReport ¶
BuildReport computes the full dashboard report for root. Findings come from Analyze (which already bridges duplication + complexity); the inventory + duplication summary + ratings are added for display. Missing optional dependencies degrade to empty sections rather than erroring.
func (*Service) BuildReportForCommit ¶ added in v0.2.0
func (s *Service) BuildReportForCommit(ctx context.Context, root, headCommit string) (Report, error)
BuildReportForCommit builds a report pinned to the immutable commit captured by the acquired workspace. Keeping the commit on the call rather than the shared Service prevents concurrent scans from ever collecting history for one workspace while labelling it as another.
Source Files