feat: Add extension mechanism for third-party tools in .project format

Author: Aaravanand00

utilities/dot-project/README.md

@@ -7,6 +7,7 @@ A Go utility that validates CNCF project metadata and maintainer rosters. It che
 - Validates project YAML files against structured schema requirements
 - Detects content drift using SHA256 hashes and cached history
 - Validates maintainer definitions against canonical `.project` repository data
+- **Extension mechanism for third-party tools** (schema version 1.1.0+)
 - Stubbed third-party verification hook for maintainer identity checks
 - Multiple output formats: human-readable text, JSON, YAML
 - Includes GitHub Actions workflow and Makefile helpers
@@ -124,6 +125,42 @@ documentation:
   api: { path: "docs/API.md" }
 ```
 
+### Extensions (schema_version >= 1.1.0)
+
+Extensions allow third-party tools to store their configuration within the `.project` file without conflicting with core fields. Each extension is namespaced by tool name.
+
+```yaml
+schema_version: "1.1.0"  # Required for extensions
+# ... other fields ...
+
+extensions:
+  # Tool-specific configuration
+  scorecard:
+    metadata:
+      author: "OSSF"
+      homepage: "https://securityscorecards.dev"
+      repository: "https://github.com/ossf/scorecard"
+      license: "Apache-2.0"
+      version: "4.0.0"
+    config:
+      checks:
+        - Binary-Artifacts
+        - Branch-Protection
+      threshold: 7.0
+
+  clomonitor:
+    metadata:
+      author: "CNCF"
+      homepage: "https://clomonitor.io"
+    config:
+      category: "platform"
+```
+
+**Extension naming rules:**
+- Use alphanumeric characters, hyphens, underscores, and dots
+- Reserved names (core field names) cannot be used
+- Namespacing with organization prefix is recommended (e.g., `my-org.tool-name`)
+
 Each maintainer entry must contain a `project-maintainers` team which cannot be empty. Handles are normalized (trimmed and stripped of leading `@`) before verification.
 
 ## Maintainer Verification Stub

utilities/dot-project/extensions_test.go

@@ -0,0 +1,216 @@
+package projects
+
+import (
+	"testing"
+	"time"
+)
+
+func TestExtensionValidation(t *testing.T) {
+	baseProject := Project{
+		Name:          "Test Project",
+		Description:   "A test project",
+		SchemaVersion: "1.1.0",
+		MaturityLog: []MaturityEntry{
+			{
+				Phase: "incubating",
+				Date:  time.Date(2024, 1, 15, 0, 0, 0, 0, time.UTC),
+				Issue: "https://github.com/cncf/toc/issues/123",
+			},
+		},
+		Repositories: []string{"https://github.com/test/repo"},
+	}
+
+	t.Run("valid extension", func(t *testing.T) {
+		project := baseProject
+		project.Extensions = map[string]Extension{
+			"my-tool": {
+				Metadata: &ExtensionMetadata{
+					Author:     "Test Author",
+					Homepage:   "https://example.com",
+					Repository: "https://github.com/test/tool",
+					License:    "Apache-2.0",
+					Version:    "1.0.0",
+				},
+				Config: map[string]interface{}{
+					"enabled": true,
+					"setting": "value",
+				},
+			},
+		}
+
+		errors := validateProjectStruct(project)
+		if len(errors) != 0 {
+			t.Errorf("Expected no errors for valid extension, got: %v", errors)
+		}
+	})
+
+	t.Run("extension without schema version", func(t *testing.T) {
+		project := baseProject
+		project.SchemaVersion = ""
+		project.Extensions = map[string]Extension{
+			"my-tool": {Config: map[string]interface{}{"key": "value"}},
+		}
+
+		errors := validateProjectStruct(project)
+		found := false
+		for _, err := range errors {
+			if err == "extensions require schema_version >= 1.1.0" {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("Expected schema version error, got: %v", errors)
+		}
+	})
+
+	t.Run("extension with old schema version", func(t *testing.T) {
+		project := baseProject
+		project.SchemaVersion = "1.0.0"
+		project.Extensions = map[string]Extension{
+			"my-tool": {Config: map[string]interface{}{"key": "value"}},
+		}
+
+		errors := validateProjectStruct(project)
+		found := false
+		for _, err := range errors {
+			if err == "extensions require schema_version >= 1.1.0" {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("Expected schema version error, got: %v", errors)
+		}
+	})
+
+	t.Run("reserved extension name", func(t *testing.T) {
+		project := baseProject
+		project.Extensions = map[string]Extension{
+			"name": {Config: map[string]interface{}{"key": "value"}},
+		}
+
+		errors := validateProjectStruct(project)
+		found := false
+		for _, err := range errors {
+			if err == "extensions.name: 'name' is a reserved name" {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("Expected reserved name error, got: %v", errors)
+		}
+	})
+
+	t.Run("invalid extension name format", func(t *testing.T) {
+		project := baseProject
+		project.Extensions = map[string]Extension{
+			"my tool!": {Config: map[string]interface{}{"key": "value"}},
+		}
+
+		errors := validateProjectStruct(project)
+		found := false
+		for _, err := range errors {
+			if err == "extensions.my tool!: invalid name format (use alphanumeric, hyphens, underscores, dots)" {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("Expected invalid name format error, got: %v", errors)
+		}
+	})
+
+	t.Run("invalid metadata URL", func(t *testing.T) {
+		project := baseProject
+		project.Extensions = map[string]Extension{
+			"my-tool": {
+				Metadata: &ExtensionMetadata{
+					Homepage: "not-a-url",
+				},
+			},
+		}
+
+		errors := validateProjectStruct(project)
+		found := false
+		for _, err := range errors {
+			if err == "extensions.my-tool.metadata.homepage is not a valid URL" {
+				found = true
+				break
+			}
+		}
+		if !found {
+			t.Errorf("Expected invalid URL error, got: %v", errors)
+		}
+	})
+}
+
+func TestIsValidExtensionName(t *testing.T) {
+	testCases := []struct {
+		name  string
+		valid bool
+	}{
+		{"my-tool", true},
+		{"my_tool", true},
+		{"my.tool", true},
+		{"MyTool123", true},
+		{"tool", true},
+		{"my tool", false},
+		{"my-tool!", false},
+		{"", false},
+		{"tool@name", false},
+		{"tool#name", false},
+	}
+
+	for _, tc := range testCases {
+		result := isValidExtensionName(tc.name)
+		if result != tc.valid {
+			t.Errorf("isValidExtensionName(%q) = %v, expected %v", tc.name, result, tc.valid)
+		}
+	}
+}
+
+func TestIsVersionAtLeast(t *testing.T) {
+	testCases := []struct {
+		version    string
+		minVersion string
+		expected   bool
+	}{
+		{"1.1.0", "1.1.0", true},
+		{"1.2.0", "1.1.0", true},
+		{"2.0.0", "1.1.0", true},
+		{"1.0.0", "1.1.0", false},
+		{"0.9.0", "1.1.0", false},
+	}
+
+	for _, tc := range testCases {
+		result := isVersionAtLeast(tc.version, tc.minVersion)
+		if result != tc.expected {
+			t.Errorf("isVersionAtLeast(%q, %q) = %v, expected %v",
+				tc.version, tc.minVersion, result, tc.expected)
+		}
+	}
+}
+
+func TestBackwardCompatibility(t *testing.T) {
+	// Test that projects without extensions still validate correctly
+	project := Project{
+		Name:          "Legacy Project",
+		Description:   "A project without extensions",
+		SchemaVersion: "1.0.0",
+		MaturityLog: []MaturityEntry{
+			{
+				Phase: "incubating",
+				Date:  time.Date(2024, 1, 15, 0, 0, 0, 0, time.UTC),
+				Issue: "https://github.com/cncf/toc/issues/123",
+			},
+		},
+		Repositories: []string{"https://github.com/test/repo"},
+	}
+
+	errors := validateProjectStruct(project)
+	if len(errors) != 0 {
+		t.Errorf("Expected no errors for legacy project, got: %v", errors)
+	}
+}

utilities/dot-project/types.go

@@ -5,6 +5,9 @@ import (
 	"time"
 )
 
+// SchemaVersionWithExtensions is the minimum version that supports extensions
+const SchemaVersionWithExtensions = "1.1.0"
+
 type ProjectList []string
 
 type Project struct {
@@ -25,6 +28,26 @@ type Project struct {
 	Governance    *GovernanceConfig    `json:"governance,omitempty" yaml:"governance,omitempty"`
 	Legal         *LegalConfig         `json:"legal,omitempty" yaml:"legal,omitempty"`
 	Documentation *DocumentationConfig `json:"documentation,omitempty" yaml:"documentation,omitempty"`
+
+	// Extensions for third-party tools (requires schema_version >= 1.1.0)
+	Extensions map[string]Extension `json:"extensions,omitempty" yaml:"extensions,omitempty"`
+}
+
+// Extension represents a third-party tool extension configuration
+type Extension struct {
+	// Metadata about the extension
+	Metadata *ExtensionMetadata `json:"metadata,omitempty" yaml:"metadata,omitempty"`
+	// Tool-specific configuration (arbitrary key-value pairs)
+	Config map[string]interface{} `json:"config,omitempty" yaml:"config,omitempty"`
+}
+
+// ExtensionMetadata contains information about the extension provider
+type ExtensionMetadata struct {
+	Author     string `json:"author,omitempty" yaml:"author,omitempty"`
+	Homepage   string `json:"homepage,omitempty" yaml:"homepage,omitempty"`
+	Repository string `json:"repository,omitempty" yaml:"repository,omitempty"`
+	License    string `json:"license,omitempty" yaml:"license,omitempty"`
+	Version    string `json:"version,omitempty" yaml:"version,omitempty"`
 }
 
 type PathRef struct {

utilities/dot-project/validator.go

@@ -322,9 +322,81 @@ func validateProjectStruct(project Project) []string {
 		}
 	}
 
+	// Validate extensions
+	if len(project.Extensions) > 0 {
+		extensionErrors := validateExtensions(project)
+		errors = append(errors, extensionErrors...)
+	}
+
 	return errors
 }
 
+// reservedExtensionNames contains names that cannot be used as extension keys
+// to prevent conflicts with core project fields
+var reservedExtensionNames = map[string]bool{
+	"name": true, "description": true, "maturity_log": true,
+	"repositories": true, "social": true, "artwork": true,
+	"website": true, "mailing_lists": true, "audits": true,
+	"schema_version": true, "type": true, "security": true,
+	"governance": true, "legal": true, "documentation": true,
+	"extensions": true,
+}
+
+// validateExtensions validates the extensions section of a project
+func validateExtensions(project Project) []string {
+	var errors []string
+
+	// Check schema version requirement
+	if project.SchemaVersion == "" || !isVersionAtLeast(project.SchemaVersion, SchemaVersionWithExtensions) {
+		errors = append(errors, fmt.Sprintf("extensions require schema_version >= %s", SchemaVersionWithExtensions))
+		return errors
+	}
+
+	for name, ext := range project.Extensions {
+		// Validate extension name format (alphanumeric, hyphens, underscores, dots)
+		if !isValidExtensionName(name) {
+			errors = append(errors, fmt.Sprintf("extensions.%s: invalid name format (use alphanumeric, hyphens, underscores, dots)", name))
+		}
+
+		// Check for reserved names
+		if reservedExtensionNames[name] {
+			errors = append(errors, fmt.Sprintf("extensions.%s: '%s' is a reserved name", name, name))
+		}
+
+		// Validate metadata URLs if provided
+		if ext.Metadata != nil {
+			if ext.Metadata.Homepage != "" && !isValidURL(ext.Metadata.Homepage) {
+				errors = append(errors, fmt.Sprintf("extensions.%s.metadata.homepage is not a valid URL", name))
+			}
+			if ext.Metadata.Repository != "" && !isValidURL(ext.Metadata.Repository) {
+				errors = append(errors, fmt.Sprintf("extensions.%s.metadata.repository is not a valid URL", name))
+			}
+		}
+	}
+
+	return errors
+}
+
+// isValidExtensionName checks if an extension name follows naming conventions
+func isValidExtensionName(name string) bool {
+	if name == "" {
+		return false
+	}
+	for _, r := range name {
+		if !((r >= 'a' && r <= 'z') || (r >= 'A' && r <= 'Z') ||
+			(r >= '0' && r <= '9') || r == '-' || r == '_' || r == '.') {
+			return false
+		}
+	}
+	return true
+}
+
+// isVersionAtLeast compares semantic versions (simple comparison)
+func isVersionAtLeast(version, minVersion string) bool {
+	// Simple version comparison for x.y.z format
+	return version >= minVersion
+}
+
 // isValidURL checks if a string is a valid URL
 func isValidURL(str string) bool {
 	if !strings.HasPrefix(str, "http://") && !strings.HasPrefix(str, "https://") {