split packages as modules

.github/dependabot.yaml

@@ -1,7 +1,8 @@
 version: 2
 updates:
   - package-ecosystem: "github-actions"
-    directory: "/"
+    directories:
+      - "**/*"
     schedule:
       interval: "weekly"
       day: "friday"

.github/workflows/go-test.yml

@@ -44,14 +44,29 @@ jobs:
         cache: true
 
     - uses: actions/checkout@v4
-    - name: Run unit tests
+    - name: Run unit tests on all modules in this repo
       shell: bash
-      run: go test -v -race -coverprofile="coverage-${{ matrix.os }}.${{ matrix.go_version }}.out" -covermode=atomic -coverpkg=$(go list)/... ./...
+      run: |
+        # This script runs all tests on all modules and their subpackages.
+        #
+        # NOTES:
+        # * git bash on a windows runner should support GNU find. find flags should be supported by find on macos.
+        # * we don't attempt tricks using go work. Perhaps this will be the official way in future go releases.
+        set -euxo pipefail
+
+        find . -name \*.mod -execdir pwd \; | grep -v "\.git" | sort | uniq | \
+          while read module_dir ; do
+            pushd "${module_dir}"
+            # *.coverage.* pattern is automatically detected by codecov
+            coverprofile="${module_dir##*/}.coverage.${{ matrix.os }}.${{ matrix.go_version }}.out"
+            go test -v -race -coverprofile="${coverprofile}" -covermode=atomic -coverpkg=$(go list)/... ./...
+            popd
+          done
 
     - name: Upload coverage to codecov
       uses: codecov/codecov-action@v5
       with:
-        files: './coverage-${{ matrix.os }}.${{ matrix.go_version }}.out'
+        name: Multi modules aggregated coverage
         flags: '${{ matrix.go_version }}-${{ matrix.os }}'
         fail_ci_if_error: false
         verbose: true

.golangci.yml

@@ -14,6 +14,7 @@ linters:
     - gocognit
     - godot
     - godox
+    - gomoddirectives
     - gosmopolitan
     - inamedparam
     - ireturn

README.md

@@ -11,89 +11,154 @@ You may also use it standalone for your projects.
 
 > `swag` is one of the foundational building blocks of the go-openapi initiative.
 >
-> Most packages in `github.com/go-openapi/...` depend on it in some way.
+> Most repositories in `github.com/go-openapi/...` depend on it in some way.
 > So does the CLI tool `github.com/go-swagger/go-swagger`,
 > and the code generated by this tool.
 
 ## Contents
 
+`go-openapi/swag` now exposes a collection of relatively independent modules.
+
 Here is what is inside:
 
-*	Package `conv`
+*	Module `cmdutils`
+
+  * [x] utilities to work with CLIs
+
+*	Module `conv`
 
   * [x] convert between values and pointers for any types
   * [x] convert from string to builtin types (wraps `strconv`)
+  * [x] require `./typeutils` (test dependency)
 
-*	Package `fileutils`
+*	Module `fileutils`
 
   * [x] file upload type
   * [x] search in path (deprecated)
-* Package `jsonname`
+
+* Module `jsonname`
 
   * [x] infer JSON names from go properties
 
-* Package `jsonutils`
+* Module `jsonutils`
 
   * [x] fast json concatenation
   * [x] read and write JSON from and to dynamic go data structures
+  * [x] require `github.com/mailru/easyjson`
 
-* Package `loading`
+* Module `loading`
 
   * [x] load from file or http
+  * [x] require `./yamlutils`
 
-* Package `mangling`
+* Module `mangling`
 
   * [x] name mangling for go
 
-* Package `netutils`
+* Module `netutils`
 
   * [x] host, port from address
 
-*	Package `stringutils`
+*	Module `stringutils`
 
   * [x] search in slice (with case-insensitive)
-  * [x] slit/join query parameters as arrays
+  * [x] split/join query parameters as arrays
 
-*	Package `typeutils`
+*	Module `typeutils`
 
   * [x] check the zero value for any type
 
-* Package `yamlutils`
+* Module `yamlutils`
 
   * [x] converting YAML to JSON
   * [x] loading YAML into a dynamic YAML document
+  * [x] require `./jsonutils`
+  * [x] require `github.com/mailru/easyjson`
+  * [x] require `gopkg.in/yaml.v3`
 
 ---
 
-This repo has a few dependencies outside of the standard library:
+The root module `github.com/go-openapi/swag` at the repo level maintains a few 
+dependencies outside of the standard library:
 
 * YAML utilities depend on `gopkg.in/yaml.v3`
 * JSON utilities `github.com/mailru/easyjson`
 
+This is not necessarily the case for all sub-modules.
+
 ## Release notes
 
-### v0.24.0
+### v0.24.0 [Unreleased]
 
 With this release, we have largely modernized the API of `swag`:
-* The traditional `swag` API still works the same: code that imports `swag` will still
+
+* The traditional `swag` API is still supported: code that imports `swag` will still
   compile and work the same.
 * A deprecation notice is published to encourage consumers of this library to adopt
-  the newer API:
+  the newer API
+* **Deprecation notice** 
   * configuration through global variables is now deprecated, in favor of options passed as parameters
-  * helper functions are moved to more specialized packages, which are exposed as 
+  * all helper functions are moved to more specialized packages, which are exposed as 
     go modules. Importing such a module would reduce the footprint of dependencies.
-
-Moving forward, no additional feature will be added to the `swag` API directly.
-However, child modules will continue to evolve or some new ones may be added in the future.
+  * _all_ functions, variables, constants exposed by the deprecated API have now moved, so
+    that consumers of the new API no longer need to import github.com/go-openapi/swag, but
+    should import the desired sub-module(s).
 
 **New with this release**:
 
 * [x] type converters and pointer to value helpers now support generic types
 * [x] name mangling now support pluralized initialisms (issue #46)
-  Strings like "contact IDs" are now recognized as such a plural form and
+      Strings like "contact IDs" are now recognized as such a plural form and mangled as a linter would expect.
 * [x] performance: small improvements to reduce the overhead of convert/format wrappers (see issues #110, or PR #108)
 * [x] performance: name mangling utilities run ~ 10% faster (PR #115)
 
+---
+
+Moving forward, no additional feature will be added to the `swag` API directly.
+
+However, child modules will continue to evolve or some new ones may be added in the future.
+
+
+#### Note to contributors
+
+The mono-repo structure comes with some unavoidable extra pains...
+
+* Testing
+
+> The usual `go test ./...` command, run from the root of this repo won't work any longer to test all submodules.
+>
+> Each module constitutes an independant unit of test. So you have to run `go test` inside each module.
+> Or you may take a look at how this is achieved by CI
+> [here] https://github.com/go-openapi/swag/blob/master/.github/workflows/go-test.yml).
+>
+> There are also some alternative tricks using `go work`, for local development, if you feel comfortable with
+> go workspaces. Perhaps some day, we'll have a `go work test` to run all tests without any hack.
+
+* Releasing
+
+> Each module follows its own independant module versioning.
+>
+> So you have tags like `mangling/v0.24.0`, `fileutils/v0.24.0` etc that are used by `go mod` and `go get`
+> to refer to the tagged version of each module specifically.
+>
+> This means we may release patches etc to each module independently.
+>
+> We'd like to adopt the rule that modules in this repo would only differ by a patch version
+> (e.g. `v0.24.5` vs `v0.24.3`), and we'll level all modules whenever a minor version is introduced.
+>
+> A script in `./hack` is provided to tag all modules in one go at the same level in one go.
+
 ## Todos, suggestions and plans
 
 All kinds of contributions are welcome.
+
+A few ideas:
+
+* [ ] Complete the split of dependencies to isolate easyjson from the rest
+* [ ] Improve mangling utilities (improve readability, support for capitalized words,
+      better word substitution for non-letter symbols...)
+* [ ] Move back to this common shared pot a few of the technical features introduced by go-swagger independently
+      (e.g. mangle go package names, search package with go modules support, ...)
+* [ ] Apply a similar mono-repo approach to go-openapi/strfmt which suffer from similar woes: bloated API,
+      imposed dependency to some database driver.
+

cmdutils/go.mod

@@ -0,0 +1,3 @@
+module github.com/go-openapi/swag/cmdutils
+
+go 1.20.0

conv/go.mod

@@ -0,0 +1,17 @@
+module github.com/go-openapi/swag/conv
+
+require (
+	github.com/go-openapi/swag/typeutils v0.0.0-00010101000000-000000000000
+	github.com/stretchr/testify v1.10.0
+)
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/kr/pretty v0.2.1 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+go 1.20.0
+
+replace github.com/go-openapi/swag/typeutils => ../typeutils

conv/go.sum

@@ -0,0 +1,15 @@
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/kr/pretty v0.2.1 h1:Fmg33tUaq4/8ym9TJN1x7sLJnHVwhP33CNkpYV/7rwI=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

doc.go

@@ -22,47 +22,51 @@
 //
 // Here is what is inside:
 //
-// Package [conv]:
+// Module [cmdutils]:
+//
+//   - utilities to work with CLIs
+//
+// Module [conv]:
 //
 //   - convert between value and pointers for builtin types
 //   - convert from string to builtin types (wraps strconv)
 //
-// Package [fileutils]:
+// Module [fileutils]:
 //
 //   - file upload type
 //   - search in path
 //
-// Package [jsonname]:
+// Module [jsonname]:
 //
 //   - json names for go properties
 //
-// Package [jsonutils]:
+// Module [jsonutils]:
 //
 //   - fast json concatenation
 //   - read and write JSON from and to dynamic go data structures
 //
-// Package [loading]:
+// Module [loading]:
 //
 //   - load from file or http
 //
-// Package [mangling]:
+// Module [mangling]:
 //
 //   - name mangling to generate clean identifiers
 //
-// Package [netutils]:
+// Module [netutils]:
 //
 //   - host, port from address
 //
-// Package [stringutils]:
+// Module [stringutils]:
 //
 //   - find string in list
 //   - join/split arrays of query parameters
 //
-// Package [typeutils]:
+// Module [typeutils]:
 //
 //   - check the zero value of any type
 //
-// Package [yamlutils]:
+// Module [yamlutils]:
 //
 //   - converting YAML to JSON
 //   - loading YAML into a dynamic YAML document

fileutils/go.mod

@@ -0,0 +1,13 @@
+module github.com/go-openapi/swag/fileutils
+
+require github.com/stretchr/testify v1.10.0
+
+require (
+	github.com/davecgh/go-spew v1.1.1 // indirect
+	github.com/kr/text v0.2.0 // indirect
+	github.com/pmezard/go-difflib v1.0.0 // indirect
+	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
+	gopkg.in/yaml.v3 v3.0.1 // indirect
+)
+
+go 1.20.0

fileutils/go.sum

@@ -0,0 +1,18 @@
+github.com/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/kr/pretty v0.2.1 h1:Fmg33tUaq4/8ym9TJN1x7sLJnHVwhP33CNkpYV/7rwI=
+github.com/kr/pretty v0.2.1/go.mod h1:ipq/a2n7PKx3OHsz4KJII5eveXtPO4qwEXGdVfWzfnI=
+github.com/kr/pty v1.1.1/go.mod h1:pFQYn66WHrOpPYNljwOMqo10TkYh1fy3cYio2l3bCsQ=
+github.com/kr/text v0.1.0/go.mod h1:4Jbv+DJW3UT/LiOwJeYQe1efqtUx/iVham/4vfdArNI=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/stretchr/testify v1.10.0 h1:Xv5erBjTwe/5IxqUQTdXv5kgmIvbHo3QQyRwhJsOfJA=
+github.com/stretchr/testify v1.10.0/go.mod h1:r2ic/lqez/lEtzL7wO/rwa5dbSLXVDPFyf8C91i36aY=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=