chore: refactor package layout (#15)

* chore: package disentanglement

This PR restructures the codescan package in order to:

* get a better control over exposed API vs internal (currently: Run(), Options)
* organize the functionality in smaller bits, more easily identifiable
  and testable
* establish a clear chain of responsibility between the various components

How this has been tested:

* all the original tests remain the same with the same assertions and have been
  reshuffled across packages
* all tests that produce a spec or partial spec output on master got
  their output captured as a "golden" JSON file: all reshuffled tests
  compare their output against this golden copy.
* added more tests to the baseline, producing golden with an extended coverage (~ 85%)
* added more tests to the baseline, exercising reachable error paths
* added regression test harness with full golden comparison

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

* chore: backport to refactored layout commit "swagger:type array by falling through to underlying type resolution"

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

---------

Signed-off-by: Frederic BIDON <fredbi@yahoo.com>

Author: fredbi

.gitignore

@@ -27,3 +27,4 @@ profile.cov
 # .idea/
 # .vscode/
 .mcp.json
+.worktrees

.mockery.yml

@@ -0,0 +1,21 @@
+all: false
+dir: '{{.InterfaceDir}}'
+filename: mocks_test.go
+force-file-write: true
+formatter: goimports
+include-auto-generated: false
+log-level: info
+structname: '{{.Mock}}{{.InterfaceName}}'
+pkgname: '{{.SrcPackageName}}'
+recursive: false
+require-template-schema-exists: true
+template: matryer
+template-schema: '{{.Template}}.schema.json'
+packages:
+  github.com/go-openapi/codescan/internal/ifaces:
+    config:
+      dir: internal/scantest/mocks
+      filename: mocks.go
+      pkgname: 'mocks'
+      force-file-write: true
+      all: true

api.go

@@ -0,0 +1,31 @@
+// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
+// SPDX-License-Identifier: Apache-2.0
+
+package codescan
+
+import (
+	"fmt"
+
+	"github.com/go-openapi/codescan/internal/builders/spec"
+	"github.com/go-openapi/codescan/internal/scanner"
+	oaispec "github.com/go-openapi/spec"
+)
+
+// Options for the scanner.
+type Options = scanner.Options
+
+// Run the scanner to produce a swagger spec with the options provided.
+func Run(opts *Options) (*oaispec.Swagger, error) { // TODO(fred/claude): use option functors pattern
+	ctx, err := scanner.NewScanCtx(opts)
+	if err != nil {
+		return nil, fmt.Errorf("could not scan source: %w: %w", err, ErrCodeScan)
+	}
+
+	builder := spec.NewBuilder(opts.InputSpec, ctx, opts.ScanModels) // TODO(fred/claude): use option functors pattern
+	sp, err := builder.Build()
+	if err != nil {
+		return nil, fmt.Errorf("could not build spec: %w: %w", err, ErrCodeScan)
+	}
+
+	return sp, nil
+}

api_test.go

@@ -0,0 +1,91 @@
+// SPDX-FileCopyrightText: Copyright 2015-2025 go-swagger maintainers
+// SPDX-License-Identifier: Apache-2.0
+
+package codescan
+
+import (
+	"flag"
+	"io"
+	"log"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/go-openapi/testify/v2/require"
+)
+
+// Public-API smoke suite. Fixture-heavy tests live in internal/integration.
+
+var enableDebug bool //nolint:gochecknoglobals // test flag registered in init
+
+func init() { //nolint:gochecknoinits // registers test flags before TestMain
+	flag.BoolVar(&enableDebug, "enable-debug", false, "enable debug output in tests")
+}
+
+func TestMain(m *testing.M) {
+	flag.Parse()
+
+	if !enableDebug {
+		log.SetOutput(io.Discard)
+	} else {
+		log.SetFlags(log.LstdFlags | log.Lshortfile)
+		log.SetOutput(os.Stderr)
+	}
+
+	os.Exit(m.Run())
+}
+
+func TestApplication_DebugLogging(t *testing.T) {
+	// Exercises the logger.DebugLogf code path with Debug: true.
+	_, err := Run(&Options{
+		Packages:   []string{"./goparsing/petstore/..."},
+		WorkDir:    "fixtures",
+		ScanModels: true,
+		Debug:      true,
+	})
+
+	require.NoError(t, err)
+}
+
+func TestRun_InvalidWorkDir(t *testing.T) {
+	// Exercises the Run() error path when package loading fails.
+	_, err := Run(&Options{
+		Packages: []string{"./..."},
+		WorkDir:  "/nonexistent/directory",
+	})
+
+	require.Error(t, err)
+}
+
+func TestSetEnumDoesNotPanic(t *testing.T) {
+	// Regression: ensure Run() does not panic on minimal source with an enum.
+	dir := t.TempDir()
+
+	src := `
+	package failure
+
+	// swagger:model Order
+	type Order struct {
+		State State ` + "`json:\"state\"`" + `
+	}
+
+	// State represents the state of an order.
+	// enum: ["created","processed"]
+	type State string
+	`
+	err := os.WriteFile(filepath.Join(dir, "model.go"), []byte(src), 0o600)
+	require.NoError(t, err)
+
+	goMod := `
+	module failure
+	go 1.23`
+	err = os.WriteFile(filepath.Join(dir, "go.mod"), []byte(goMod), 0o600)
+	require.NoError(t, err)
+
+	_, err = Run(&Options{
+		WorkDir:    dir,
+		ScanModels: true,
+	})
+
+	require.NoError(t, err)
+}