diff --git a/apps/backend/internal/github/env_hermetic_test.go b/apps/backend/internal/github/env_hermetic_test.go index fe8fa8eee3..fe24abe109 100644 --- a/apps/backend/internal/github/env_hermetic_test.go +++ b/apps/backend/internal/github/env_hermetic_test.go @@ -1,14 +1,10 @@ package github import ( - "go/ast" - "go/parser" - "go/token" "os" - "path/filepath" - "strconv" - "strings" "testing" + + "github.com/kandev/kandev/internal/testutil" ) // ambientGitHubEnvVars lists every environment variable this package reads in @@ -55,165 +51,5 @@ func TestAmbientGitHubEnvIsClearedForTests(t *testing.T) { // a new os.Getenv/os.LookupEnv call that ambientGitHubEnvVars does not cover, // so the scrub cannot silently fall behind the code it protects. func TestAmbientGitHubEnvCoversEveryPackageEnvRead(t *testing.T) { - fileSet := token.NewFileSet() - files := parseNonTestSources(t, fileSet) - constants := stringConstants(files) - covered := make(map[string]bool, len(ambientGitHubEnvVars)) - for _, name := range ambientGitHubEnvVars { - covered[name] = true - } - for _, file := range files { - for _, call := range envReadCalls(file) { - name, resolved := resolveEnvName(call, constants) - if !resolved { - t.Errorf("%s: environment variable name is not a string literal or a constant of this "+ - "package; a constant imported from elsewhere needs resolveEnvName taught about it", - fileSet.Position(call.Pos())) - continue - } - if !covered[name] { - t.Errorf("%s: %s is read in non-test code but missing from ambientGitHubEnvVars", - fileSet.Position(call.Pos()), name) - } - } - } -} - -func TestEnvReadCallsResolvesOSImportAlias(t *testing.T) { - fileSet := token.NewFileSet() - file, err := parser.ParseFile(fileSet, "aliased.go", `package github - -import stdos "os" - -func readToken() string { - return stdos.Getenv("GH_TOKEN") -} -`, 0) - if err != nil { - t.Fatalf("parse aliased source: %v", err) - } - - if got := len(envReadCalls(file)); got != 1 { - t.Fatalf("envReadCalls() found %d calls, want 1", got) - } -} - -// parseNonTestSources parses every production file of the package, which is -// the code whose environment reads the scrub has to keep up with. -func parseNonTestSources(t *testing.T, fileSet *token.FileSet) []*ast.File { - t.Helper() - paths, err := filepath.Glob("*.go") - if err != nil { - t.Fatalf("list sources: %v", err) - } - var files []*ast.File - for _, path := range paths { - if strings.HasSuffix(path, "_test.go") { - continue - } - file, parseErr := parser.ParseFile(fileSet, path, nil, 0) - if parseErr != nil { - t.Fatalf("parse %s: %v", path, parseErr) - } - files = append(files, file) - } - if len(files) == 0 { - t.Fatal("no non-test sources found in the package directory") - } - return files -} - -// stringConstants maps package-level string constant names to their values so -// env reads written as os.Getenv(envSomeConst) resolve to the variable name. -func stringConstants(files []*ast.File) map[string]string { - constants := make(map[string]string) - for _, file := range files { - for _, decl := range file.Decls { - genDecl, ok := decl.(*ast.GenDecl) - if !ok || genDecl.Tok != token.CONST { - continue - } - for _, spec := range genDecl.Specs { - valueSpec, ok := spec.(*ast.ValueSpec) - if !ok { - continue - } - for i, name := range valueSpec.Names { - if i >= len(valueSpec.Values) { - continue - } - if value, ok := literalString(valueSpec.Values[i]); ok { - constants[name.Name] = value - } - } - } - } - } - return constants -} - -func osPackageName(file *ast.File) (string, bool) { - for _, spec := range file.Imports { - path, err := strconv.Unquote(spec.Path.Value) - if err != nil || path != "os" { - continue - } - if spec.Name != nil { - return spec.Name.Name, spec.Name.Name != "_" && spec.Name.Name != "." - } - return "os", true - } - return "", false -} - -// envReadCalls collects every os.Getenv / os.LookupEnv call in a file. -func envReadCalls(file *ast.File) []*ast.CallExpr { - osName, ok := osPackageName(file) - if !ok { - return nil - } - var calls []*ast.CallExpr - ast.Inspect(file, func(node ast.Node) bool { - call, ok := node.(*ast.CallExpr) - if !ok || len(call.Args) != 1 { - return true - } - selector, ok := call.Fun.(*ast.SelectorExpr) - if !ok { - return true - } - pkgIdent, ok := selector.X.(*ast.Ident) - if !ok || pkgIdent.Name != osName { - return true - } - if selector.Sel.Name == "Getenv" || selector.Sel.Name == "LookupEnv" { - calls = append(calls, call) - } - return true - }) - return calls -} - -func resolveEnvName(call *ast.CallExpr, constants map[string]string) (string, bool) { - if value, ok := literalString(call.Args[0]); ok { - return value, true - } - ident, ok := call.Args[0].(*ast.Ident) - if !ok { - return "", false - } - value, ok := constants[ident.Name] - return value, ok -} - -func literalString(expr ast.Expr) (string, bool) { - lit, ok := expr.(*ast.BasicLit) - if !ok || lit.Kind != token.STRING { - return "", false - } - value, err := strconv.Unquote(lit.Value) - if err != nil { - return "", false - } - return value, true + testutil.AssertEnvReadsCovered(t, ambientGitHubEnvVars, nil) } diff --git a/apps/backend/internal/testutil/envscan.go b/apps/backend/internal/testutil/envscan.go index c905c38f82..69875caf89 100644 --- a/apps/backend/internal/testutil/envscan.go +++ b/apps/backend/internal/testutil/envscan.go @@ -3,8 +3,10 @@ package testutil import ( "fmt" "go/ast" + "go/importer" "go/parser" "go/token" + "go/types" "path/filepath" "strconv" "strings" @@ -19,9 +21,9 @@ import ( // scrub against silently falling behind new environment reads. // // os.Getenv and os.LookupEnv are always treated as environment reads. They are -// matched on the literal identifier os, so a file that imports os under an -// alias or through a dot import is not scanned; no file in this repository -// does either, and a review of one that did would be the place to catch it. +// matched by the file-local import name bound to the os package. Dot imports +// are matched by bare Getenv and LookupEnv calls. Blank imports are not scanned +// because they name no package. // Names are likewise resolved against package-level constants with no scope // analysis, so a local variable shadowing one of those constants resolves to // the constant's value rather than its own. @@ -193,7 +195,7 @@ func callsExtraReader(files []*ast.File, name string) bool { func uncoveredEnvReadsInFile(fileSet *token.FileSet, file *ast.File, scan envScan) []string { var messages []string - for _, call := range envReadCalls(file, scan.extraReaders) { + for _, call := range envReadCalls(fileSet, file, scan.extraReaders) { name, resolved := resolveEnvName(call, scan.constants) pos := fileSet.Position(call.Pos()) if !resolved { @@ -295,14 +297,16 @@ func recordConstSpecs(constants packageConstants, specs []ast.Spec) { // first: pinning this to exactly one argument meant that adding a fallback // parameter to an accessor dropped all of its call sites from the scan without // failing a single test. -func envReadCalls(file *ast.File, extraReaders map[string]bool) []*ast.CallExpr { +func envReadCalls(fileSet *token.FileSet, file *ast.File, extraReaders map[string]bool) []*ast.CallExpr { + uses := typeUses(fileSet, file) + dotImportedOS := hasOSDotImport(file) var calls []*ast.CallExpr ast.Inspect(file, func(node ast.Node) bool { call, ok := node.(*ast.CallExpr) if !ok || len(call.Args) == 0 { return true } - if isEnvRead(call.Fun, extraReaders) { + if isEnvRead(call.Fun, uses, dotImportedOS, extraReaders) { calls = append(calls, call) } return true @@ -310,27 +314,68 @@ func envReadCalls(file *ast.File, extraReaders map[string]bool) []*ast.CallExpr return calls } +// hasOSDotImport reports whether bare identifiers from the standard os package +// can be used in this file. The type checker receives the file's package name +// as its path, so a package named os would otherwise make local Getenv and +// LookupEnv functions indistinguishable from the imported functions. +func hasOSDotImport(file *ast.File) bool { + for _, importSpec := range file.Imports { + if importSpec.Name == nil || importSpec.Name.Name != "." { + continue + } + path, ok := literalString(importSpec.Path) + if ok && path == "os" { + return true + } + } + return false +} + +// typeUses resolves identifier bindings within one file. A scanner only needs +// import bindings here, so type errors in unrelated package code do not stop +// it from distinguishing an os import from a local declaration with the same +// spelling. +func typeUses(fileSet *token.FileSet, file *ast.File) map[*ast.Ident]types.Object { + uses := make(map[*ast.Ident]types.Object) + config := types.Config{ + Importer: importer.Default(), + Error: func(error) {}, + } + _, _ = config.Check(file.Name.Name, fileSet, []*ast.File{file}, &types.Info{Uses: uses}) + return uses +} + // isEnvRead reports whether fun names os.Getenv, os.LookupEnv, or one of the // extraReaders. An extraReader matches on the trailing name alone, so both // receiver.environmentValue(x) and a bare environmentValue(x) count. -func isEnvRead(fun ast.Expr, extraReaders map[string]bool) bool { +func isEnvRead(fun ast.Expr, uses map[*ast.Ident]types.Object, dotImportedOS bool, extraReaders map[string]bool) bool { switch target := fun.(type) { case *ast.SelectorExpr: if extraReaders[target.Sel.Name] { return true } pkgIdent, ok := target.X.(*ast.Ident) - if !ok || pkgIdent.Name != "os" { + if !ok || !isOSPackageName(uses[pkgIdent]) { return false } return target.Sel.Name == "Getenv" || target.Sel.Name == "LookupEnv" case *ast.Ident: - return extraReaders[target.Name] + return extraReaders[target.Name] || (dotImportedOS && isOSReader(uses[target]) && (target.Name == "Getenv" || target.Name == "LookupEnv")) default: return false } } +func isOSPackageName(object types.Object) bool { + pkgName, ok := object.(*types.PkgName) + return ok && pkgName.Imported().Path() == "os" +} + +func isOSReader(object types.Object) bool { + function, ok := object.(*types.Func) + return ok && function.Pkg() != nil && function.Pkg().Path() == "os" +} + func resolveEnvName(call *ast.CallExpr, constants packageConstants) (string, bool) { if value, ok := literalString(call.Args[0]); ok { return value, true diff --git a/apps/backend/internal/testutil/envscan_test.go b/apps/backend/internal/testutil/envscan_test.go index 115be8f84c..95f2f59ae6 100644 --- a/apps/backend/internal/testutil/envscan_test.go +++ b/apps/backend/internal/testutil/envscan_test.go @@ -87,6 +87,131 @@ func read() (string, bool) { return os.LookupEnv("BAR") } } } +// TestUncoveredEnvReadsUncoveredAliasedOSImport ensures a local import name +// cannot hide an environment read from the hermetic-environment guard. +func TestUncoveredEnvReadsUncoveredAliasedOSImport(t *testing.T) { + fileSet, file := parseSnippet(t, `package example + +import stdos "os" + +func read() string { return stdos.Getenv("BAR") } +`) + + messages := uncoveredEnvReads(fileSet, []*ast.File{file}, nil, nil) + if len(messages) != 1 { + t.Fatalf("expected exactly one uncovered-name message, got %v", messages) + } + if !strings.Contains(messages[0], "BAR") { + t.Fatalf("message %q does not name the uncovered variable", messages[0]) + } +} + +// TestUncoveredEnvReadsCoveredAliasedOSImport documents that alias resolution +// uses the same scrub/exempt classification as the ordinary os import path. +func TestUncoveredEnvReadsCoveredAliasedOSImport(t *testing.T) { + fileSet, file := parseSnippet(t, `package example + +import stdos "os" + +func read() string { return stdos.Getenv("FOO") } +`) + + messages := uncoveredEnvReads(fileSet, []*ast.File{file}, []string{"FOO"}, nil) + if len(messages) != 0 { + t.Fatalf("covered aliased read reported as uncovered: %v", messages) + } +} + +// TestUncoveredEnvReadsIgnoresShadowedAliasedOSImport ensures a local binding +// with the import's spelling does not turn an unrelated Getenv method into an +// environment read. +func TestUncoveredEnvReadsIgnoresShadowedAliasedOSImport(t *testing.T) { + fileSet, file := parseSnippet(t, `package example + +import stdos "os" + +type reader struct{} + +func (reader) Getenv(string) string { return "" } + +func read(stdos reader) string { return stdos.Getenv("BAR") } +func genuineRead() string { return stdos.Getenv("REAL") } +`) + + messages := uncoveredEnvReads(fileSet, []*ast.File{file}, nil, nil) + if len(messages) != 1 || !strings.Contains(messages[0], "REAL") { + t.Fatalf("expected only the genuine aliased os read, got %v", messages) + } +} + +func TestUncoveredEnvReadsUncoveredDotImportedOS(t *testing.T) { + fileSet, file := parseSnippet(t, `package example + +import . "os" + +func getenv() string { return Getenv("BAR") } +func lookupenv() (string, bool) { return LookupEnv("BAZ") } +`) + + messages := uncoveredEnvReads(fileSet, []*ast.File{file}, nil, nil) + if len(messages) != 2 { + t.Fatalf("expected exactly two uncovered-name messages, got %v", messages) + } + if !strings.Contains(messages[0], "BAR") || !strings.Contains(messages[1], "BAZ") { + t.Fatalf("messages %q do not name both uncovered variables", messages) + } +} + +// TestUncoveredEnvReadsCoveredDotImportedOS documents that dot-imported reads +// are classified against the caller's scrubbed and exempt environment names. +func TestUncoveredEnvReadsCoveredDotImportedOS(t *testing.T) { + fileSet, file := parseSnippet(t, `package example + +import . "os" + +func getenv() string { return Getenv("FOO") } +func lookupenv() (string, bool) { return LookupEnv("BAR") } +`) + + messages := uncoveredEnvReads(fileSet, []*ast.File{file}, []string{"FOO"}, []string{"BAR"}) + if len(messages) != 0 { + t.Fatalf("covered dot-imported reads reported as uncovered: %v", messages) + } +} + +// TestUncoveredEnvReadsIgnoresShadowedDotImportedOS ensures a local Getenv +// binding does not turn an unrelated function value into an environment read. +func TestUncoveredEnvReadsIgnoresShadowedDotImportedOS(t *testing.T) { + fileSet, file := parseSnippet(t, `package example + +import . "os" + +func read(Getenv func(string) string) string { return Getenv("BAR") } +func genuineRead() string { return Getenv("REAL") } +`) + + messages := uncoveredEnvReads(fileSet, []*ast.File{file}, nil, nil) + if len(messages) != 1 || !strings.Contains(messages[0], "REAL") { + t.Fatalf("expected only the genuine dot-imported os read, got %v", messages) + } +} + +// TestUncoveredEnvReadsIgnoresLocalPackageNamedOS ensures a package name does +// not make a local Getenv function look like the standard os.Getenv function. +func TestUncoveredEnvReadsIgnoresLocalPackageNamedOS(t *testing.T) { + fileSet, file := parseSnippet(t, `package os + +func Getenv(string) string { return "" } + +func read() string { return Getenv("BAR") } +`) + + messages := uncoveredEnvReads(fileSet, []*ast.File{file}, nil, nil) + if len(messages) != 0 { + t.Fatalf("local package Getenv should not be scanned, got %v", messages) + } +} + func TestUncoveredEnvReadsUnresolvableIdentifier(t *testing.T) { fileSet, file := parseSnippet(t, `package example diff --git a/docs/plans/env-scrub-drift-guards/plan.md b/docs/plans/env-scrub-drift-guards/plan.md new file mode 100644 index 0000000000..32d2f17a6a --- /dev/null +++ b/docs/plans/env-scrub-drift-guards/plan.md @@ -0,0 +1,90 @@ +--- +created: 2026-09-14 +status: done +requirements: + - REQ-INTEGRATIONS-GITLAB-INTEGRATION-001 + - REQ-INTEGRATIONS-GITHUB-AUTHENTICATION-001 +system_design: + - ../../specs/integrations/system-design/gitlab-integration-02.md + - ../../specs/integrations/system-design/github-authentication-01.md +legacy_specs: [] +--- + +# Implementation plan: Environment scrub drift guards + +## Overview + +Keep the hermetic environment scrubs used by the GitHub and GitLab integration +test suites from silently falling behind the environment reads those packages +actually perform. One shared scanner in `internal/testutil` resolves the +file-local binding of the `os` package, so an aliased or dot-imported +`os.Getenv` / `os.LookupEnv` call is classified the same way as a plain +`os.Getenv` call instead of bypassing the guard. + +The integrations system owns this package because the guarded scrubs exist to +make the providers' environment-credential fallbacks deterministic under test: +an ambient `GITLAB_TOKEN` or `GH_TOKEN` from a developer shell would otherwise +silently activate those fallbacks and change which connection path a test +exercises. + +## Scope + +In scope: import-aware classification of `os` environment reads in the shared +scanner, adopting it for the GitHub guard, and regression coverage for every +classified import form. + +Out of scope: production credential resolution, new environment fallbacks, +bulk `os.Environ`-style unnamed reads, non-`os` accessors such as +`syscall.Getenv`, and public user documentation. + +## Technical approach + +The original guard matched the literal identifier `os`, which left aliased and +dot-imported calls unscanned. `AssertEnvReadsCovered` now resolves identifier +bindings with `go/types` per file: a selector counts as an environment read +when its package identifier is bound to import path `os`, and a bare +`Getenv` / `LookupEnv` call counts when the identifier resolves to the `os` +package function. Type errors in unrelated package code do not stop the scan +because only import bindings are consulted. + +`internal/github`'s package-local guard is replaced by the shared scanner, so +the GitHub and GitLab/process scrubs now follow one classification rule. + +## Tests + +| Criteria | Evidence | +| --- | --- | +| Aliased `os` import reads are reported as uncovered | `envscan_test.go` import-variant fixtures | +| Dot-imported `Getenv` / `LookupEnv` count as reads | `envscan_test.go` dot-import fixtures | +| Plain imports, extra readers, and non-`os` selectors stay unchanged | Existing `envscan_test.go` suite plus `internal/github` and `internal/gitlab` hermetic suites | + +Red-green evidence: the aliased-import regression failed before the scanner +change and passed after it; the remaining import-variant tests pass against +the shared scanner. + +## Work orders + +- [x] [Task 01: Scan aliased os environment reads](task-01-scan-aliased-os-reads.md) + +## Verification results + +Commands run from `apps/backend` with the workspace GOMODCACHE/GOCACHE: + +- `go test -count=1 ./internal/testutil ./internal/github/... ./internal/gitlab/...`: passed. +- `gofmt -l` on changed files: clean. + +Existing referenced requirement and design documents are unchanged; they +qualify at the PR revision as-is. + +## Risks + +The scanner still does not name bulk unnamed environment reads or non-`os` +accessors; those channels remain outside a name-keyed scrub list and are +guarded by `extraReaders` and review instead. + +## References + +- [GitLab requirements](../../specs/integrations/requirements/gitlab-integration.md) +- [GitLab system design](../../specs/integrations/system-design/gitlab-integration-02.md) +- [GitHub authentication requirements](../../specs/integrations/requirements/github-authentication.md) +- [GitHub authentication system design](../../specs/integrations/system-design/github-authentication-01.md) diff --git a/docs/plans/env-scrub-drift-guards/task-01-scan-aliased-os-reads.md b/docs/plans/env-scrub-drift-guards/task-01-scan-aliased-os-reads.md new file mode 100644 index 0000000000..6aea83f8bd --- /dev/null +++ b/docs/plans/env-scrub-drift-guards/task-01-scan-aliased-os-reads.md @@ -0,0 +1,106 @@ +--- +id: "01-scan-aliased-os-reads" +title: "Scan aliased os environment reads" +status: done +wave: 1 +depends_on: [] +plan: "plan.md" +requirements: + - REQ-INTEGRATIONS-GITLAB-INTEGRATION-001 + - REQ-INTEGRATIONS-GITHUB-AUTHENTICATION-001 +acceptance_criteria: + - AC-INTEGRATIONS-GITLAB-INTEGRATION-001.4 + - AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.1 +system_design: + - ../../specs/integrations/system-design/gitlab-integration-02.md + - ../../specs/integrations/system-design/github-authentication-01.md +--- + +# Task 01: Scan aliased os environment reads + +## Summary + +Close the classification gap that let an aliased or dot-imported +`os.Getenv` / `os.LookupEnv` call bypass the shared hermetic-environment +guard, and adopt that guard for the GitHub suite instead of its +package-local copy. + +## In scope + +- `apps/backend/internal/testutil/envscan.go` +- `apps/backend/internal/testutil/envscan_test.go` +- `apps/backend/internal/github/env_hermetic_test.go` + +## Out of scope + +Production credential resolution, new environment fallbacks, bulk unnamed +reads such as `os.Environ`, non-`os` accessors such as `syscall.Getenv`, and +public user documentation. + +## Acceptance + +- An aliased `os` import is classified and reports an uncovered environment + variable; the regression was red before the scanner change and green after. +- Dot-imported bare `Getenv` / `LookupEnv` calls and shadowed local `os` + declarations are classified by their actual binding, not by spelling. +- Existing plain-import scanning, extra readers, and non-`os` selectors keep + their behavior; the GitHub, GitLab, and process hermetic suites pass + against the shared scanner. +- The GitLab `GITLAB_TOKEN` environment fallback and the GitHub + workspace-source selection stay testable without ambient shell credentials + sabotaging the scrubbed fixtures. + +## Verification + +Run from `apps/backend`: + +```bash +GOMODCACHE= GOCACHE= \ + go test -count=1 ./internal/testutil ./internal/github/... ./internal/gitlab/... +gofmt -l internal/testutil/envscan.go internal/testutil/envscan_test.go internal/github/env_hermetic_test.go +``` + +## Files likely touched + +- `apps/backend/internal/testutil/envscan.go` +- `apps/backend/internal/testutil/envscan_test.go` +- `apps/backend/internal/github/env_hermetic_test.go` +- This plan and work order. + +## Dependencies + +None. The GitLab and process scrubs already used the shared scanner. + +## Risks + +The `go/types` pass resolves bindings per file and ignores type errors +elsewhere; keeping that tolerance documented avoids a future "fix" that +makes the guard fail on unrelated broken code. + +## Parallelism + +`sequential` + +## Inputs + +- [Plan](plan.md) +- [GitLab requirements](../../specs/integrations/requirements/gitlab-integration.md), criterion `AC-INTEGRATIONS-GITLAB-INTEGRATION-001.4` +- [GitLab system design](../../specs/integrations/system-design/gitlab-integration-02.md) +- [GitHub authentication requirements](../../specs/integrations/requirements/github-authentication.md), criterion `AC-INTEGRATIONS-GITHUB-AUTHENTICATION-001.1` +- [GitHub authentication system design](../../specs/integrations/system-design/github-authentication-01.md) + +## Results + +The scanner derives the file-local import name bound to package path `os` +through `go/types`, so alias and dot-import forms are classified exactly like +plain `os.Getenv` / `os.LookupEnv` calls. `internal/github` now reuses the +shared `testutil.AssertEnvReadsCovered` instead of its package-local copy. + +Verification on 2026-09-09 (focused suites) recorded in the PR: + +- `go test -count=1 ./internal/testutil ./internal/github/... ./internal/gitlab/...`: passed. +- `gofmt -l`: clean on the changed files. + +The aliased-import regression was red before the scanner change and green +afterward. Existing standard `os` calls, extra readers, and non-`os` +selectors retain behavior.