sdk.md

SDK Guide

The public Go SDK for this repository lives at:

import "github.com/devr-tools/codeguard/pkg/codeguard"

Use the CLI when you want an operator-facing workflow. Use the SDK when you want to embed codeguard scans into another Go application or tool.

Install

go get github.com/devr-tools/codeguard/pkg/codeguard

Minimal example

package main

import (
	"context"
	"log"
	"os"

	"github.com/devr-tools/codeguard/pkg/codeguard"
)

func main() {
	cfg := codeguard.ExampleConfig()
	report, err := codeguard.Run(context.Background(), cfg)
	if err != nil {
		log.Fatal(err)
	}
	_ = report
}

Common SDK entrypoints

• codeguard.ExampleConfig() returns a ready-to-edit starter config.
• codeguard.ExampleConfigForProfile(name) returns a starter config for a built-in profile.
• codeguard.ApplyDefaults(&cfg) fills omitted fields on an in-memory config before validation or inspection.
• codeguard.LoadConfigFile(path) loads and validates a config file.
• codeguard.ValidateConfig(cfg) validates config without running a scan.
• codeguard.Run(ctx, cfg) runs a full scan.
• codeguard.RunWithOptions(ctx, cfg, opts) runs a full or diff scan.
• codeguard.VerifyFix(ctx, cfg, finding, candidate, opts) validates a proposed patch in a temp workspace, reruns codeguard against the diff, and executes verification tests before returning it.
• codeguard.GenerateVerifiedFix(ctx, req) asks a generator for a patch candidate and only returns it after the same verification flow passes.
• codeguard.WriteReport(w, report, format) writes text, json, sarif, or github output.
• codeguard.WriteBaselineFile(path, entries) writes a baseline file.
• codeguard.BaselineEntriesFromReport(report) extracts baseline entries from a report.
• codeguard.Rules() lists rule metadata for CLI-like discovery.
• codeguard.RulesForConfig(cfg) includes custom rule-pack metadata from config.
• codeguard.ExplainRule(ruleID) returns the metadata for one rule.
• codeguard.ExplainRuleForConfig(cfg, ruleID) resolves built-in and custom rules from config.
• codeguard.Profiles() lists built-in profile metadata.

Typical flow

cfg, err := codeguard.LoadConfigFile("codeguard.json")
if err != nil {
	log.Fatal(err)
}

report, err := codeguard.RunWithOptions(context.Background(), cfg, codeguard.ScanOptions{
	Mode:    codeguard.ScanModeDiff,
	BaseRef: "main",
})
if err != nil {
	log.Fatal(err)
}

if err := codeguard.WriteReport(os.Stdout, report, "json"); err != nil {
	log.Fatal(err)
}

Configuration defaults and recommended sections

ExampleConfig and ApplyDefaults serve different purposes. ExampleConfig returns CodeGuard's complete starter configuration, suitable as the beginning of a new config. ApplyDefaults fills omitted values on a Config that your program constructed or decoded in memory. File loading and writing already apply defaults. Call ApplyDefaults yourself before validating or inspecting a partial in-memory config.

The optional recommended section policy is controlled under checks:

checks:
  use_recommended_defaults: true
  disabled:
    - prompts

When use_recommended_defaults is true, CodeGuard additionally enables the recommended baseline: quality, design, security, prompts, and ci. performance and supply_chain remain opt-in. Existing explicit section enables are retained, and checks.disabled is applied last, so it always wins over both an explicit enable and the recommended baseline. Use the canonical section names in disabled: quality, performance, design, security, prompts, ci, supply_chain, context, or contracts; aliases are not accepted.

When use_recommended_defaults is absent or false, CodeGuard preserves the existing section behavior. Built-in profiles remain independent of this flag: they supply their own thresholds and policy settings, but do not implicitly select or replace the recommended section baseline.

CheckConfig is an exported struct alias. Adding fields for this policy means unkeyed composite literals such as codeguard.CheckConfig{true, ...} are no longer source-compatible across SDK versions. Use keyed literals instead:

cfg := codeguard.Config{
	Checks: codeguard.CheckConfig{
		UseRecommendedDefaults: true,
		Disabled:                []string{"prompts"},
	},
}
codeguard.ApplyDefaults(&cfg)

Loading standalone design policies

LoadConfigFile also loads a standalone architecture policy. It auto-discovers .codeguard/design_rules.yml or .codeguard/design_rules.yaml, or follows checks.design_rules_file relative to the main config. The external document is loaded as the base DesignRulesConfig; explicitly present inline checks.design_rules fields win.

This behavior belongs to file loading. Setting CheckConfig.DesignRulesFile on a config constructed entirely in memory and passing it directly to Run does not read the file. For an in-memory config, populate CheckConfig.DesignRules directly using the exported DesignRulesConfig, DesignLayerConfig, DesignDomainConfig, DesignCapabilityConfig, DesignPublicSurfaceConfig, DesignProductionTestConfig, DesignReachabilityConfig, and DesignStabilityConfig types.

See the standalone policy template for the complete YAML schema and migration notes in the Design checks guide.

Verified fix flow

VerifyFix and GenerateVerifiedFix fail closed. They do not return a patch unless:

• the unified diff applies cleanly in an isolated temporary workspace
• a diff-scoped codeguard run returns no findings for the proposed change
• verification test commands pass

By default, the verifier infers conservative verification commands from the changed files:

• Go: nearest package tests
• Python: nearest unittest files through python3 -m unittest <test-file>
• JavaScript: nearest runnable node --test files
• JavaScript and TypeScript: package.json test scripts as a fallback when no runnable nearest-file command can be inferred

When those defaults are not appropriate for your repo, pass explicit FixVerificationCommand entries through FixOptions.TestCommands.