[purelock] Lock down parseImportSpecsFromObject, relativizeIncludedFilePath, resolveCacheStepName with pure-function test suites (#54235)

Author: github-actions[bot]

docs/adr/54235-adopt-purelock-batch-testing-for-pure-function-coverage.md

@@ -0,0 +1,45 @@
+# ADR-54235: Adopt PureLock Batch Testing for Pure-Function Coverage Lockdown
+
+**Date**: 2026-08-20
+**Status**: Draft
+**Deciders**: pelikhan, PureLock automation (app/github-actions)
+
+---
+
+### Context
+
+Three Go functions in `pkg/parser` and `pkg/workflow` had 0% function coverage with no systematic mechanism to detect or address such gaps: `parseImportSpecsFromObject` (`pkg/parser/import_bfs.go:88`), `relativizeIncludedFilePath` (`pkg/parser/include_expander.go:100`), and `resolveCacheStepName` (`pkg/workflow/cache_steps.go:75`). All three are pure functions — no I/O, no global mutation, no observable side effects — making them safe targets for automated test generation. The PureLock workflow identifies pure-function coverage gaps from a ranked candidate list and generates maximal-coverage table-driven test suites in batch PRs to close those gaps.
+
+### Decision
+
+We will use the PureLock automated batch workflow to systematically identify pure Go functions with 0% function coverage and lock them down with table-driven unit test suites targeting 100% function coverage per function. Each batch PR targets functions confirmed pure by static analysis and manual inspection; fuzz testing is used only when marked explicitly fuzz-friendly and table-driven cases do not achieve full coverage. Tests are committed directly to the package under test (e.g., `pkg/parser/import_bfs_test.go`) using the `!integration` build tag.
+
+### Alternatives Considered
+
+#### Alternative 1: Rely on ad-hoc test coverage during feature work
+
+The default model where developers add tests for new or changed code as part of feature PRs. This is well-understood and keeps tests co-located with the motivating change, but it does not systematically surface coverage gaps in pre-existing pure functions that have never been tested. The three functions in this PR had been in the codebase with 0% coverage indefinitely.
+
+#### Alternative 2: Use Go fuzzing (`go test -fuzz`) for pure-function coverage
+
+Some PureLock candidates are marked fuzz-friendly. Fuzzing is powerful for detecting edge cases in deterministic functions, but it requires a persistent corpus, is slower than table-driven tests in CI, and is overkill when a small set of structural branches can be exhaustively enumerated. For these three functions, table-driven cases provided 100% function coverage without fuzzing overhead.
+
+### Consequences
+
+#### Positive
+- `parseImportSpecsFromObject`, `relativizeIncludedFilePath`, and `resolveCacheStepName` move from 0% to 100% function coverage, protecting against regressions in pure business logic.
+- Establishes a repeatable, auditable batch pattern for closing coverage gaps in side-effect-free functions across the codebase.
+- Test suites are fully deterministic and run under `-race`, catching data-race regressions.
+
+#### Negative
+- Automated test-only batch PRs cross volume thresholds in business logic directories, triggering ADR enforcement gates even when no production architecture is changing.
+- Reviewers must validate AI-generated test cases match the intended behavior of the production function, not just the observed behavior at generation time.
+- Pre-existing unrelated test failures in the sandbox environment (network-restricted and `/dev/fd`-dependent tests) must be manually distinguished from failures introduced by this change.
+
+#### Neutral
+- Package-level statement coverage changes are marginal (e.g., `pkg/parser` 72.1% → 72.4%) because function coverage targets only the specific locked-down functions, not untested statement branches within other functions.
+- The `!integration` build tag keeps these tests out of integration test runs, consistent with existing patterns in `pkg/parser` and `pkg/workflow`.
+
+---
+
+*ADR created by [adr-writer agent]. Review and finalize before changing status from Draft to Accepted.*

pkg/parser/import_bfs_test.go

@@ -18,3 +18,90 @@ func TestParseImportSpecsFromArray_RejectsIfField(t *testing.T) {
 	require.Error(t, err)
 	require.ErrorContains(t, err, "import 'if' is no longer supported")
 }
+
+func TestParseImportSpecsFromObject(t *testing.T) {
+	tests := []struct {
+		name          string
+		importsObject map[string]any
+		wantSpecs     []ImportSpec
+		wantErr       string
+	}{
+		{
+			name:          "no aw key returns nil, nil",
+			importsObject: map[string]any{},
+			wantSpecs:     nil,
+		},
+		{
+			name:          "aw key present but nil value falls to default case",
+			importsObject: map[string]any{"aw": nil},
+			wantErr:       "imports.aw must be an array of strings or objects",
+		},
+		{
+			name: "aw as []any of strings",
+			importsObject: map[string]any{
+				"aw": []any{"shared/a.md", "shared/b.md"},
+			},
+			wantSpecs: []ImportSpec{{Path: "shared/a.md"}, {Path: "shared/b.md"}},
+		},
+		{
+			name: "aw as []any of objects",
+			importsObject: map[string]any{
+				"aw": []any{
+					map[string]any{"path": "shared/c.md"},
+				},
+			},
+			wantSpecs: []ImportSpec{{Path: "shared/c.md"}},
+		},
+		{
+			name: "aw as []any propagates array parse error",
+			importsObject: map[string]any{
+				"aw": []any{
+					map[string]any{"nope": "shared/d.md"},
+				},
+			},
+			wantErr: "imports.aw: import object must have a 'path' or 'uses' field",
+		},
+		{
+			name: "aw as []string",
+			importsObject: map[string]any{
+				"aw": []string{"shared/e.md", "shared/f.md"},
+			},
+			wantSpecs: []ImportSpec{{Path: "shared/e.md"}, {Path: "shared/f.md"}},
+		},
+		{
+			name: "aw as []string empty slice returns empty (non-nil) specs",
+			importsObject: map[string]any{
+				"aw": []string{},
+			},
+			wantSpecs: []ImportSpec{},
+		},
+		{
+			name: "aw as unsupported type (string) returns error",
+			importsObject: map[string]any{
+				"aw": "shared/g.md",
+			},
+			wantErr: "imports.aw must be an array of strings or objects",
+		},
+		{
+			name: "aw as unsupported type (map) returns error",
+			importsObject: map[string]any{
+				"aw": map[string]any{"path": "shared/h.md"},
+			},
+			wantErr: "imports.aw must be an array of strings or objects",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			specs, err := parseImportSpecsFromObject(tt.importsObject)
+			if tt.wantErr != "" {
+				require.Error(t, err)
+				require.ErrorContains(t, err, tt.wantErr)
+				require.Nil(t, specs)
+				return
+			}
+			require.NoError(t, err)
+			require.Equal(t, tt.wantSpecs, specs)
+		})
+	}
+}

pkg/parser/include_expander_relativize_test.go

@@ -0,0 +1,77 @@
+//go:build !integration
+
+package parser
+
+import (
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestRelativizeIncludedFilePath(t *testing.T) {
+	tests := []struct {
+		name     string
+		baseDir  string
+		repoRoot string
+		filePath string
+		want     string
+	}{
+		{
+			name:     "file under baseDir returns baseDir-relative slash path",
+			baseDir:  filepath.FromSlash("/repo/workflows"),
+			repoRoot: filepath.FromSlash("/repo"),
+			filePath: filepath.FromSlash("/repo/workflows/shared/a.md"),
+			want:     "shared/a.md",
+		},
+		{
+			name:     "file equal to baseDir returns dot",
+			baseDir:  filepath.FromSlash("/repo/workflows"),
+			repoRoot: filepath.FromSlash("/repo"),
+			filePath: filepath.FromSlash("/repo/workflows"),
+			want:     ".",
+		},
+		{
+			name:     "file outside baseDir but under repoRoot returns repoRoot-relative slash path",
+			baseDir:  filepath.FromSlash("/repo/workflows"),
+			repoRoot: filepath.FromSlash("/repo"),
+			filePath: filepath.FromSlash("/repo/.github/shared/b.md"),
+			want:     ".github/shared/b.md",
+		},
+		{
+			name:     "file outside both baseDir and repoRoot returns slash-converted absolute path",
+			baseDir:  filepath.FromSlash("/repo/workflows"),
+			repoRoot: filepath.FromSlash("/repo"),
+			filePath: filepath.FromSlash("/other/shared/c.md"),
+			want:     "/other/shared/c.md",
+		},
+		{
+			name:     "empty repoRoot with file outside baseDir falls back to slash-converted path",
+			baseDir:  filepath.FromSlash("/repo/workflows"),
+			repoRoot: "",
+			filePath: filepath.FromSlash("/other/shared/d.md"),
+			want:     "/other/shared/d.md",
+		},
+		{
+			name:     "empty repoRoot with file under baseDir still resolves via baseDir",
+			baseDir:  filepath.FromSlash("/repo/workflows"),
+			repoRoot: "",
+			filePath: filepath.FromSlash("/repo/workflows/e.md"),
+			want:     "e.md",
+		},
+		{
+			name:     "file equal to repoRoot when outside baseDir returns dot",
+			baseDir:  filepath.FromSlash("/repo/workflows"),
+			repoRoot: filepath.FromSlash("/repo"),
+			filePath: filepath.FromSlash("/repo"),
+			want:     ".",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := relativizeIncludedFilePath(tt.baseDir, tt.repoRoot, tt.filePath)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}

pkg/workflow/cache_steps_test.go

@@ -0,0 +1,104 @@
+//go:build !integration
+
+package workflow
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func TestResolveCacheStepName(t *testing.T) {
+	tests := []struct {
+		name  string
+		cache map[string]any
+		idx   int
+		total int
+		want  string
+	}{
+		{
+			name:  "name field present takes priority over everything",
+			cache: map[string]any{"name": "My Cache", "key": "some-key"},
+			idx:   0,
+			total: 1,
+			want:  "My Cache",
+		},
+		{
+			name:  "empty name string falls through to key",
+			cache: map[string]any{"name": "", "key": "some-key"},
+			idx:   0,
+			total: 1,
+			want:  "Cache (some-key)",
+		},
+		{
+			name:  "non-string name falls through to key",
+			cache: map[string]any{"name": 42, "key": "some-key"},
+			idx:   0,
+			total: 1,
+			want:  "Cache (some-key)",
+		},
+		{
+			name:  "no name, key present, single total returns key-based name",
+			cache: map[string]any{"key": "npm-cache"},
+			idx:   0,
+			total: 1,
+			want:  "Cache (npm-cache)",
+		},
+		{
+			name:  "empty key string falls through to default stepName",
+			cache: map[string]any{"key": ""},
+			idx:   0,
+			total: 1,
+			want:  "Cache",
+		},
+		{
+			name:  "non-string key falls through to default stepName",
+			cache: map[string]any{"key": 123},
+			idx:   0,
+			total: 1,
+			want:  "Cache",
+		},
+		{
+			name:  "no name or key, single total returns default Cache",
+			cache: map[string]any{},
+			idx:   0,
+			total: 1,
+			want:  "Cache",
+		},
+		{
+			name:  "no name or key, multiple total returns indexed default",
+			cache: map[string]any{},
+			idx:   0,
+			total: 3,
+			want:  "Cache 1",
+		},
+		{
+			name:  "no name or key, multiple total uses 1-based idx",
+			cache: map[string]any{},
+			idx:   2,
+			total: 3,
+			want:  "Cache 3",
+		},
+		{
+			name:  "key present with multiple total still prefers key over indexed default",
+			cache: map[string]any{"key": "build-cache"},
+			idx:   1,
+			total: 2,
+			want:  "Cache (build-cache)",
+		},
+		{
+			name:  "name present with multiple total still prefers name",
+			cache: map[string]any{"name": "Custom"},
+			idx:   1,
+			total: 2,
+			want:  "Custom",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := resolveCacheStepName(tt.cache, tt.idx, tt.total)
+			require.Equal(t, tt.want, got)
+		})
+	}
+}