chore: refactor package layout

[fredbi]

Change type

Please select: Refactoring

Short description

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

Fixes

Full description

Checklist

• I have signed all my commits with my name and email (see DCO. This does not require a PGP-signed commit
• I have rebased and squashed my work, so only one commit remains
• I have added tests to cover my changes.
• I have properly enriched go doc comments in code.
• I have properly documented any breaking change.

[codecov]

Codecov Report

❌ Patch coverage is 76.42374% with 592 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.79%. Comparing base (4be7125) to head (04a9b65).
⚠️ Report is 3 commits behind head on master.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
internal/builders/schema/schema.go	64.14%	234 Missing and 83 partials ⚠️
internal/builders/responses/responses.go	66.80%	46 Missing and 32 partials ⚠️
internal/builders/parameters/parameters.go	72.18%	43 Missing and 31 partials ⚠️
internal/builders/parameters/typable.go	70.00%	12 Missing and 3 partials ⚠️
internal/builders/resolvers/resolvers.go	86.36%	12 Missing and 3 partials ⚠️
internal/parsers/extensions.go	89.47%	7 Missing and 7 partials ⚠️
internal/builders/resolvers/assertions.go	72.09%	8 Missing and 4 partials ⚠️
internal/builders/responses/typable.go	81.48%	10 Missing ⚠️
internal/builders/schema/taggers.go	86.48%	6 Missing and 4 partials ⚠️
internal/builders/items/typable.go	60.86%	9 Missing ⚠️
... and 9 more

❌ Your patch status has failed because the patch coverage (76.42%) is below the target coverage (80.00%). You can increase the patch coverage or adjust the target coverage.

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #15      +/-   ##
==========================================
- Coverage   72.34%   71.79%   -0.56%     
==========================================
  Files          14       48      +34     
  Lines        3804     4878    +1074     
==========================================
+ Hits         2752     3502     +750     
- Misses        738     1148     +410     
+ Partials      314      228      -86     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

This PR refactors codescan into smaller internal packages (parsers/builders/resolvers/etc.) to better separate public API from implementation details, and reorganizes tests into unit + integration suites with golden outputs.

Changes:

• Moved parsing logic into internal/parsers and introduced internal builder packages (schema/routes/operations/parameters/responses/items).
• Added a new integration test suite (internal/integration) and many golden JSON fixtures to lock down generated specs.
• Introduced internal interfaces (internal/ifaces) to decouple parsers from concrete Swagger model writers.

Reviewed changes

Copilot reviewed 156 out of 200 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
internal/parsers/regexprs_test.go	Switches test package to parsers and adds coverage for route/operation regexes.
internal/parsers/regexprs.go	Moves regexes into parsers, adds Rxf() helper.
internal/parsers/parsers_test.go	Adds unit tests for new parser primitives (matchers/setters).
internal/parsers/parsers_helpers_test.go	Adds tests for title/description extraction helper behavior.
internal/parsers/parsers_helpers.go	Moves helpers into parsers package.
internal/parsers/parsers.go	Introduces reusable parser components (match-only, deprecated, consumes/produces).
internal/parsers/parsed_path_content_test.go	Adds tests for parsing swagger:route / swagger:operation path annotations.
internal/parsers/parsed_path_content.go	Implements route/operation annotation parsing into ParsedPathContent.
internal/parsers/meta.go	Refactors meta parsing into parsers with a public NewMetaParser.
internal/parsers/matchers.go	Adds shared comment-group matcher utilities for common annotations.
internal/parsers/lines_test.go	Adds tests for JoinDropLast, Setter, and empty-line removal.
internal/parsers/lines.go	Adds string helpers for comment-line processing.
internal/parsers/errors.go	Adds ErrParser sentinel error for parsers.
internal/parsers/enum.go	Moves enum parsing utilities into parsers.
internal/logger/debug.go	Adds DebugLogf helper for conditional debug logging.
internal/integration/helpers_test.go	Adds integration test helpers for YAML/JSON and spec assertions.
internal/integration/go_swagger_spec_test.go	Adds canary tests matching go-swagger spec generation goldens.
internal/integration/doc.go	Adds package doc for integration tests package.
internal/integration/coverage_malformed_test.go	Adds error-surface tests for malformed annotation fixtures.
internal/ifaces/ifaces.go	Introduces internal interfaces to decouple parsers from spec writers.
internal/builders/schema/typable.go	Adds schema typable + validations implementation.
internal/builders/schema/taggers.go	Adds schema tagger composition using parser taggers.
internal/builders/schema/schema_go118_test.go	Adds Go 1.18-focused schema builder tests with goldens.
internal/builders/schema/errors.go	Adds ErrSchema sentinel error.
internal/builders/routes/taggers.go	Adds operation taggers for routes builder.
internal/builders/routes/setters.go	Adds operation setters for consumes/produces/schemes/security/etc.
internal/builders/routes/routes_test.go	Ports routes tests to routes package and adds golden comparisons.
internal/builders/routes/routes.go	Implements routes builder using ParsedPathContent + sectioned parser.
internal/builders/routes/errors.go	Adds ErrRoutes sentinel error.
internal/builders/responses/typable.go	Adds response/header typable + validations.
internal/builders/responses/taggers.go	Adds response header taggers composition.
internal/builders/responses/errors.go	Adds ErrResponses sentinel error.
internal/builders/resolvers/resolvers_test.go	Adds tests for resolver extension behavior.
internal/builders/resolvers/resolvers.go	Adds resolver utilities (type mapping, JSON tags, unsupported types).
internal/builders/resolvers/errors.go	Adds ErrResolver sentinel error.
internal/builders/resolvers/assertions.go	Moves assertions + helpers (TextMarshaler/time/error/any checks, extensions).
internal/builders/parameters/typable.go	Adds parameter typable + validations.
internal/builders/parameters/taggers.go	Adds parameter tagger composition (ref vs inline).
internal/builders/parameters/errors.go	Adds ErrParameters sentinel error.
internal/builders/operations/operations_test.go	Ports operations tests to operations package and adds golden comparison.
internal/builders/operations/operations_go119_test.go	Ports Go 1.19 YAML block test and adds golden comparison.
internal/builders/operations/operations.go	Implements operations builder and path-method dispatch.
internal/builders/operations/errors.go	Adds ErrOperations sentinel error.
internal/builders/items/validations.go	Adds items validation writer.
internal/builders/items/typable.go	Adds items typable implementation.
internal/builders/items/taggers.go	Adds items tagger composition and array-type recursion.
internal/builders/items/errors.go	Adds ErrItems sentinel error for items builder.
fixtures/integration/golden/transparentalias_responses.json	Adds new golden fixture for transparent-alias responses.
fixtures/integration/golden/transparentalias_params.json	Adds new golden fixture for transparent-alias params.
fixtures/integration/golden/product_responses.json	Adds new golden fixture for product responses.
fixtures/integration/golden/petstore_schema_Tag.json	Adds new golden fixture for petstore Tag schema.
fixtures/integration/golden/petstore_schema_Pet.json	Adds new golden fixture for petstore Pet schema.
fixtures/integration/golden/petstore_schema_Order.json	Adds new golden fixture for petstore Order schema.
fixtures/integration/golden/go123_special_spec.json	Adds new golden fixture covering Go 1.23 special types.
fixtures/integration/golden/go119_operations.json	Adds new golden fixture for Go 1.19 operations output.
fixtures/integration/golden/go118_schema_transportErr.json	Adds new golden fixture for Go 1.18 transportErr schema.
fixtures/integration/golden/go118_schema_aliased.json	Adds new golden fixture for Go 1.18 aliased schema output.
fixtures/integration/golden/go118_schema_NamedWithType.json	Adds new golden fixture for Go 1.18 NamedWithType output.
fixtures/integration/golden/go118_schema_Interfaced.json	Adds new golden fixture for Go 1.18 interface-field output.
fixtures/integration/golden/go118_responses_issue2011.json	Adds new golden fixture for issue 2011 responses output.
fixtures/integration/golden/go118_params_issue2011.json	Adds new golden fixture for issue 2011 params output.
fixtures/integration/golden/enhancements_top_level_kinds.json	Adds new enhancement golden for top-level kind scanning.
fixtures/integration/golden/enhancements_text_marshal.json	Adds new enhancement golden for TextMarshaler scanning.
fixtures/integration/golden/enhancements_swagger_type_array.json	Adds new enhancement golden for swagger:type array handling.
fixtures/integration/golden/enhancements_strfmt_arrays.json	Adds new enhancement golden for strfmt arrays/slices.
fixtures/integration/golden/enhancements_response_edges.json	Adds new enhancement golden for response edge-cases.
fixtures/integration/golden/enhancements_ref_alias_chain.json	Adds new enhancement golden for alias-chain behavior.
fixtures/integration/golden/enhancements_pointers_xnullable.json	Adds new enhancement golden for pointer nullable behavior (x-nullable).
fixtures/integration/golden/enhancements_pointers_no_xnullable.json	Adds new enhancement golden for pointer nullable behavior (no x-nullable).
fixtures/integration/golden/enhancements_named_struct_tags.json	Adds new enhancement golden for named struct tag override behavior.
fixtures/integration/golden/enhancements_named_basic.json	Adds new enhancement golden for named basic types behavior.
fixtures/integration/golden/enhancements_interface_methods_xnullable.json	Adds new enhancement golden for interface methods (x-nullable).
fixtures/integration/golden/enhancements_interface_methods.json	Adds new enhancement golden for interface methods baseline.
fixtures/integration/golden/enhancements_input_overlay.json	Adds new enhancement golden for input overlay behavior.
fixtures/integration/golden/enhancements_enum_docs.json	Adds new enhancement golden for enum docs enrichment.
fixtures/integration/golden/enhancements_embedded_types.json	Adds new enhancement golden for embedded type handling.
fixtures/integration/golden/enhancements_defaults_examples.json	Adds new enhancement golden for defaults/examples parsing.
fixtures/integration/golden/enhancements_allof_edges.json	Adds new enhancement golden for allOf edge cases.
fixtures/integration/golden/enhancements_all_http_methods.json	Adds new enhancement golden for all HTTP method routes.
fixtures/integration/golden/enhancements_alias_response_ref.json	Adds new enhancement golden for response-level alias under RefAliases=true.
fixtures/integration/golden/enhancements_alias_ref.json	Adds new enhancement golden for alias behavior under RefAliases=true.
fixtures/integration/golden/enhancements_alias_expand.json	Adds new enhancement golden for non-transparent alias expand behavior.
fixtures/integration/golden/classification_schema_struct_discriminators.json	Adds classification golden for discriminator behavior.
fixtures/integration/golden/classification_schema_NullString.json	Adds classification golden for NullString schema.
fixtures/integration/golden/classification_schema_NamedWithType.json	Adds classification golden for NamedWithType schema.
fixtures/integration/golden/classification_schema_AllOfModel.json	Adds classification golden for allOf model schema.
fixtures/integration/golden/classification_responses_issue2011.json	Adds classification golden for issue 2011 responses.
fixtures/integration/golden/classification_responses_issue2007.json	Adds classification golden for issue 2007 responses.
fixtures/integration/golden/classification_params_issue2011.json	Adds classification golden for issue 2011 params.
fixtures/integration/golden/classification_params_issue2007.json	Adds classification golden for issue 2007 params.
fixtures/integration/golden/classification_operations.json	Adds classification golden for operations output.
fixtures/integration/golden/bugs_3125_schema.json	Adds bug regression golden for #3125 schema output.
fixtures/integration/golden/bookings_spec.json	Adds golden spec fixture for bookings.
fixtures/integration/golden/api_spec_go111_transparent.json	Adds go111 transparent-alias spec golden.
fixtures/integration/golden/api_spec_go111_ref.json	Adds go111 ref-alias spec golden.
fixtures/integration/golden/api_spec_go111.json	Adds go111 baseline spec golden.
fixtures/goparsing/spec/api.go	Small fixture formatting change (extra blank line).
fixtures/goparsing/petstore/enums/priority.go	Adds a new petstore enum fixture.
fixtures/enhancements/unknown-annotation/types.go	Adds fixture for unknown annotation error path.
fixtures/enhancements/top-level-kinds/types.go	Adds fixture for top-level kind model scanning.
fixtures/enhancements/text-marshal/types.go	Adds fixture for TextMarshaler-related schema behavior.
fixtures/enhancements/swagger-type-array/types.go	Adds fixture for swagger:type array fallthrough behavior.
fixtures/enhancements/strfmt-arrays/types.go	Adds fixture for strfmt array/slice handling.
fixtures/enhancements/response-edges/api.go	Adds fixture for response builder edge cases.
fixtures/enhancements/ref-alias-chain/types.go	Adds fixture for alias-of-alias chains and stdlib alias handling.
fixtures/enhancements/named-struct-tags/types.go	Adds fixture for named struct type overrides (strfmt/type).
fixtures/enhancements/named-basic/types.go	Adds fixture for named basic types (strfmt/type/default).
fixtures/enhancements/malformed/meta-bad-ext-key/doc.go	Adds malformed fixture to exercise meta extension key validation.
fixtures/enhancements/malformed/info-bad-ext-key/doc.go	Adds malformed fixture to exercise info extension key validation.
fixtures/enhancements/malformed/example-int/api.go	Adds malformed fixture for invalid integer example parsing.
fixtures/enhancements/malformed/duplicate-body-tag/handlers.go	Adds malformed fixture for duplicate response body tag.
fixtures/enhancements/malformed/default-int/api.go	Adds malformed fixture for invalid integer default parsing.
fixtures/enhancements/malformed/bad-sec-defs/doc.go	Adds malformed fixture for invalid YAML security definitions.
fixtures/enhancements/malformed/bad-response-tag/handlers.go	Adds malformed fixture for invalid response tag prefix.
fixtures/enhancements/malformed/bad-contact/doc.go	Adds malformed fixture for invalid contact parsing.
fixtures/enhancements/interface-methods/types.go	Adds fixture for interface-method schema extraction behavior.
fixtures/enhancements/enum-docs/types.go	Adds fixture for enum value doc enrichment.
fixtures/enhancements/embedded-types/types.go	Adds fixture for embedded types and alias embedding behavior.
fixtures/enhancements/defaults-examples/types.go	Adds fixture for defaults/examples across schema types.
fixtures/enhancements/allof-edges/types.go	Adds fixture for allOf edge cases.
fixtures/enhancements/all-http-methods/handlers.go	Adds fixture to exercise all HTTP method branches.
fixtures/enhancements/alias-response/api.go	Adds fixture for response-level alias behavior.
fixtures/enhancements/alias-expand/api.go	Adds fixture for parameter/response alias expansion behavior.
errors.go	Changes ErrCodeScan sentinel to a custom error type/constant.
api_test.go	Adds public API smoke tests and debug logging gate via flags.
api.go	Adds thin public API wrapper around internal scanner + spec builder.
.mockery.yml	Adds mockery config for generating mocks in internal/scantest/mocks.
enum_test.go	Removes enum tests from root package (moved into internal).
enum.go	Removes enum helpers from root package (moved into internal/parsers).
assertions.go	Removes assertions from root package (moved into internal/builders/resolvers).