refactor: drop comments that restate the code

Delete about 6,400 comment lines across cmd/ and internal/: doc
comments that repeat a name, step narration, banners, "X is TS Y"
notes the parity and oracle tests already pin, history of fixed bugs,
issue tags, and divergence notes that docs/DIVERGENCES.md or
docs/go-only-features.md already record.

Kept: comments about behaviour we cannot change (Docker, BuildKit,
Compose, git, POSIX shell, Go's standard library, JavaScript and V8
semantics the reference forces), the recipe that regenerates the
ts-features-build goldens, and divergences recorded nowhere else.
Every //go:, //nolint, mutate-lane and mutate-exempt comment is
untouched. Only comments change: each file parses to the same AST
once comments are stripped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: aledbf

cmd/devtool/main.go

@@ -1,8 +1,3 @@
-// Command devtool is the repo's CI/dev helper, replacing the former scripts/*.sh.
-// Its commands live in internal/devtools (devtools.Main), which wires stdin/stdout,
-// git, `go tool`, and docker around the pure, unit-tested logic there. Invoked
-// from the Taskfile and the CI workflow (e.g. `go run ./cmd/devtool coverage-gate
-// coverage.out TOTAL=48`).
 package main
 
 import (

cmd/devtool/main_test.go

@@ -8,16 +8,13 @@ import (
 	"testing"
 )
 
-// TestMain runs the command itself, instead of the tests, in the child process
-// TestTheCommandIsWired starts.
 func TestMain(m *testing.M) {
 	if os.Getenv("DEVTOOL_RUN_MAIN") == "1" {
 		main()
 	}
 	os.Exit(m.Run())
 }
 
-// devtool runs this test binary as the devtool command, with args and stdin.
 func devtool(t *testing.T, stdin string, args ...string) (code int, stdout, stderr string) {
 	t.Helper()
 	cmd := exec.Command(os.Args[0], args...)
@@ -35,8 +32,6 @@ func devtool(t *testing.T, stdin string, args ...string) (code int, stdout, stde
 	return cmd.ProcessState.ExitCode(), o.String(), e.String()
 }
 
-// TestTheCommandIsWired holds what main adds to devtools.Main: the process's
-// arguments, standard streams and exit code.
 func TestTheCommandIsWired(t *testing.T) {
 	if code, out, errOut := devtool(t, "internal/cli/exec.go\n", "parity-affected"); code != 0 || out != "exec\n" || errOut != "" {
 		t.Errorf("parity-affected: code=%d stdout=%q stderr=%q, want 0 \"exec\\n\" \"\"", code, out, errOut)

internal/cli/build.go

@@ -7,14 +7,7 @@ import (
 	"github.com/devcontainers/cli/internal/oci"
 )
 
-// bridgeBuildAuth resolves credentials for every registry a build touches (base
-// image, push tags, cache import/export) via the CLI's credential chain and, when
-// any resolve, returns the subprocess env (DOCKER_CONFIG=<tmp>) plus a cleanup
-// func. It returns (nil, no-op) when there is nothing to bridge, leaving the
-// build's ambient auth untouched. Errors are swallowed (best-effort): a build
-// that would have worked anonymously must not fail because auth bridging did.
 func bridgeBuildAuth(logger log.Logger, baseImage string, tags, cacheFrom []string, cacheTo string) (env []string, cleanup func()) {
-	// With no registry to bridge, ResolveBuildAuth resolves nothing and is not ok.
 	regs := collectBuildRegistries(baseImage, tags, cacheFrom, cacheTo)
 	dir, clean, ok, err := oci.ResolveBuildAuth(osEnvMap(), regs, logger)
 	if err != nil || !ok {
@@ -23,7 +16,6 @@ func bridgeBuildAuth(logger log.Logger, baseImage string, tags, cacheFrom []stri
 	return []string{"DOCKER_CONFIG=" + dir}, clean
 }
 
-// collectBuildRegistries returns the deduped registry hosts referenced by a build.
 func collectBuildRegistries(baseImage string, tags, cacheFrom []string, cacheTo string) []string {
 	var out []string
 	seen := map[string]bool{}
@@ -64,9 +56,6 @@ func registryHostFromImageRef(ref string) string {
 	return ""
 }
 
-// registryCacheRef pulls the image reference out of a buildx cache spec. A
-// registry cache is written as "type=registry,ref=<image>[,...]"; anything else
-// (type=local/inline/gha, or a bare image) is returned as-is.
 func registryCacheRef(spec string) string {
 	spec = strings.TrimSpace(spec)
 	if spec == "" || !strings.Contains(spec, "=") {

internal/cli/build_auth.go

@@ -9,8 +9,6 @@ import (
 	"github.com/devcontainers/cli/internal/log"
 )
 
-// isolateBuildAuth points the credential chain at an empty docker config, so
-// only DEVCONTAINERS_OCI_AUTH can supply credentials.
 func isolateBuildAuth(t *testing.T, ociAuth string) {
 	t.Helper()
 	dir := t.TempDir()
@@ -22,8 +20,6 @@ func isolateBuildAuth(t *testing.T, ociAuth string) {
 	t.Setenv("DEVCONTAINERS_OCI_AUTH", ociAuth)
 }
 
-// A build whose registries have no credentials keeps its ambient auth: no
-// DOCKER_CONFIG is handed to the build.
 func TestBridgeBuildAuthWithoutCredentials(t *testing.T) {
 	isolateBuildAuth(t, "")
 	env, cleanup := bridgeBuildAuth(log.Null, "reg.example.com/base:1", nil, nil, "")
@@ -33,7 +29,6 @@ func TestBridgeBuildAuthWithoutCredentials(t *testing.T) {
 	}
 }
 
-// Credentials that resolve are bridged through a temporary DOCKER_CONFIG.
 func TestBridgeBuildAuthWithCredentials(t *testing.T) {
 	isolateBuildAuth(t, "reg.example.com|alice|secret")
 	env, cleanup := bridgeBuildAuth(log.Null, "reg.example.com/base:1", nil, nil, "")

internal/cli/build_auth_held_test.go

@@ -12,12 +12,11 @@ func TestRegistryHostFromImageRef(t *testing.T) {
 		"myreg.example.com:5000/team/app":               "myreg.example.com:5000",
 		"localhost:5000/app":                            "localhost:5000",
 		"123456.dkr.ecr.us-east-1.amazonaws.com/repo:1": "123456.dkr.ecr.us-east-1.amazonaws.com",
-		// Docker Hub forms → no explicit registry → "" (ambient auth applies).
-		"ubuntu:22.04":   "",
-		"library/ubuntu": "",
-		"org/img:tag":    "",
-		"mcr":            "",
-		"":               "",
+		"ubuntu:22.04":                                  "",
+		"library/ubuntu":                                "",
+		"org/img:tag":                                   "",
+		"mcr":                                           "",
+		"":                                              "",
 	}
 	for ref, want := range cases {
 		if got := registryHostFromImageRef(ref); got != want {
@@ -30,9 +29,9 @@ func TestRegistryCacheRef(t *testing.T) {
 	cases := map[string]string{
 		"type=registry,ref=ghcr.io/org/cache:main": "ghcr.io/org/cache:main",
 		"type=registry,ref=myreg.com/c,mode=max":   "myreg.com/c",
-		"type=local,dest=/tmp/c":                   "", // not a registry cache
+		"type=local,dest=/tmp/c":                   "",
 		"type=inline":                              "",
-		"ghcr.io/org/cache:main":                   "ghcr.io/org/cache:main", // bare ref
+		"ghcr.io/org/cache:main":                   "ghcr.io/org/cache:main",
 		"":                                         "",
 	}
 	for spec, want := range cases {
@@ -44,10 +43,10 @@ func TestRegistryCacheRef(t *testing.T) {
 
 func TestCollectBuildRegistries(t *testing.T) {
 	got := collectBuildRegistries(
-		"ghcr.io/base/img:1", // base
-		[]string{"ghcr.io/base/img:1", "reg.example.com/app:2", "ubuntu"},            // tags (dup base, hub)
-		[]string{"type=registry,ref=cache.example.com/c:main", "type=local,dest=/x"}, // cacheFrom
-		"type=registry,ref=cache.example.com/c:main",                                 // cacheTo (dup of cacheFrom)
+		"ghcr.io/base/img:1",
+		[]string{"ghcr.io/base/img:1", "reg.example.com/app:2", "ubuntu"},
+		[]string{"type=registry,ref=cache.example.com/c:main", "type=local,dest=/x"},
+		"type=registry,ref=cache.example.com/c:main",
 	)
 	want := []string{"ghcr.io", "reg.example.com", "cache.example.com"}
 	if !reflect.DeepEqual(got, want) {
@@ -56,7 +55,6 @@ func TestCollectBuildRegistries(t *testing.T) {
 }
 
 func TestCollectBuildRegistriesEmpty(t *testing.T) {
-	// Only Docker Hub / local caches → nothing to bridge.
 	if got := collectBuildRegistries("ubuntu:22.04", []string{"org/app"}, []string{"type=inline"}, ""); len(got) != 0 {
 		t.Fatalf("expected no registries, got %v", got)
 	}

internal/cli/build_auth_test.go

@@ -7,9 +7,6 @@ import (
 	"github.com/devcontainers/cli/internal/config"
 )
 
-// TestCacheFromForDockerfileBuild pins the merge of the --cache-from flag with
-// devcontainer.json build.cacheFrom: flag values first, then config values, in
-// order — matching TS singleContainer (additionalCacheFroms, then config.build.cacheFrom).
 func TestCacheFromForDockerfileBuild(t *testing.T) {
 	cfgWith := func(cf ...string) *config.DevContainer {
 		return &config.DevContainer{Build: &config.Build{CacheFrom: config.StringOrStrings(cf)}}
@@ -38,9 +35,6 @@ func TestCacheFromForDockerfileBuild(t *testing.T) {
 	}
 }
 
-// TestCacheFromForDockerfileBuildDoesNotMutateFlag guards against the helper
-// aliasing/appending into the caller's flag slice (which extendImageWithFeatures
-// still passes verbatim for the feature layers).
 func TestCacheFromForDockerfileBuildDoesNotMutateFlag(t *testing.T) {
 	flagBacking := []string{"flag1", "sentinel"}
 	flag := flagBacking[:1]

internal/cli/build_cachefrom_test.go

@@ -9,13 +9,6 @@ import (
 	"github.com/devcontainers/cli/internal/log"
 )
 
-// TestBuildComposePathWiring verifies that the `build` command threads
-// --docker-compose-path into docker.NewComposeClient. When the call site
-// hardcodes "" instead, the operator-supplied path could never appear in the
-// compose-client detection error ("neither 'docker compose' nor '<path>'
-// found"). The test is hermetic: dockerPath points at a nonexistent binary so
-// the `docker compose` (v2) probe always fails regardless of the host, forcing
-// NewComposeClient down the custom-path branch.
 func TestBuildComposePathWiring(t *testing.T) {
 	tests := []struct {
 		name              string
@@ -39,8 +32,6 @@ func TestBuildComposePathWiring(t *testing.T) {
 			r := &buildRunner{
 				log: log.New(log.Options{Writer: io.Discard}),
 				opts: &buildOpts{
-					// Force the `docker compose` (v2) probe to fail hermetically,
-					// independent of whether Docker is installed on the host.
 					dockerPath:        "/nonexistent/docker-binary",
 					dockerComposePath: tt.dockerComposePath,
 				},

internal/cli/build_compose_path_test.go

@@ -17,8 +17,6 @@ import (
 
 func discardLogger() log.Logger { return log.New(log.Options{Writer: io.Discard}) }
 
-// The deprecated --experimental-frozen-lockfile and --frozen-lockfile both
-// make the Feature build verify the lockfile, as TS effectiveFrozenLockfile.
 func TestBuildFrozenLockfileReachesTheFeatureBuild(t *testing.T) {
 	for _, tc := range []struct {
 		name                 string
@@ -187,9 +185,6 @@ func TestBuildxSecrets(t *testing.T) {
 	}
 }
 
-// --buildkit never skips BuildKit detection, so the build runs as if buildx
-// were absent even when the Docker CLI has it. The fake --docker-path reports
-// buildx, and both cases stop at the flag check before any Docker build.
 func TestRunBuildBuildKitNeverIgnoresBuildx(t *testing.T) {
 	bin := t.TempDir()
 	docker := filepath.Join(bin, "docker")
@@ -227,9 +222,6 @@ func TestRunBuildBuildKitNeverIgnoresBuildx(t *testing.T) {
 	}
 }
 
-// The Dockerfile build targets the config's target when it names one, else
-// the final stage, named when it has no name; a Dockerfile without FROM is
-// TS's error.
 func TestPrepareDockerfileBuildStage(t *testing.T) {
 	ws := writeConfigFixture(t, map[string]string{
 		".devcontainer/Dockerfile": "FROM alpine:3 AS base\nFROM base\n",
@@ -257,9 +249,6 @@ func TestPrepareDockerfileBuildStage(t *testing.T) {
 	}
 }
 
-// A Compose build without --image-name reports its image as a string, as TS
-// doBuild does (imageNameResult = originalImageName); with --image-name, and
-// for any other configuration, the names are an array.
 func TestBuildResultImageName(t *testing.T) {
 	for _, tc := range []struct {
 		name     string

internal/cli/build_held_test.go

@@ -7,9 +7,6 @@ import (
 	"testing"
 )
 
-// A build whose image or Dockerfile step fails before any Docker call reports
-// the failure on stdout and exits 1, never the success envelope: a legacy
-// Feature id as the bare message, any other failure as a container error.
 func TestRunBuildReportsAFailedBuildStep(t *testing.T) {
 	for name, tc := range map[string]struct {
 		config string