Add .describe() annotations to under-documented Zod schema files

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/spec/src/kernel/plugin-structure.zod.ts

@@ -27,7 +27,7 @@ const OPS_FILE_SUFFIX_REGEX = /\.(object|field|trigger|function|view|page|dashbo
  * - "src/CRM/LeadObject.ts" (PascalCase)
  * - "src/utils/helper.js" (Wrong extension)
  */
-export const OpsFilePathSchema = z.string().superRefine((path, ctx) => {
+export const OpsFilePathSchema = z.string().describe('Validates a file path against OPS naming conventions').superRefine((path, ctx) => {
   // 1. Must be in src/
   if (!path.startsWith('src/')) {
     // Non-source files (package.json, config) are ignored by this specific validator
@@ -79,7 +79,7 @@ export const OpsFilePathSchema = z.string().superRefine((path, ctx) => {
 export const OpsDomainModuleSchema = z.object({
   name: z.string().regex(SNAKE_CASE_REGEX).describe('Module name (snake_case)'),
   files: z.array(z.string()).describe('List of files in this module'),
-}).superRefine((module, ctx) => {
+}).describe('Scanned domain module representing a plugin folder').superRefine((module, ctx) => {
   // Rule: Must have an index.ts
   if (!module.files.includes('index.ts')) {
     ctx.addIssue({
@@ -95,7 +95,7 @@ export const OpsDomainModuleSchema = z.object({
 export const OpsPluginStructureSchema = z.object({
   root: z.string().describe('Root directory path of the plugin project'),
   files: z.array(z.string()).describe('List of all file paths relative to root'),
-}).superRefine((project, ctx) => {
+}).describe('Full plugin project layout validated against OPS conventions').superRefine((project, ctx) => {
   // Check for configuration file
   if (!project.files.includes('objectstack.config.ts')) {
     ctx.addIssue({

packages/spec/src/system/cache.zod.ts

@@ -30,7 +30,7 @@ export const CacheStrategySchema = z.enum([
   'fifo',         // First In First Out
   'ttl',          // Time To Live only
   'adaptive',     // Dynamic strategy selection
-]);
+]).describe('Cache eviction strategy');
 
 export type CacheStrategy = z.infer<typeof CacheStrategySchema>;
 
@@ -41,7 +41,7 @@ export const CacheTierSchema = z.object({
   ttl: z.number().default(300).describe('Default TTL in seconds'),
   strategy: CacheStrategySchema.default('lru').describe('Eviction strategy'),
   warmup: z.boolean().default(false).describe('Pre-populate cache on startup'),
-});
+}).describe('Configuration for a single cache tier in the hierarchy');
 
 export type CacheTier = z.infer<typeof CacheTierSchema>;
 export type CacheTierInput = z.input<typeof CacheTierSchema>;
@@ -51,7 +51,7 @@ export const CacheInvalidationSchema = z.object({
   scope: z.enum(['key', 'pattern', 'tag', 'all']).describe('Invalidation scope'),
   pattern: z.string().optional().describe('Key pattern for pattern-based invalidation'),
   tags: z.array(z.string()).optional().describe('Cache tags to invalidate'),
-});
+}).describe('Rule defining when and how cached entries are invalidated');
 
 export type CacheInvalidation = z.infer<typeof CacheInvalidationSchema>;
 
@@ -62,7 +62,7 @@ export const CacheConfigSchema = z.object({
   prefetch: z.boolean().default(false).describe('Enable cache prefetching'),
   compression: z.boolean().default(false).describe('Enable data compression in cache'),
   encryption: z.boolean().default(false).describe('Enable encryption for cached data'),
-});
+}).describe('Top-level application cache configuration');
 
 export type CacheConfig = z.infer<typeof CacheConfigSchema>;
 export type CacheConfigInput = z.input<typeof CacheConfigSchema>;

packages/spec/src/system/compliance.zod.ts

@@ -4,62 +4,62 @@ import { z } from 'zod';
  * Compliance protocol for GDPR, CCPA, HIPAA, SOX, PCI-DSS
  */
 export const GDPRConfigSchema = z.object({
-  enabled: z.boolean(),
+  enabled: z.boolean().describe('Enable GDPR compliance controls'),
   dataSubjectRights: z.object({
-    rightToAccess: z.boolean().default(true),
-    rightToRectification: z.boolean().default(true),
-    rightToErasure: z.boolean().default(true),
-    rightToRestriction: z.boolean().default(true),
-    rightToPortability: z.boolean().default(true),
-    rightToObjection: z.boolean().default(true),
-  }),
+    rightToAccess: z.boolean().default(true).describe('Allow data subjects to access their data'),
+    rightToRectification: z.boolean().default(true).describe('Allow data subjects to correct their data'),
+    rightToErasure: z.boolean().default(true).describe('Allow data subjects to request deletion'),
+    rightToRestriction: z.boolean().default(true).describe('Allow data subjects to restrict processing'),
+    rightToPortability: z.boolean().default(true).describe('Allow data subjects to export their data'),
+    rightToObjection: z.boolean().default(true).describe('Allow data subjects to object to processing'),
+  }).describe('Data subject rights configuration per GDPR Articles 15-21'),
   legalBasis: z.enum([
     'consent',
     'contract',
     'legal-obligation',
     'vital-interests',
     'public-task',
     'legitimate-interests',
-  ]),
-  consentTracking: z.boolean().default(true),
-  dataRetentionDays: z.number().optional(),
-  dataProcessingAgreement: z.string().optional(),
-});
+  ]).describe('Legal basis for data processing under GDPR Article 6'),
+  consentTracking: z.boolean().default(true).describe('Track and record user consent'),
+  dataRetentionDays: z.number().optional().describe('Maximum data retention period in days'),
+  dataProcessingAgreement: z.string().optional().describe('URL or reference to the data processing agreement'),
+}).describe('GDPR (General Data Protection Regulation) compliance configuration');
 
 export type GDPRConfig = z.infer<typeof GDPRConfigSchema>;
 export type GDPRConfigInput = z.input<typeof GDPRConfigSchema>;
 
 export const HIPAAConfigSchema = z.object({
-  enabled: z.boolean(),
+  enabled: z.boolean().describe('Enable HIPAA compliance controls'),
   phi: z.object({
-    encryption: z.boolean().default(true),
-    accessControl: z.boolean().default(true),
-    auditTrail: z.boolean().default(true),
-    backupAndRecovery: z.boolean().default(true),
-  }),
-  businessAssociateAgreement: z.boolean().default(false),
-});
+    encryption: z.boolean().default(true).describe('Encrypt Protected Health Information at rest'),
+    accessControl: z.boolean().default(true).describe('Enforce role-based access to PHI'),
+    auditTrail: z.boolean().default(true).describe('Log all PHI access events'),
+    backupAndRecovery: z.boolean().default(true).describe('Enable PHI backup and disaster recovery'),
+  }).describe('Protected Health Information safeguards'),
+  businessAssociateAgreement: z.boolean().default(false).describe('BAA is in place with third-party processors'),
+}).describe('HIPAA (Health Insurance Portability and Accountability Act) compliance configuration');
 
 export type HIPAAConfig = z.infer<typeof HIPAAConfigSchema>;
 export type HIPAAConfigInput = z.input<typeof HIPAAConfigSchema>;
 
 export const PCIDSSConfigSchema = z.object({
-  enabled: z.boolean(),
-  level: z.enum(['1', '2', '3', '4']),
-  cardDataFields: z.array(z.string()),
-  tokenization: z.boolean().default(true),
-  encryptionInTransit: z.boolean().default(true),
-  encryptionAtRest: z.boolean().default(true),
-});
+  enabled: z.boolean().describe('Enable PCI-DSS compliance controls'),
+  level: z.enum(['1', '2', '3', '4']).describe('PCI-DSS compliance level (1 = highest)'),
+  cardDataFields: z.array(z.string()).describe('Field names containing cardholder data'),
+  tokenization: z.boolean().default(true).describe('Replace card data with secure tokens'),
+  encryptionInTransit: z.boolean().default(true).describe('Encrypt cardholder data during transmission'),
+  encryptionAtRest: z.boolean().default(true).describe('Encrypt stored cardholder data'),
+}).describe('PCI-DSS (Payment Card Industry Data Security Standard) compliance configuration');
 
 export type PCIDSSConfig = z.infer<typeof PCIDSSConfigSchema>;
 export type PCIDSSConfigInput = z.input<typeof PCIDSSConfigSchema>;
 
 export const AuditLogConfigSchema = z.object({
-  enabled: z.boolean().default(true),
-  retentionDays: z.number().default(365),
-  immutable: z.boolean().default(true),
-  signLogs: z.boolean().default(false),
+  enabled: z.boolean().default(true).describe('Enable audit logging'),
+  retentionDays: z.number().default(365).describe('Number of days to retain audit logs'),
+  immutable: z.boolean().default(true).describe('Prevent modification or deletion of audit logs'),
+  signLogs: z.boolean().default(false).describe('Cryptographically sign log entries for tamper detection'),
   events: z.array(z.enum([
     'create',
     'read',
@@ -70,18 +70,18 @@ export const AuditLogConfigSchema = z.object({
     'login',
     'logout',
     'failed-login',
-  ])),
-});
+  ])).describe('Event types to capture in the audit log'),
+}).describe('Audit log configuration for compliance and security monitoring');
 
 export type AuditLogConfig = z.infer<typeof AuditLogConfigSchema>;
 export type AuditLogConfigInput = z.input<typeof AuditLogConfigSchema>;
 
 export const ComplianceConfigSchema = z.object({
-  gdpr: GDPRConfigSchema.optional(),
-  hipaa: HIPAAConfigSchema.optional(),
-  pciDss: PCIDSSConfigSchema.optional(),
-  auditLog: AuditLogConfigSchema,
-});
+  gdpr: GDPRConfigSchema.optional().describe('GDPR compliance settings'),
+  hipaa: HIPAAConfigSchema.optional().describe('HIPAA compliance settings'),
+  pciDss: PCIDSSConfigSchema.optional().describe('PCI-DSS compliance settings'),
+  auditLog: AuditLogConfigSchema.describe('Audit log configuration'),
+}).describe('Unified compliance configuration spanning GDPR, HIPAA, and PCI-DSS');
 
 export type ComplianceConfig = z.infer<typeof ComplianceConfigSchema>;
 export type ComplianceConfigInput = z.input<typeof ComplianceConfigSchema>;

packages/spec/src/system/encryption.zod.ts

@@ -8,7 +8,7 @@ export const EncryptionAlgorithmSchema = z.enum([
   'aes-256-gcm',
   'aes-256-cbc',
   'chacha20-poly1305',
-]);
+]).describe('Supported encryption algorithm');
 
 export type EncryptionAlgorithm = z.infer<typeof EncryptionAlgorithmSchema>;
 
@@ -18,7 +18,7 @@ export const KeyManagementProviderSchema = z.enum([
   'azure-key-vault',
   'gcp-kms',
   'hashicorp-vault',
-]);
+]).describe('Key management service provider');
 
 export type KeyManagementProvider = z.infer<typeof KeyManagementProviderSchema>;
 
@@ -27,7 +27,7 @@ export const KeyRotationPolicySchema = z.object({
   frequencyDays: z.number().min(1).default(90).describe('Rotation frequency in days'),
   retainOldVersions: z.number().default(3).describe('Number of old key versions to retain'),
   autoRotate: z.boolean().default(true).describe('Automatically rotate without manual approval'),
-});
+}).describe('Policy for automatic encryption key rotation');
 
 export type KeyRotationPolicy = z.infer<typeof KeyRotationPolicySchema>;
 export type KeyRotationPolicyInput = z.input<typeof KeyRotationPolicySchema>;
@@ -43,7 +43,7 @@ export const EncryptionConfigSchema = z.object({
   scope: z.enum(['field', 'record', 'table', 'database']).describe('Encryption scope level'),
   deterministicEncryption: z.boolean().default(false).describe('Allows equality queries on encrypted data'),
   searchableEncryption: z.boolean().default(false).describe('Allows search on encrypted data'),
-});
+}).describe('Field-level encryption configuration');
 
 export type EncryptionConfig = z.infer<typeof EncryptionConfigSchema>;
 export type EncryptionConfigInput = z.input<typeof EncryptionConfigSchema>;
@@ -52,7 +52,7 @@ export const FieldEncryptionSchema = z.object({
   fieldName: z.string().describe('Name of the field to encrypt'),
   encryptionConfig: EncryptionConfigSchema.describe('Encryption settings for this field'),
   indexable: z.boolean().default(false).describe('Allow indexing on encrypted field'),
-});
+}).describe('Per-field encryption assignment');
 
 export type FieldEncryption = z.infer<typeof FieldEncryptionSchema>;
 export type FieldEncryptionInput = z.input<typeof FieldEncryptionSchema>;

packages/spec/src/system/masking.zod.ts

@@ -11,28 +11,28 @@ export const MaskingStrategySchema = z.enum([
   'randomize',    // Randomize: generate random value
   'nullify',      // Null value: null
   'substitute',   // Substitute with dummy data
-]);
+]).describe('Data masking strategy for PII protection');
 
 export type MaskingStrategy = z.infer<typeof MaskingStrategySchema>;
 
 export const MaskingRuleSchema = z.object({
-  field: z.string(),
-  strategy: MaskingStrategySchema,
+  field: z.string().describe('Field name to apply masking to'),
+  strategy: MaskingStrategySchema.describe('Masking strategy to use'),
   pattern: z.string().optional().describe('Regex pattern for partial masking'),
-  preserveFormat: z.boolean().default(true),
-  preserveLength: z.boolean().default(true),
+  preserveFormat: z.boolean().default(true).describe('Keep the original data format after masking'),
+  preserveLength: z.boolean().default(true).describe('Keep the original data length after masking'),
   roles: z.array(z.string()).optional().describe('Roles that see masked data'),
   exemptRoles: z.array(z.string()).optional().describe('Roles that see unmasked data'),
-});
+}).describe('Masking rule for a single field');
 
 export type MaskingRule = z.infer<typeof MaskingRuleSchema>;
 export type MaskingRuleInput = z.input<typeof MaskingRuleSchema>;
 
 export const MaskingConfigSchema = z.object({
-  enabled: z.boolean().default(false),
-  rules: z.array(MaskingRuleSchema),
-  auditUnmasking: z.boolean().default(true),
-});
+  enabled: z.boolean().default(false).describe('Enable data masking'),
+  rules: z.array(MaskingRuleSchema).describe('List of field-level masking rules'),
+  auditUnmasking: z.boolean().default(true).describe('Log when masked data is accessed unmasked'),
+}).describe('Top-level data masking configuration for PII protection');
 
 export type MaskingConfig = z.infer<typeof MaskingConfigSchema>;
 export type MaskingConfigInput = z.input<typeof MaskingConfigSchema>;

packages/spec/src/system/message-queue.zod.ts

@@ -11,48 +11,48 @@ export const MessageQueueProviderSchema = z.enum([
   'redis-pubsub',
   'google-pubsub',
   'azure-service-bus',
-]);
+]).describe('Supported message queue backend provider');
 
 export type MessageQueueProvider = z.infer<typeof MessageQueueProviderSchema>;
 
 export const TopicConfigSchema = z.object({
-  name: z.string(),
-  partitions: z.number().default(1),
-  replicationFactor: z.number().default(1),
-  retentionMs: z.number().optional(),
-  compressionType: z.enum(['none', 'gzip', 'snappy', 'lz4']).default('none'),
-});
+  name: z.string().describe('Topic name identifier'),
+  partitions: z.number().default(1).describe('Number of partitions for parallel consumption'),
+  replicationFactor: z.number().default(1).describe('Number of replicas for fault tolerance'),
+  retentionMs: z.number().optional().describe('Message retention period in milliseconds'),
+  compressionType: z.enum(['none', 'gzip', 'snappy', 'lz4']).default('none').describe('Message compression algorithm'),
+}).describe('Configuration for a message queue topic');
 
 export type TopicConfig = z.infer<typeof TopicConfigSchema>;
 
 export const ConsumerConfigSchema = z.object({
-  groupId: z.string(),
-  autoOffsetReset: z.enum(['earliest', 'latest']).default('latest'),
-  enableAutoCommit: z.boolean().default(true),
-  maxPollRecords: z.number().default(500),
-});
+  groupId: z.string().describe('Consumer group identifier'),
+  autoOffsetReset: z.enum(['earliest', 'latest']).default('latest').describe('Where to start reading when no offset exists'),
+  enableAutoCommit: z.boolean().default(true).describe('Automatically commit consumed offsets'),
+  maxPollRecords: z.number().default(500).describe('Maximum records returned per poll'),
+}).describe('Consumer group configuration for topic consumption');
 
 export type ConsumerConfig = z.infer<typeof ConsumerConfigSchema>;
 
 export const DeadLetterQueueSchema = z.object({
-  enabled: z.boolean().default(false),
-  maxRetries: z.number().default(3),
-  queueName: z.string(),
-});
+  enabled: z.boolean().default(false).describe('Enable dead letter queue for failed messages'),
+  maxRetries: z.number().default(3).describe('Maximum delivery attempts before sending to DLQ'),
+  queueName: z.string().describe('Name of the dead letter queue'),
+}).describe('Dead letter queue configuration for unprocessable messages');
 
 export type DeadLetterQueue = z.infer<typeof DeadLetterQueueSchema>;
 
 export const MessageQueueConfigSchema = z.object({
-  provider: MessageQueueProviderSchema,
-  topics: z.array(TopicConfigSchema),
-  consumers: z.array(ConsumerConfigSchema).optional(),
-  deadLetterQueue: DeadLetterQueueSchema.optional(),
-  ssl: z.boolean().default(false),
+  provider: MessageQueueProviderSchema.describe('Message queue backend provider'),
+  topics: z.array(TopicConfigSchema).describe('List of topic configurations'),
+  consumers: z.array(ConsumerConfigSchema).optional().describe('Consumer group configurations'),
+  deadLetterQueue: DeadLetterQueueSchema.optional().describe('Dead letter queue for failed messages'),
+  ssl: z.boolean().default(false).describe('Enable SSL/TLS for broker connections'),
   sasl: z.object({
-    mechanism: z.enum(['plain', 'scram-sha-256', 'scram-sha-512']),
-    username: z.string(),
-    password: z.string(),
-  }).optional(),
-});
+    mechanism: z.enum(['plain', 'scram-sha-256', 'scram-sha-512']).describe('SASL authentication mechanism'),
+    username: z.string().describe('SASL username'),
+    password: z.string().describe('SASL password'),
+  }).optional().describe('SASL authentication configuration'),
+}).describe('Top-level message queue configuration');
 
 export type MessageQueueConfig = z.infer<typeof MessageQueueConfigSchema>;