runtime

Documentation

Overview

Package runtime detects async/message-bus integration patterns in a repository. It uses ast-grep (via toolrun.Runner) to scan for async signal patterns per language, and consults an off-gate library→integration-kind YAML table.

This is an adapter package: os.ReadFile is permitted here. os/exec is forbidden — all subprocess calls go through toolrun.Runner.

Signal is REPORT-ONLY and must never change the gate verdict (v1). Confidence is always "low" when no async signal is found — absence of evidence is not evidence of synchronous communication.

Index

• Constants
• type AsyncSignal
• type IntegrationKind
• type Result
  • func Detect(ctx context.Context, root string, runner toolrun.Runner) Result

Constants

const (
	ConfidenceLow    = "low"
	ConfidenceMedium = "medium"
)

Confidence levels for runtime async detection results.

Types

type AsyncSignal

type AsyncSignal struct {
	File            string
	Line            int
	Library         string
	IntegrationKind IntegrationKind
	Language        string
}

AsyncSignal records one detected async integration at a file location.

type IntegrationKind

type IntegrationKind string

IntegrationKind classifies what kind of async integration was detected.

const (
	KindMessageQueue IntegrationKind = "message_queue"
	KindEventBus     IntegrationKind = "event_bus"
	KindAsyncTask    IntegrationKind = "async_task"
)

Integration kind constants for detected async patterns.

type Result

type Result struct {
	Signals       []AsyncSignal
	Confidence    string // "low" | "medium"
	ModuleSignals map[string][]AsyncSignal
}

Result is the output of Detect for one repository. Signals lists every detected async pattern. Confidence is "low" when no signals are found (absence ≠ synchronous). ModuleSignals maps module path → list of signals found in that module's files.

func Detect

func Detect(ctx context.Context, root string, runner toolrun.Runner) Result

Detect scans root for async integration patterns across all three languages. It uses ast-grep via runner when "sg" is available; falls back to a simple text scan of source files when ast-grep is absent (grep-style import search). Never gates — always report-only.