modvalidate

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 27, 2026 License: Apache-2.0, Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

SPDX-License-Identifier: Apache-2.0

Package modvalidate implements the module-artifact validator required by the module contract. It loads a module directory's four artifacts (module.manifest.json, authz.fragment.json, openapi.yaml, migrations/, and the optional frontend/frontend.manifest.json), validates each individually, and cross-checks a batch of modules (plus an optional external catalog snapshot) against the contract's reject list.

Every contract rule that is automatable from the artifacts alone is implemented here (reused code, not reimplemented, where the platform already owns the logic — e.g. the authz subset wall is enforced via internal/authz/engine.LoadModel, never duplicated). Rules that need runtime/deployment state this package cannot see (deployment org-unit taxonomy, generated-output staleness) are out of scope here.

Index

Constants

View Source
const (
	RuleUnknownField                       = "unknown-field"
	RuleUnknownContractVersion             = "unknown-contract-version"
	RuleModuleKeyFormat                    = "module-key-format"
	RuleBasePathMismatch                   = "base-path-mismatch"
	RuleSchemaMismatch                     = "schema-mismatch"
	RuleFeaturePrefixMismatch              = "feature-prefix-mismatch"
	RuleRouteBaseMismatch                  = "route-base-mismatch"
	RuleFragmentModuleKeyMismatch          = "fragment-module-key-mismatch"
	RuleAuthzSubsetWall                    = "authz-subset-wall"
	RuleAuthzBaseTypeRedeclared            = "authz-base-type-redeclared"
	RuleAuthzRelationUnknown               = "authz-relation-unknown"
	RuleAuthzAnchorMissing                 = "authz-anchor-missing"
	RuleDependencyUnknown                  = "dependency-unknown"
	RuleDependencyCycle                    = "dependency-cycle"
	RuleDependencyRange                    = "dependency-range"
	RuleDependencyRangeSyntax              = "dependency-range-syntax"
	RuleMigrationFilename                  = "migration-filename"
	RuleMigrationOrder                     = "migration-order"
	RuleMigrationCrossSchema               = "migration-cross-schema"
	RuleMigrationUnsafeStatement           = "migration-unsafe-statement"
	RuleMigrationChecksum                  = "migration-checksum-mismatch"
	RuleScopeTypeInvalid                   = "scope-type-invalid"
	RuleServicePort                        = "service-port"
	RuleHealthPath                         = "health-path"
	RuleDependencyRequired                 = "dependency-required"
	RuleFragmentObjectInvalid              = "fragment-object-invalid"
	RuleFragmentFeatureInvalid             = "fragment-feature-invalid"
	RuleFragmentRoleInvalid                = "fragment-role-invalid"
	RuleFragmentRowScopeInvalid            = "fragment-row-scope-invalid"
	RuleFrontendSDKVersionRange            = "frontend-sdk-version-range"
	RuleOpenAPIUnknownRequiredModule       = "openapi-unknown-required-module"
	RuleDuplicatePort                      = "duplicate-port"
	RuleOpenAPIOperationID                 = "openapi-missing-operation-id"
	RuleOpenAPIPathOutsideBasePath         = "openapi-path-outside-basepath"
	RuleOpenAPIMissingCapabilityAnnotation = "openapi-missing-capability-annotation"
	RuleFrontendDuplicateRouteID           = "frontend-duplicate-route-id"
	RuleFrontendPathCollision              = "frontend-path-collision"
	RuleFrontendBadParamName               = "frontend-bad-param-name"
	RuleFrontendFeatureKeyMissing          = "frontend-feature-key-missing"
	RuleDuplicateModuleKey                 = "duplicate-module-key"
	RuleDuplicateBasePath                  = "duplicate-base-path"
	RuleDuplicateRouteID                   = "duplicate-route-id"
	RuleDuplicateFeatureKey                = "duplicate-feature-key"
	RuleDuplicateObjectType                = "duplicate-object-type"
	RuleVersionFormat                      = "version-format"
	RuleLicenseFileClassMismatch           = "license-file-class-mismatch"
	RuleLicenseSPDXInvalid                 = "license-spdx-invalid"
)

Rule names — one per module-contract reject rule this package automates. Tests assert on these names directly (the conformance suite).

View Source
const ChecksumLedgerFile = "checksums.json"

ChecksumLedgerFile is the committed lockfile every migrations directory carries (`<module>/migrations/checksums.json`, and `migrations/<tree>/checksums.json` for the four foundation trees): filename -> sha256 of shipped content. The ledger lists EVERY migration file: a changed hash, a ledger entry with no file (deleted or renamed), or a file with no ledger entry is a failure. The ledger is refreshed explicitly via WriteChecksumLedger (`modvalidate -write-checksums <dir>`) when a new migration is added — a shipped file is never rewritten, a new one is appended.

Variables

This section is empty.

Functions

func LoadMigrationsDir

func LoadMigrationsDir(key, migrationsDir string) ([]MigrationFile, []ValidationError)

LoadMigrationsDir reads every *.sql file of a migrations directory (sorted by name) with its sha256. key is the owner used in error attribution (module key or foundation tree name).

func LoadModule

func LoadModule(dir string) (*Module, []ValidationError)

LoadModule reads a module directory's artifacts from disk. It returns load errors (missing required artifact, malformed JSON/YAML, unknown fields) as ValidationErrors so callers can batch them alongside semantic validation errors; a nil *Module is returned only when the manifest itself could not be loaded at all (nothing else can be meaningfully checked).

func WriteChecksumLedger

func WriteChecksumLedger(dir string, mod *Module) error

WriteChecksumLedger (re)writes the checksum ledger for a module's current migration set.

func WriteChecksumLedgerDir

func WriteChecksumLedgerDir(migrationsDir string, files []MigrationFile) error

WriteChecksumLedgerDir (re)writes the checksum ledger of a bare migrations directory (a foundation tree such as migrations/registry).

Types

type AuthzFragment

type AuthzFragment struct {
	ModuleKey       string                  `json:"moduleKey"`
	Roles           []FragmentRole          `json:"roles"`
	Objects         []FragmentObject        `json:"objects"`
	Relations       json.RawMessage         `json:"relations"`
	Features        []FragmentFeature       `json:"features"`
	FieldCatalog    []map[string]any        `json:"fieldCatalog"`
	FieldSets       []map[string]any        `json:"fieldSets"`
	RowScopes       []FragmentRowScope      `json:"rowScopes"`
	BootstrapPolicy FragmentBootstrapPolicy `json:"bootstrapPolicy"`
}

AuthzFragment mirrors the contract's authz.fragment.json shape. Relations is kept as raw JSON and handed to internal/authz/engine.LoadModel verbatim — the subset wall is enforced there, never reimplemented here.

type CatalogEntry

type CatalogEntry struct {
	ModuleKey   string   `json:"moduleKey"`
	Version     string   `json:"version"`
	BasePath    string   `json:"basePath"`
	Port        int      `json:"port,omitempty"`
	RouteBase   string   `json:"routeBase,omitempty"`
	RouteIDs    []string `json:"routeIds,omitempty"`
	FeatureKeys []string `json:"featureKeys,omitempty"`
	ObjectTypes []string `json:"objectTypes,omitempty"`
}

CatalogEntry is the minimal external-catalog-snapshot shape used for cross-module duplicate and dependency-resolution checks against modules NOT in the current validate batch (duplicates are rejected across the whole catalog). No registry export mechanism exists yet, so this snapshot is supplied as a JSON file (-catalog flag) or built in-memory in tests.

type CatalogSnapshot

type CatalogSnapshot struct {
	Modules []CatalogEntry `json:"modules"`
}

CatalogSnapshot is a set of CatalogEntry rows representing modules already known to the platform, outside the batch being validated right now.

func LoadCatalogSnapshot

func LoadCatalogSnapshot(path string) (CatalogSnapshot, error)

LoadCatalogSnapshot reads an external catalog snapshot JSON file (duplicate checks are "across the catalog", not just the current validate batch). A missing path is not an error — it simply means no external catalog is being checked against (e.g. a single-module validate-modules run with no other modules to collide with yet).

type FragmentBootstrapPolicy

type FragmentBootstrapPolicy struct {
	SeedCompanyCreatorObjectRelations []any `json:"seedCompanyCreatorObjectRelations"`
}

type FragmentFeature

type FragmentFeature struct {
	FeatureKey        string         `json:"featureKey"`
	Label             string         `json:"label"`
	ScopeType         string         `json:"scopeType"`
	RequiresCompany   bool           `json:"requiresCompany"`
	AccessRuleKind    string         `json:"accessRuleKind"`
	AccessRulePayload map[string]any `json:"accessRulePayload"`
	SortOrder         int            `json:"sortOrder"`
	IsSidebarEntry    bool           `json:"isSidebarEntry"`
}

type FragmentObject

type FragmentObject struct {
	ObjectType         string   `json:"objectType"`
	Label              string   `json:"label"`
	ScopeKind          string   `json:"scopeKind"`
	ParentKind         string   `json:"parentKind"`
	ManagerRelation    string   `json:"managerRelation"`
	GrantableRelations []string `json:"grantableRelations"`
	ShowInPermissionUi bool     `json:"showInPermissionUi"`
	SortOrder          int      `json:"sortOrder"`
}

type FragmentRole

type FragmentRole struct {
	RoleKey                string `json:"roleKey"`
	Label                  string `json:"label"`
	ScopeType              string `json:"scopeType"`
	GrantsShellAccess      bool   `json:"grantsShellAccess"`
	SeedCompanyCreatorRole bool   `json:"seedCompanyCreatorRole"`
	SortOrder              int    `json:"sortOrder"`
}

type FragmentRowScope

type FragmentRowScope struct {
	EntityType string   `json:"entityType"`
	Rules      []string `json:"rules"`
}

type FrontendManifest

type FrontendManifest struct {
	ModuleKey       string          `json:"moduleKey"`
	RouteBase       string          `json:"routeBase"`
	Routes          []FrontendRoute `json:"routes"`
	NavFromFeatures bool            `json:"navFromFeatures"`
	SdkVersionRange string          `json:"sdkVersionRange"`
	RemoteEntryUrl  *string         `json:"remoteEntryUrl"`
}

FrontendManifest mirrors the contract's frontend.manifest.json shape.

type FrontendRoute

type FrontendRoute struct {
	ID         string `json:"id"`
	Path       string `json:"path"`
	FeatureKey string `json:"featureKey"`
}

type Manifest

type Manifest struct {
	ContractVersion string               `json:"contractVersion"`
	ModuleKey       string               `json:"moduleKey"`
	DisplayName     string               `json:"displayName"`
	Version         string               `json:"version"`
	ScopeType       string               `json:"scopeType"`
	Mandatory       bool                 `json:"mandatory"`
	Service         ManifestService      `json:"service"`
	Dependencies    []ManifestDependency `json:"dependencies"`
	Org             ManifestOrg          `json:"org"`
	Data            ManifestData         `json:"data"`
	License         ManifestLicense      `json:"license"`
	Events          json.RawMessage      `json:"events"`
}

Manifest mirrors the contract's module.manifest.json shape exactly. Unknown fields are rejected at decode time (decodeStrict), except keys prefixed with "_" (author comments/annotations — see notification's frontend.manifest.json).

type ManifestData

type ManifestData struct {
	PostgresSchema string `json:"postgresSchema"`
	MigrationsPath string `json:"migrationsPath"`
}

type ManifestDependency

type ManifestDependency struct {
	ModuleKey    string `json:"moduleKey"`
	VersionRange string `json:"versionRange"`
	Required     bool   `json:"required"`
}

type ManifestLicense

type ManifestLicense struct {
	Class               string `json:"class"`
	SPDX                string `json:"spdx"`
	EntitlementRequired bool   `json:"entitlementRequired"`
}

type ManifestOrg

type ManifestOrg struct {
	RequiredOrgUnitTypes []string `json:"requiredOrgUnitTypes"`
	UsesMembers          bool     `json:"usesMembers"`
	UsesPositions        bool     `json:"usesPositions"`
}

type ManifestService

type ManifestService struct {
	BasePath   string  `json:"basePath"`
	Port       int     `json:"port"`
	HealthPath string  `json:"healthPath"`
	Image      *string `json:"image"`
}

type MigrationFile

type MigrationFile struct {
	Name     string // basename, e.g. "0001_schema.sql"
	Contents []byte
	Checksum string // sha256 hex of Contents
}

MigrationFile is one loaded migrations/NNNN_description.sql file.

type Module

type Module struct {
	Dir        string
	ModuleKey  string // taken from the manifest once loaded; "" if the manifest itself failed
	Manifest   *Manifest
	Fragment   *AuthzFragment
	OpenAPI    map[string]any // parsed YAML document, generic (openapi.yaml is standard OpenAPI, not a custom contract shape)
	OpenAPIRaw []byte
	Migrations []MigrationFile
	Frontend   *FrontendManifest // nil when the module has no frontend/ dir (headless modules are first-class)
}

Module is a fully loaded module directory: the four required artifacts plus the optional frontend one.

type ValidationError

type ValidationError struct {
	ModuleKey string
	Rule      string
	Message   string
}

ValidationError is one named contract rejection. Never a warning.

func ValidateBatch

func ValidateBatch(modules []*Module, snapshot CatalogSnapshot) []ValidationError

ValidateBatch runs ValidateModule over every module plus every cross-module contract check (duplicates across the catalog, dependency graph). snapshot may be zero-valued (no external catalog to check against — e.g. a single-module validate-modules run).

func ValidateMigrationsDir

func ValidateMigrationsDir(key, migrationsDir string) []ValidationError

ValidateMigrationsDir runs the artifact-only migration rules (filename shape, strict order, ledger completeness and immutability) over a bare migrations directory — the foundation trees' gate (`make validate-migrations`). The cross-schema rule table does not apply: foundation trees own the shared schemas and roles by design.

func ValidateModule

func ValidateModule(mod *Module) []ValidationError

ValidateModule runs every module-contract rule that needs only a single module's own artifacts (no cross-module/catalog state). Load errors (LoadModule's own return) should be reported separately/first — ValidateModule assumes mod.Manifest is non-nil (LoadModule already guarantees this or returns a nil *Module).

func (ValidationError) Error

func (e ValidationError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL