Documentation
¶
Overview ¶
Package runtimeannotate owns Cobra dws.schema.* annotation writers and the RuntimeSchemaConstraints helpers used by the command framework.
Package boundary:
- Types / DTO / ProductDecl → internal/corecmd/contract
- AnnotateRuntime* writers (this package) — no Catalog delivery
- ContractFinal cobra store + Register seam → internal/corecmd/contractfinal
- Catalog assembly / ResolveMeta (`RegisterSchemaSourceRoot` → `ResolveSchemaBuild`); go:embed only for reviewed inputs → internal/cli (root)
Dependency direction: corecmd and corecmd/contractfinal import this package. This package must never import internal/cli (root or subpackages). Product / delivery code consumes this package directly, or via the cli root's package-local aliases (internal/cli/runtime_schema_seam.go).
Index ¶
- Constants
- func AnnotateRuntimeConstraints(cmd *cobra.Command, constraints RuntimeSchemaConstraints)
- func AnnotateRuntimeContract(cmd *cobra.Command)
- func AnnotateRuntimeFlag(cmd *cobra.Command, flagName, propertyName, paramType string, required bool)
- func AnnotateRuntimeFlagDescription(cmd *cobra.Command, flagName, description string)
- func AnnotateRuntimeFlagEnum(cmd *cobra.Command, flagName string, values ...string)
- func AnnotateRuntimeFlagExample(cmd *cobra.Command, flagName, example string)
- func AnnotateRuntimeFlagFormat(cmd *cobra.Command, flagName, format string)
- func AnnotateRuntimeFlagInterfaceType(cmd *cobra.Command, flagName, interfaceType string)
- func AnnotateRuntimeFlagProperty(cmd *cobra.Command, flagName, propertyName string)
- func AnnotateRuntimeFlagRequiredValue(cmd *cobra.Command, flagName string, required bool)
- func AnnotateRuntimeFlagRequiredWhen(cmd *cobra.Command, flagName, expression string)
- func AnnotateRuntimePositionals(cmd *cobra.Command, positionals ...contract.RuntimeSchemaPositional)
- func AnnotateRuntimeRequiredFlags(cmd *cobra.Command, flagNames ...string)
- func AttachRuntimeSchema(cmd *cobra.Command, productID, toolName, source string)
- func CommandFlag(cmd *cobra.Command, name string) *pflag.Flag
- func CommandPositionals(cmd *cobra.Command) []contract.RuntimeSchemaPositional
- func ConstraintsEmpty(constraints RuntimeSchemaConstraints) bool
- func RuntimeContractGate(cmd *cobra.Command) (string, bool)
- func RuntimeContractRisk(cmd *cobra.Command) (string, bool)
- func SetCommandAnnotation(cmd *cobra.Command, key, value string)
- func SetFlagAnnotation(flag *pflag.Flag, key, value string)
- func SetFlagAnnotationValues(flag *pflag.Flag, key string, values ...string)
- type RuntimeSchemaConstraints
Constants ¶
const ( AnnotationProduct = "dws.schema.product" AnnotationTool = "dws.schema.tool" AnnotationSource = "dws.schema.source" AnnotationDescription = "dws.schema.description" AnnotationExclude = "dws.schema.exclude" AnnotationConstraints = "dws.schema.constraints" AnnotationPositionals = "dws.schema.positionals" AnnotationContract = "dws.schema.contract" AnnotationRisk = "dws.schema.risk" AnnotationRuntimeGate = "dws.schema.runtime_gate" AnnotationFlagProperty = "dws.schema.property" AnnotationFlagType = "dws.schema.type" AnnotationFlagRequired = "dws.schema.required" AnnotationFlagReqWhen = "dws.schema.required_when" AnnotationFlagExample = "dws.schema.example" AnnotationFlagFormat = "x-cli-format" AnnotationFlagAnyOf = "dws.schema.anyOf" AnnotationFlagEnum = "x-cli-enum" )
Cobra annotation keys for Schema homology (path A). Writers and readers must share these exact strings; do not re-declare literals in callers.
const ( AnnotationFlagAliasOf = "dws.compat.alias_of" AnnotationFlagAliasOrigin = "dws.compat.alias_origin" FlagAliasOriginCorecmdV1 = "corecmd.flag_spec_aliases.v1" )
CLI flag alias evidence is kept in this narrow file so the base-owned Interface Snapshot helper can add the protocol constants to an older stable worktree without replacing that revision's complete runtimeannotate package. Only corecmd.FlagSpec.Aliases writes the exact origin; neither field is a Schema synonym or final payload-equivalence proof.
Variables ¶
This section is empty.
Functions ¶
func AnnotateRuntimeConstraints ¶
func AnnotateRuntimeConstraints(cmd *cobra.Command, constraints RuntimeSchemaConstraints)
AnnotateRuntimeConstraints records command-level parameter relationships.
func AnnotateRuntimeContract ¶
AnnotateRuntimeContract marks a command as carrying a command/LeafSpec Contract surface.
func AnnotateRuntimeFlag ¶
func AnnotateRuntimeFlag(cmd *cobra.Command, flagName, propertyName, paramType string, required bool)
AnnotateRuntimeFlag adds parameter metadata to an already-registered flag.
func AnnotateRuntimeFlagDescription ¶
AnnotateRuntimeFlagDescription records the Schema parameter description.
func AnnotateRuntimeFlagEnum ¶
AnnotateRuntimeFlagEnum records the accepted values for a flag.
func AnnotateRuntimeFlagExample ¶
AnnotateRuntimeFlagExample records a valid representative CLI value.
func AnnotateRuntimeFlagFormat ¶
AnnotateRuntimeFlagFormat records a machine-readable value format.
func AnnotateRuntimeFlagInterfaceType ¶
AnnotateRuntimeFlagInterfaceType records the wire type for a flag's interface property.
func AnnotateRuntimeFlagProperty ¶
AnnotateRuntimeFlagProperty records only the stable CLI flag to interface property binding.
func AnnotateRuntimeFlagRequiredValue ¶
AnnotateRuntimeFlagRequiredValue sets an explicit required value on a flag.
func AnnotateRuntimeFlagRequiredWhen ¶
AnnotateRuntimeFlagRequiredWhen records a conditional CLI requirement.
func AnnotateRuntimePositionals ¶
func AnnotateRuntimePositionals(cmd *cobra.Command, positionals ...contract.RuntimeSchemaPositional)
AnnotateRuntimePositionals records ordered positional arguments for agents.
func AnnotateRuntimeRequiredFlags ¶
AnnotateRuntimeRequiredFlags records schema-only required semantics.
func AttachRuntimeSchema ¶
AttachRuntimeSchema records optional implementation-side identity evidence on a runnable command. Stable command identity is collected from ContractFinal.Identity on the live Cobra leaves (EffectiveCommandRegistry); the binder accepts an absent annotation and rejects an annotation that disagrees with the collected identity.
func CommandFlag ¶
CommandFlag resolves local flags plus product/group persistent flags. Root persistent flags are intentionally available only when explicitly requested; they are global execution controls, not tool parameters.
func CommandPositionals ¶
func CommandPositionals(cmd *cobra.Command) []contract.RuntimeSchemaPositional
CommandPositionals reads annotated positionals (nil on miss/error).
func ConstraintsEmpty ¶
func ConstraintsEmpty(constraints RuntimeSchemaConstraints) bool
ConstraintsEmpty reports whether no constraint groups remain.
func RuntimeContractGate ¶
RuntimeContractGate returns the annotated runtime confirmation gate when present. Like RuntimeContractRisk it is read-only residual plumbing: the writer is retired and declared Contract SafetySpec is the production path.
func RuntimeContractRisk ¶
RuntimeContractRisk returns the Contract Risk annotation when present. Writers are retired: production leaves declare contract.SafetySpec through ContractFinal, and assembly consults this residual annotation only as the fallback when a leaf carries no ContractFinal Safety.
func SetCommandAnnotation ¶
SetCommandAnnotation writes a non-blank command annotation.
func SetFlagAnnotation ¶
SetFlagAnnotation writes a single non-blank flag annotation value.
Types ¶
type RuntimeSchemaConstraints ¶
type RuntimeSchemaConstraints = contract.RuntimeSchemaConstraints
RuntimeSchemaConstraints is retained here for framework compatibility.
func CommandConstraints ¶
func CommandConstraints(cmd *cobra.Command) RuntimeSchemaConstraints
CommandConstraints reads the annotated constraint payload (empty on miss/error).
func NormalizeConstraints ¶
func NormalizeConstraints(constraints RuntimeSchemaConstraints) RuntimeSchemaConstraints
NormalizeConstraints trims, deduplicates, and drops undersized groups.
Source Files