Help us shape the future of Go! Take the 2026 Go Developer Survey

codesignalcli

package
v0.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 12, 2026 License: BSD-2-Clause Imports: 28 Imported by: 0

Documentation

Overview

Package codesignalcli is the scan use case behind `coach codesignal`: it analyzes the selected files of a diff or a repository baseline, hands a validated project policy to its language's project backend (Go or TypeScript), and discloses worktree state the committed report cannot see. The adapters and other use cases it builds on live in its sub-packages.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AnalyzeBaseline added in v0.1.2 

func AnalyzeBaseline(ctx context.Context, dir, revisionSHA string, files []gitrepo.SelectedFile, extraDiagnostics []codesignal.Diagnostic, appliedScope string, coverage codesignal.Coverage, project *ProjectAnalysis) (*codesignal.Report, error)

func AnalyzeChanges 

func AnalyzeChanges(ctx context.Context, dir, headSHA, mergeBaseSHA string, files []gitrepo.SelectedFile, extraDiagnostics []codesignal.Diagnostic, continuity []codesignal.PathContinuity, appliedScope string, excluded []codesignal.CoverageGroup, project *ProjectAnalysis) (*codesignal.Report, error)

func MaterializeTSAnalyzer added in v0.4.0 

func MaterializeTSAnalyzer(ctx context.Context) (dir string, cleanup func(), err error)

MaterializeTSAnalyzer copies the embedded, generated TypeScript analyzer asset into a new private temporary directory and returns that directory alongside a cleanup func that removes it. On error (including ctx cancellation), dir is "" and no directory is created or left behind -- the returned cleanup is a no-op and callers need not (and cannot usefully) call it. On success the caller owns dir and must call cleanup, which is safe to call more than once, once it is done with the directory.

func PrepareTSRuntime added in v0.5.0 

func PrepareTSRuntime(ctx context.Context, dir string, roots []string) (*tsRuntime, func(), error)

PrepareTSRuntime resolves and materializes everything tsProjectBackend needs to run one --project-language typescript analysis confined to a private, host-approved runtime: the exact host Node executable, the exact approved TypeScript compiler (see tstoolchain.ResolveCompilerForRuntime), and a freshly materialized private analyzer directory (MaterializeTSAnalyzer). On success, the caller owns the returned cleanup and must call it, exactly like MaterializeTSAnalyzer's own contract -- it tears down the materialized analyzer directory and is safe to call more than once.

dir is the walk ceiling (repository root); roots are the selected policy roots threaded into tstoolchain.ResolveCompilerForRuntime so readiness and Analyze share one root-scoped project-manifest origin. Compiler- resolution reads are host-readiness reads of the analyzed repository's worktree (its package.json/mise.toml/node_modules), never analysis input -- the same distinction projectcheck.Run's own tstoolchain.ResolveCompiler call documents.

Every failure here is fatal (a non-nil error, cleanup a no-op), never a soft projectmodel.DiagBackendUnavailable degrade. Analyze does not run --check-project; the two share tstoolchain.ResolveCompiler's locatable-PASS rule so a readiness-green repository cannot reach an unlocatable compiler here. A clean miss of host Node or of a supported compiler is a tstoolchain.CompilerUnresolvedError (exit 2). Other probe failures stay operational.

func ResolveProjectBackend added in v0.4.0 

func ResolveProjectBackend(language string) error

ResolveProjectBackend reports whether a project-analysis backend is registered for language. "go" and "typescript" both have registered backends today; every other language, including the empty string, remains unavailable until its own backend lands.

func TSAnalyzerAssetDigest added in v0.4.0 

func TSAnalyzerAssetDigest() (string, error)

TSAnalyzerAssetDigest returns a deterministic sha256 hex digest over every file in the embedded TypeScript analyzer asset (path and content, visited in path-sorted order), so the digest is stable across process runs and only changes when the generated asset's content changes.

func WorkingTreeDisclosureDiagnostics added in v0.9.0 

func WorkingTreeDisclosureDiagnostics(dir string) []codesignal.Diagnostic

WorkingTreeDisclosureDiagnostics reports uncommitted paths the committed snapshot scan does not read. A status-check failure is one diagnostic and does not fail the scan. A clean tree returns nil.

Types

type ProjectAnalysis added in v0.4.0 

type ProjectAnalysis struct {
	ConfigPath   string
	Language     string
	Config       json.RawMessage
	ConfigDigest string
	Backend      ProjectBackend
}

ProjectAnalysis is the typed handoff from a validated --project-config selection into AnalyzeBaseline/AnalyzeChanges. A nil *ProjectAnalysis means project mode is disabled (legacy schema-1 path). When non-nil, Backend must be non-nil; config/backend failures stay on the CLI composition root so file-local reports remain available with stable diagnostics.

type ProjectBackend added in v0.4.0 

type ProjectBackend interface {
	Analyze(ctx context.Context, req ProjectBackendRequest) (*ProjectBackendResult, error)
}

ProjectBackend builds project observations for one analysis request. Downstream language backends (#210/#214) implement this seam.

func NewGoProjectBackend added in v0.4.0 

func NewGoProjectBackend() ProjectBackend

NewGoProjectBackend returns the ProjectBackend registered for --project-language go. Analyze always builds the head-side model; when req.Baseline is false (diff mode) it additionally builds the base-side model and sets ProjectBackendResult.BaseAnalyzed. A revision that cannot be read as a Git snapshot (see revisionfs.New) is returned as a real error, not swallowed into an empty result.

func NewTSProjectBackend added in v0.4.0 

func NewTSProjectBackend() ProjectBackend

NewTSProjectBackend returns the ProjectBackend registered for --project-language typescript. Analyze always builds the head-side model; when req.Baseline is false (diff mode) it additionally builds the base-side model and sets ProjectBackendResult.BaseAnalyzed. Head and base evaluations share one PrepareTSRuntime call -- one resolved Node/compiler and one materialized analyzer directory serve both revisions.

A crashed or timed-out analyzer subprocess is never surfaced as a Go error here: BuildTypeScriptModelViaSidecar's own contract reports that condition as a DiagBackendUnavailable diagnostic inside the returned Model's Coverage (Coverage.Complete false), which flows through unchanged into ProjectBackendResult.HeadCoverage/BaseCoverage. A PrepareTSRuntime failure (no usable Node, no locatable compiler, or a materialization failure) is different: it surfaces as a real Go error, since it is an unexpected condition --check-project is expected to have already gated (see PrepareTSRuntime's doc comment).

type ProjectBackendRequest added in v0.4.0 

type ProjectBackendRequest struct {
	Dir          string
	HeadRevision string
	BaseRevision string
	Baseline     bool
	ConfigPath   string
	Config       json.RawMessage
	ConfigDigest string
	Language     string
}

ProjectBackendRequest carries the immutable revision and config identity a backend needs. Absolute checkout roots must not leak into lifecycle identity.

type ProjectBackendResult added in v0.4.0 

type ProjectBackendResult struct {
	HeadChanges []codesignal.ProjectChange
	BaseChanges []codesignal.ProjectChange
	Facts       []codesignal.ProjectFact
	// HeadDiagnostics/BaseDiagnostics carry backend-produced diagnostics that
	// are not themselves ProjectChanges (e.g. a coverage-incomplete
	// diagnostic), reaching report.Diagnostics[] via applyProjectBackend
	// instead of being silently dropped alongside the ProjectChanges/Coverage
	// they describe. See baseProjectDiagnostics for how a base-side entry
	// stays distinguishable from a head-side one in diff mode.
	HeadDiagnostics []codesignal.Diagnostic
	BaseDiagnostics []codesignal.Diagnostic
	HeadCoverage    *projectmodel.Coverage
	BaseCoverage    *projectmodel.Coverage
	// HeadProjectScope/BaseProjectScope carry the per-revision
	// projectmodel.ProjectScopeFromModel result (candidate_files/
	// analyzed_files accounting per policy root, matched/unmatched layers).
	// Unlike HeadCoverage/BaseCoverage, a nil value here means no
	// project_scope could be derived for that revision (e.g. the analyzer
	// produced no root_scopes data at all), not that scope is unpopulated by
	// omission -- see tsProjectBackend.evaluateRevision.
	HeadProjectScope *projectmodel.ProjectScope
	BaseProjectScope *projectmodel.ProjectScope
	// HeadModelCoverage/BaseModelCoverage, HeadBypassCoverage/
	// BaseBypassCoverage, and HeadReachabilityCoverage/BaseReachabilityCoverage
	// carry each analyzed revision's three phase-specific Coverage
	// observations independently of HeadCoverage/BaseCoverage's existing
	// combined fold: model (the project model's own
	// Coverage), bypass (the layer-bypass search's own completeness after
	// tsBypassCoverageForFold's reachability-gap exclusion, or Phase
	// "not_requested" -- never nil -- when the config has no required_layer),
	// and reachability (BuildTypeScriptReachabilityFromModel(model).Coverage).
	// None of the three replaces or alters HeadCoverage/BaseCoverage; they
	// are additive, read-only observations of the same single analyzer
	// response tsProjectBackend.evaluateRevision already builds. Currently
	// only populated by the TypeScript backend.
	HeadModelCoverage        *projectmodel.Coverage
	BaseModelCoverage        *projectmodel.Coverage
	HeadBypassCoverage       *projectmodel.Coverage
	BaseBypassCoverage       *projectmodel.Coverage
	HeadReachabilityCoverage *projectmodel.Coverage
	BaseReachabilityCoverage *projectmodel.Coverage
	BaseAnalyzed             bool
	RuntimeKind              string
	RuntimeVersion           string
	RuntimeOrigin            string
	CompilerVersion          string
	CompilerOrigin           string
	AnalyzerProtocolVersion  int
	AnalyzerVersion          string
	AnalyzerDigest           string
	PackageManagerKind       string
	PackageManagerVersion    string
	PackageManagerOrigin     string
}

ProjectBackendResult is the builder-facing project observation bundle.

type ProjectBackendUnavailableError added in v0.4.0 

type ProjectBackendUnavailableError struct {
	Message string
}

ProjectBackendUnavailableError signals a valid project configuration whose requested language has no registered project-analysis backend. It maps to exit code 3 and is reported in the local CodeSignal document.

func (*ProjectBackendUnavailableError) Error added in v0.4.0 

func (e *ProjectBackendUnavailableError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
Package configauthoring helps a user produce a project-policy candidate: guided interactive authoring for TypeScript, and non-interactive root suggestion from a committed revision, written create-only.
 Package configauthoring helps a user produce a project-policy candidate: guided interactive authoring for TypeScript, and non-interactive root suggestion from a committed revision, written create-only.
Package gitrepo is the git process adapter behind coach codesignal: revision resolution, changed and tracked file selection, bounded and batched object reads, revision archives, and worktree status.
 Package gitrepo is the git process adapter behind coach codesignal: revision resolution, changed and tracked file selection, bounded and batched object reads, revision archives, and worktree status.
internal
gitfixture
Package gitfixture builds throwaway Git repositories for codesignalcli tests: one initialized repository per test, and one commit per file.
 Package gitfixture builds throwaway Git repositories for codesignalcli tests: one initialized repository per test, and one commit per file.
Package pkgmanager detects which package manager (npm, pnpm, Bun, or yarn) a TypeScript project declares, from the worktree or a committed revision, probes the version on PATH, and rejects configuration that would redirect package resolution.
 Package pkgmanager detects which package manager (npm, pnpm, Bun, or yarn) a TypeScript project declares, from the worktree or a committed revision, probes the version on PATH, and rejects configuration that would redirect package resolution.
Package projectcheck runs `coach codesignal --check-project`: it evaluates the committed policy, project shape, host runtime, compiler, package manager, and dirty worktree, then aggregates them into one readiness result with ordered gaps and next actions.
 Package projectcheck runs `coach codesignal --check-project`: it evaluates the committed policy, project shape, host runtime, compiler, package manager, and dirty worktree, then aggregates them into one readiness result with ordered gaps and next actions.
Package projectconfig owns the project-policy document (project.json): its frozen schema-1 shape, strict decoding and validation, and the bounded read of the committed document at an analyzed revision.
 Package projectconfig owns the project-policy document (project.json): its frozen schema-1 shape, strict decoding and validation, and the bounded read of the committed document at an analyzed revision.
Package projectreadiness is the --check-project result model: the checks, gaps, warnings, and next actions a readiness run reports, and the gap-code table that fixes each gap's status and remediation kind.
 Package projectreadiness is the --check-project result model: the checks, gaps, warnings, and next actions a readiness run reports, and the gap-code table that fixes each gap's status and remediation kind.
Package prompt reads answers from an interactive session one line at a time.
 Package prompt reads answers from an interactive session one line at a time.
Package render presents CodeSignal reports and project-readiness results as the CLI's text and JSON output.
 Package render presents CodeSignal reports and project-readiness results as the CLI's text and JSON output.
Package revisionfs serves one immutable Git revision as a read-only fs.FS, so project analysis never reads the live worktree.
 Package revisionfs serves one immutable Git revision as a read-only fs.FS, so project analysis never reads the live worktree.
Package sourcescope labels each selected file as production, test-only, excluded, or unknown from the analyzed revision's own Go build graph and tsconfig.json, and filters or tallies files by that label.
 Package sourcescope labels each selected file as production, test-only, excluded, or unknown from the analyzed revision's own Go build graph and tsconfig.json, and filters or tallies files by that label.
Package subprocess runs short, bounded probes of host executables (node, mise, package managers) with a wall-time limit and an output cap.
 Package subprocess runs short, bounded probes of host executables (node, mise, package managers) with a wall-time limit and an output cap.
Package terminal detects whether a file is an interactive controlling terminal, the precondition for every prompt the CLI shows.
 Package terminal detects whether a file is an interactive controlling terminal, the precondition for every prompt the CLI shows.
Package tssetup runs the consented TypeScript compiler setup a failed readiness check offers: it builds the menu of verified installation choices, previews the exact frozen command, executes it only after a single explicit confirmation, and rechecks readiness afterwards.
 Package tssetup runs the consented TypeScript compiler setup a failed readiness check offers: it builds the menu of verified installation choices, previews the exact frozen command, executes it only after a single explicit confirmation, and rechecks readiness afterwards.
Package tstoolchain resolves the host toolchain a TypeScript project scan runs on: the supported Node runtime and the one approved TypeScript compiler, found across the project manifest, project mise, and global mise origins, with mise's own trust gates applied before mise is ever asked.
 Package tstoolchain resolves the host toolchain a TypeScript project scan runs on: the supported Node runtime and the one approved TypeScript compiler, found across the project manifest, project mise, and global mise origins, with mise's own trust gates applied before mise is ever asked.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.