Merge pull request #114 from JoelSpeed/registry-refactor

Refactor to make analyzers independent

Author: k8s-ci-robot

docs/linters.md

@@ -113,7 +113,7 @@ The `jsontags` linter checks the tag name against the regex `"^[a-z][a-z0-9]*(?:
 
 ```yaml
 lintersConfig:
-  jsonTags:
+  jsontags:
     jsonTagRegex: "^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$" # Provide a custom regex, which the json tag must match.
 ```
 
@@ -178,7 +178,7 @@ In this case, the `omitempty` policy can be set to `Ignore`, and the linter will
 
 ```yaml
 lintersConfig:
-  optionalFields:
+  optionalfields:
     pointers:
       preference: Always | WhenRequired # Whether to always require pointers, or only when required. Defaults to `Always`.
       policy: SuggestFix | Warn # The policy for pointers in optional fields. Defaults to `SuggestFix`.
@@ -216,7 +216,7 @@ The `optionalorrequired` linter also checks for the presence of optional or requ
 
 ```yaml
 lintersConfig:
-  optionalOrRequired:
+  optionalorrequired:
     preferredOptionalMarker: optional | kubebuilder:validation:Optional # The preferred optional marker to use, fixes will suggest to use this marker. Defaults to `optional`.
     preferredRequiredMarker: required | kubebuilder:validation:Required # The preferred required marker to use, fixes will suggest to use this marker. Defaults to `required`.
 ```
@@ -236,7 +236,7 @@ and not having an `omitempty` value in their `json` tag.
 
 ```yaml
 lintersConfig:
-  requiredFields:
+  requiredfields:
     pointerPolicy: Warn | SuggestFix # The policy for pointers in required fields. Defaults to `SuggestFix`.
 ```
 
@@ -326,7 +326,7 @@ Because this linter has no way of determining which marker definition was intend
 It can configured to include a set of custom markers in the analysis by setting:
 ```yaml
 lintersConfig:
-  uniqueMarkers:
+  uniquemarkers:
     customMarkers:
       - identifier: custom:SomeCustomMarker
         attributes:

docs/new-linter.md

@@ -24,70 +24,70 @@ Once you are within the `inspect.Preorder`, you can then implement the business
 The registry in the analysis package co-ordinates the initialization of all linters.
 Where linters have configuration, or are enabled/disabled by higher level configuration, the registry takes on making sure the linters are initialized correctly.
 
-To enable the registry, each linter package must create an `Initializer` function that returns an `analysis.AnalyzerInitializer` interface (from `pkg/analysis`).
+To enable the registry, each linter package must create an `Initializer` function that returns an `initializer.AnalyzerInitializer` interface (from `pkg/analysis/initializer`).
 
 It is expected that each linter package contain a file `initializer.go`, the content of this file should be as follows:
 
 ```go
-// Initializer returns the AnalyzerInitializer for this
-// Analyzer so that it can be added to the registry.
-func Initializer() initializer {
-	return initializer{}
-}
-
-// intializer implements the AnalyzerInitializer interface.
-type initializer struct{}
-
-// Name returns the name of the Analyzer.
-func (initializer) Name() string {
-	return name
-}
-
-// Init returns the intialized Analyzer.
-func (initializer) Init(cfg config.LintersConfig) (*analysis.Analyzer, error) {
-	return newAnalyzer(cfg.MyLinterConfig)
+func init() {
+    // Register the linter with the registry when the package is imported.
+    registry.DefaultRegistry().RegisterLinter(Initializer())
 }
 
-// Default determines whether this Analyzer is on by default, or not.
-func (initializer) Default() bool {
-	return true // or false
+// Initializer returns the AnalyzerInitializer for this
+// Analyzer so that it can be added to the registry.
+func Initializer() initializer.AnalyzerInitializer {
+	return initializer.NewInitializer(
+		name, // A constant containing the name of the linter. This should be lowercase.
+		Analyzer, // An *analysis.Analyzer variable that is the linter.
+		true, // Whether the linter is enabled by default.
+	)
 }
 ```
 
-This pattern allows the linter to be registered with the KAL registry, and allows the linter to be initialized with configuration.
+This pattern allows the linter to be registered with the KAL registry, and allows the linter to be initialized.
 
-Once you have created the `initializer.go` file, you will need to add the linter to the `pkg/analysis/registry.go` file.
+Once you have created the `initializer.go` file, you will need to import the linter package in the `pkg/analysis/registration/registration.go` file.
 
-Add the initializer to the `NewRegistry` function, and it will then be included in the linter builds.
-
-```go
-func NewRegistry() []*analysis.Analyzer {
-    return []*analysis.Analyzer{
-        // Add the new linter here
-        mynewlinter.Initializer(),
-    }
-}
-```
+Once imported, the analyzer will be included in the linter builds.
 
 ## Configuration
 
-If the linter requires configuration, the configuration should be added to the `config` package.
+Where the linter requires configuration, a slightly different pattern is used in `initializer.go`.
+This time, use `NewConfigurableInitializer` instead of `NewInitializer` and pass in a function to validate the linter configuration.
+
+```go
 
-Add a new structure (or structures) to the `linters_config.go` file.
-Include a new field for the top level configuration to the `LintersConfig` struct, using the name of the linter, in camel case for the `json` tag.
+func init() {
+	kalanalysis.DefaultRegistry().RegisterLinter(Initializer())
+}
 
-Any options for the linter, should also be validated.
-Validation lives in the `validation` package.
+// Initializer returns the AnalyzerInitializer for this
+// Analyzer so that it can be added to the registry.
+func Initializer() initializer.AnalyzerInitializer {
+	return initializer.NewConfigurableInitializer(
+		name, // A constant containing the name of the linter. This should be lowercase.
+		initAnalyzer, // A function that returns the initialized Analyzer.
+		true, // Whether the linter is enabled by default.
+		validateLintersConfig, // A function that validates the linter configuration.
+	)
+}
 
-Within the `ValidateLintersConfig` function, in the `linters_config.go` file, you will need to add
-a line as below, to include any configuration validation for the new linter.
-There are already examples of this in the file.
+// initAnalyzer returns the intialized Analyzer.
+func initAnalyzer(cfg *Config) (*analysis.Analyzer, error) {
+	return newAnalyzer(cfg), nil
+}
 
-```go
-fieldErrors = append(fieldErrors, validateMyNewLint(lc.MyNewLinter, fldPath.Child("myNewLinter"))...)
+// validateLintersConfig validates the linter configuration.
+func validateLintersConfig(cfg *Config, fldPath *field.Path) field.ErrorList {
+	... // Validate the linter configuration.
+}
 ```
 
-The validations should use the `field.Error` pattern to provide consistent error messages.
+The configuration struct should be defined within the analyzer package alongside the code.
+
+Validation should be implemented in the `validateLintersConfig` function to ensure that the configuration is valid.
+This validation function will be called before the `initAnalyzer` function is called.
 
 ## Helpers
 

go.mod

@@ -7,6 +7,7 @@ require (
 	github.com/onsi/ginkgo/v2 v2.23.3
 	github.com/onsi/gomega v1.36.3
 	golang.org/x/tools v0.32.0
+	gopkg.in/yaml.v3 v3.0.1
 	k8s.io/apimachinery v0.32.3
 	k8s.io/utils v0.0.0-20241104100929-3ea5e8cea738
 )
@@ -26,5 +27,4 @@ require (
 	golang.org/x/text v0.24.0 // indirect
 	google.golang.org/protobuf v1.36.6 // indirect
 	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
-	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

pkg/analysis/commentstart/initializer.go

@@ -16,30 +16,20 @@ limitations under the License.
 package commentstart
 
 import (
-	"golang.org/x/tools/go/analysis"
-	"sigs.k8s.io/kube-api-linter/pkg/config"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/initializer"
+	"sigs.k8s.io/kube-api-linter/pkg/analysis/registry"
 )
 
-// Initializer returns the AnalyzerInitializer for this
-// Analyzer so that it can be added to the registry.
-func Initializer() initializer {
-	return initializer{}
-}
-
-// intializer implements the AnalyzerInitializer interface.
-type initializer struct{}
-
-// Name returns the name of the Analyzer.
-func (initializer) Name() string {
-	return name
+func init() {
+	registry.DefaultRegistry().RegisterLinter(Initializer())
 }
 
-// Init returns the intialized Analyzer.
-func (initializer) Init(cfg config.LintersConfig) (*analysis.Analyzer, error) {
-	return Analyzer, nil
-}
-
-// Default determines whether this Analyzer is on by default, or not.
-func (initializer) Default() bool {
-	return true
+// Initializer returns the AnalyzerInitializer for this
+// Analyzer so that it can be added to the registry.
+func Initializer() initializer.AnalyzerInitializer {
+	return initializer.NewInitializer(
+		name,
+		Analyzer,
+		true,
+	)
 }