package_budget_test.go

// Package verify enforces project-level structural invariants.
//
// This file adds the package-size budget gate (issue #594): a structural
// backstop that the per-function complexity linters cannot provide. Every
// gocyclo/gocognit/revive rule evaluates code INSIDE a single function, so a
// god-package assembled from a hundred small, low-complexity functions passes
// all of them. This test caps the size of a package as a whole, forcing
// decomposition before a package grows too large to reason about in isolation.
//
// The budgets are set at or just above today's largest package in each tree so
// the gate is green on the current tree and purely additive. They are ceilings
// to ratchet DOWN over time (in separate follow-up PRs), not numbers to raise
// when a package bumps against them: hitting the budget is the signal to
// decompose the package, not to relax the gate.
//
// Generated files (those carrying a "Code generated ... DO NOT EDIT." marker)
// are excluded from the count, so an embedded spec like internal/apidocs does
// not masquerade as hand-written code (#594, item 4).
//
// The gate covers pkg/ and internal/ on the same terms, with a separate ceiling
// per tree (#1079). internal/ was never exempt by design: it fell outside the
// walk because the walk was rooted at pkg/, so the ~12k lines that #894 and #895
// moved into internal/platform and internal/httpserver left budget coverage as a
// side effect of an API-stability change. A package that is too large to reason
// about is too large wherever it lives.
//
// Run: go test -run TestPackageSizeBudget .
package mcp_data_platform_test

import (
	"bufio"
	"fmt"
	"os"
	"path/filepath"
	"regexp"
	"sort"
	"strings"
	"testing"

	"github.com/stretchr/testify/require"
)

const (
	// maxPackageLOC caps non-generated, non-test lines per package under
	// pkg/. Measured with this gate after the #1121 portal decomposition, the
	// largest are pkg/platform (9,551 LOC), pkg/toolkits/apigateway (8,289)
	// and pkg/middleware (8,182); pkg/portal has come down from 11,796 to
	// 7,114 by moving its domain types, its stores, its authorization core and
	// its feedback surface to internal/portal/.
	//
	// At 9,600 the largest package under pkg/ is pkg/platform with 49 lines of
	// headroom, so this gate now pushes on pkg/platform: that is the intended
	// direction of the ratchet, not a side effect. Decomposing it is the next
	// target; raising this number is not.
	maxPackageLOC = 9600

	// maxPackageFiles caps non-generated, non-test .go files per package
	// under pkg/. The largest today (pkg/middleware) holds 33 files; this
	// ceiling leaves headroom and pressures decomposition.
	maxPackageFiles = 35

	// maxInternalPackageLOC caps non-generated, non-test lines per package
	// under internal/. Seeded at what was then the largest — internal/
	// platform/promptlayer at 3,418 LOC — rather than padded, so internal/
	// does not inherit the far looser pkg/ allowance it was never measured
	// against. The #1124 additions tripped the gate as designed and paid for
	// themselves by extracting the notifying store decorator into
	// promptlayer/notifystore, bringing promptlayer to 3,280 (still the
	// largest, with 138 lines of headroom). The ceiling stays where it was
	// seeded: growth is paid for by decomposition, not by raising the number.
	maxInternalPackageLOC = 3418

	// maxInternalPackageFiles caps non-generated, non-test .go files per
	// package under internal/. Seeded at the current largest, internal/
	// platform/promptlayer with 10 files.
	maxInternalPackageFiles = 10
)

// generatedMarkerRe matches the canonical "generated code" line that Go
// tooling (mockgen, stringer, protoc-gen-go, etc.) emits, as specified at
// https://go.dev/s/generatedcode. A file carrying this marker is excluded
// from the budget.
var generatedMarkerRe = regexp.MustCompile(`^// Code generated .* DO NOT EDIT\.$`)

// swagGeneratedMarkerRe matches swaggo/swag's non-conforming variant, which
// prefixes the marker with a package doc clause and omits the trailing period:
//
//	// Package apidocs Code generated by swaggo/swag. DO NOT EDIT
//
// internal/apidocs/docs.go carries exactly that line and is 19,750 lines of
// embedded OpenAPI document. The canonical regexp above does not match it, so
// without this second pattern extending the gate to internal/ would measure a
// generated spec as hand-written code. The pattern is kept narrow — a package
// clause, then the canonical wording — so it recognizes the tool that is
// actually in the tree without turning the marker into an opt-out anyone can
// paste onto a hand-written file.
var swagGeneratedMarkerRe = regexp.MustCompile(`^// Package \w+ Code generated .* DO NOT EDIT\.?$`)

// sizeBudget is the ceiling pair applied to one source tree.
type sizeBudget struct {
	tree  string
	loc   int
	files int
}

// packageSize accumulates the non-generated, non-test footprint of one package.
type packageSize struct {
	loc   int
	files int
}

// TestPackageSizeBudget fails when any package under pkg/ or internal/ exceeds
// its tree's LOC or file-count budget, counting only hand-written, non-test
// source.
//
// This is the structural counterpart to the per-function complexity gates:
// those bound the inside of a function, this bounds the size of a package.
// If it fails, decompose the offending package into cohesive sub-packages —
// do not raise the budget (that defeats the gate). See CONTRIBUTING.md,
// "Structural maintainability gates".
func TestPackageSizeBudget(t *testing.T) {
	projectRoot, err := filepath.Abs(".")
	require.NoError(t, err)

	budgets := []sizeBudget{
		{tree: "pkg", loc: maxPackageLOC, files: maxPackageFiles},
		{tree: "internal", loc: maxInternalPackageLOC, files: maxInternalPackageFiles},
	}

	var violations []string
	for _, b := range budgets {
		sizes, measureErr := measureTree(projectRoot, b.tree)
		require.NoError(t, measureErr)
		require.NotEmpty(t, sizes, "should find packages under %s/", b.tree)
		violations = append(violations, budgetViolations(sizes, b)...)
	}
	sort.Strings(violations)

	require.Empty(t, violations,
		"package size budget exceeded:\n  %s", strings.Join(violations, "\n  "))
}

// measureTree returns the non-generated, non-test footprint of every package
// under projectRoot/tree, keyed by the package's path relative to projectRoot.
func measureTree(projectRoot, tree string) (map[string]*packageSize, error) {
	sizes := map[string]*packageSize{}
	err := filepath.Walk(filepath.Join(projectRoot, tree), func(path string, info os.FileInfo, fErr error) error {
		if fErr != nil {
			return fErr
		}
		if info.IsDir() || !strings.HasSuffix(info.Name(), ".go") || strings.HasSuffix(info.Name(), "_test.go") {
			return nil
		}
		generated, loc, countErr := countGoFile(path)
		if countErr != nil {
			return countErr
		}
		if generated {
			return nil
		}
		dir := filepath.Dir(path)
		rel, relErr := filepath.Rel(projectRoot, dir)
		if relErr != nil {
			return fmt.Errorf("computing relative path for %s: %w", dir, relErr)
		}
		ps, ok := sizes[rel]
		if !ok {
			ps = &packageSize{}
			sizes[rel] = ps
		}
		ps.loc += loc
		ps.files++
		return nil
	})
	if err != nil {
		return nil, err
	}
	return sizes, nil
}

// budgetViolations reports the packages in sizes that exceed b.
func budgetViolations(sizes map[string]*packageSize, b sizeBudget) []string {
	var violations []string
	for pkg, ps := range sizes {
		if ps.loc > b.loc {
			violations = append(violations, fmt.Sprintf(
				"%s: %d LOC exceeds budget of %d (decompose the package; do not raise the budget)",
				pkg, ps.loc, b.loc))
		}
		if ps.files > b.files {
			violations = append(violations, fmt.Sprintf(
				"%s: %d files exceeds budget of %d (decompose the package; do not raise the budget)",
				pkg, ps.files, b.files))
		}
	}
	return violations
}

// TestCountGoFile exercises generated-marker detection and line counting
// directly. It is the unit that proves generated files are excluded from the
// budget (#594, item 4) and that line counting is correct.
func TestCountGoFile(t *testing.T) {
	tests := []struct {
		name          string
		content       string
		wantGenerated bool
		wantLOC       int
	}{
		{
			name:          "hand-written file is counted",
			content:       "package x\n\nfunc f() {}\n",
			wantGenerated: false,
			wantLOC:       3,
		},
		{
			name:          "swag-style generated marker is detected",
			content:       "// Code generated by swaggo/swag. DO NOT EDIT.\npackage docs\n",
			wantGenerated: true,
			wantLOC:       2,
		},
		{
			name:          "marker after a build constraint is still detected",
			content:       "//go:build ignore\n\n// Code generated by mockgen. DO NOT EDIT.\npackage m\n",
			wantGenerated: true,
			wantLOC:       4,
		},
		{
			name:          "a comment that merely mentions generated code is not a marker",
			content:       "package x\n// this is not Code generated by anything\n",
			wantGenerated: false,
			wantLOC:       2,
		},
		{
			name:          "swaggo's package-clause variant without the trailing period is detected",
			content:       "// Package apidocs Code generated by swaggo/swag. DO NOT EDIT\npackage apidocs\n",
			wantGenerated: true,
			wantLOC:       2,
		},
		{
			name:          "a package doc comment that is not a marker stays hand-written",
			content:       "// Package x holds hand-written code that mentions DO NOT EDIT\npackage x\n",
			wantGenerated: false,
			wantLOC:       2,
		},
	}
	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			path := filepath.Join(t.TempDir(), "f.go")
			require.NoError(t, os.WriteFile(path, []byte(tt.content), 0o600))

			generated, loc, err := countGoFile(path)
			require.NoError(t, err)
			require.Equal(t, tt.wantGenerated, generated)
			require.Equal(t, tt.wantLOC, loc)
		})
	}
}

// TestCountGoFile_MissingFile covers the open-error path.
func TestCountGoFile_MissingFile(t *testing.T) {
	_, _, err := countGoFile(filepath.Join(t.TempDir(), "does-not-exist.go"))
	require.Error(t, err)
}

// TestApidocsIsRecognizedAsGenerated pins the one file in the tree that the
// canonical marker misses. It is the largest file in the repository by an order
// of magnitude; if swaggo changes its header wording, this fails here with the
// cause named rather than as a 19k-line budget violation in internal/apidocs.
func TestApidocsIsRecognizedAsGenerated(t *testing.T) {
	generated, loc, err := countGoFile(filepath.Join("internal", "apidocs", "docs.go"))
	require.NoError(t, err)
	require.True(t, generated, "internal/apidocs/docs.go carries swaggo's generated marker")
	require.Greater(t, loc, maxInternalPackageLOC,
		"the file must be large enough that misdetecting it would breach the internal budget")
}

// TestBudgetViolationsFires proves both ceilings bite and that each tree is
// measured against its OWN budget: a package that is comfortably within the
// pkg/ allowance still fails the tighter internal/ one. Without this, seeding
// internal/ with the pkg/ constants would look identical to seeding it
// correctly.
func TestBudgetViolationsFires(t *testing.T) {
	sizes := map[string]*packageSize{
		"internal/platform/big":  {loc: maxInternalPackageLOC + 1, files: 1},
		"internal/platform/wide": {loc: 1, files: maxInternalPackageFiles + 1},
		"internal/platform/ok":   {loc: maxInternalPackageLOC, files: maxInternalPackageFiles},
	}
	internal := budgetViolations(sizes, sizeBudget{tree: "internal", loc: maxInternalPackageLOC, files: maxInternalPackageFiles})
	require.Len(t, internal, 2)
	sort.Strings(internal)
	require.Contains(t, internal[0], "internal/platform/big")
	require.Contains(t, internal[0], "LOC exceeds budget")
	require.Contains(t, internal[1], "internal/platform/wide")
	require.Contains(t, internal[1], "files exceeds budget")

	// The same sizes are within the looser pkg/ ceilings, so a budget applied
	// to the wrong tree would report nothing.
	require.Empty(t, budgetViolations(sizes, sizeBudget{tree: "pkg", loc: maxPackageLOC, files: maxPackageFiles}))
}

// countGoFile reports whether path is a generated file and, if not, how many
// lines it contains. Generated files are detected by the canonical
// "Code generated ... DO NOT EDIT." marker or swaggo's package-clause variant
// of it, which by convention appear before the package clause; scanning the
// whole file is cheap and avoids missing a marker placed after a
// build-constraint or license header.
func countGoFile(path string) (generated bool, loc int, err error) {
	f, err := os.Open(path) //nolint:gosec // test reads project source files
	if err != nil {
		return false, 0, fmt.Errorf("opening %s: %w", path, err)
	}
	defer func() { _ = f.Close() }()

	scanner := bufio.NewScanner(f)
	scanner.Buffer(make([]byte, 0, 64*1024), 1024*1024)
	for scanner.Scan() {
		line := strings.TrimSpace(scanner.Text())
		if generatedMarkerRe.MatchString(line) || swagGeneratedMarkerRe.MatchString(line) {
			generated = true
		}
		loc++
	}
	if scanErr := scanner.Err(); scanErr != nil {
		return false, 0, fmt.Errorf("scanning %s: %w", path, scanErr)
	}
	return generated, loc, nil
}