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
- func LoadMigrationsDir(key, migrationsDir string) ([]MigrationFile, []ValidationError)
- func LoadModule(dir string) (*Module, []ValidationError)
- func WriteChecksumLedger(dir string, mod *Module) error
- func WriteChecksumLedgerDir(migrationsDir string, files []MigrationFile) error
- type AuthzFragment
- type CatalogEntry
- type CatalogSnapshot
- type FragmentBootstrapPolicy
- type FragmentFeature
- type FragmentObject
- type FragmentRole
- type FragmentRowScope
- type FrontendManifest
- type FrontendRoute
- type Manifest
- type ManifestData
- type ManifestDependency
- type ManifestLicense
- type ManifestOrg
- type ManifestService
- type MigrationFile
- type Module
- type ValidationError
Constants ¶
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).
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 ¶
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 FragmentRowScope ¶
type FrontendManifest ¶
type FrontendManifest struct {
ModuleKey string `json:"moduleKey"`
RouteBase string `json:"routeBase"`
Routes []FrontendRoute `json:"routes"`
SdkVersionRange string `json:"sdkVersionRange"`
RemoteEntryUrl *string `json:"remoteEntryUrl"`
}
FrontendManifest mirrors the contract's frontend.manifest.json shape.
type FrontendRoute ¶
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 ManifestDependency ¶
type ManifestLicense ¶
type ManifestOrg ¶
type ManifestService ¶
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 ¶
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