Merge pull request #546 from objectstack-ai/copilot/fix-zod-schema-audit-report

Author: hotlong

packages/spec/ZOD_SCHEMA_AUDIT_REPORT.md

@@ -42,3 +42,7 @@ export const ConceptListResponseSchema = BaseResponseSchema.extend({
     description: z.string().optional(),
   })).describe('List of available concepts (Objects, Apps, Flows)'),
 });
+
+export type ObjectDefinitionResponse = z.infer<typeof ObjectDefinitionResponseSchema>;
+export type AppDefinitionResponse = z.infer<typeof AppDefinitionResponseSchema>;
+export type ConceptListResponse = z.infer<typeof ConceptListResponseSchema>;

packages/spec/src/api/metadata.zod.ts

@@ -410,6 +410,12 @@ export type DependencyGraph = z.infer<typeof DependencyGraphSchema>;
 
 /**
  * Dependency Conflict
+ * 
+ * Hub-level dependency conflict detected during plugin resolution.
+ * Focuses on package version conflicts across the marketplace/registry.
+ * 
+ * @see kernel/plugin-versioning.zod.ts DependencyConflictSchema for kernel-level plugin conflicts
+ *      which models plugin-to-plugin conflicts with richer resolution strategies.
  */
 export const DependencyConflictSchema = z.object({
   /**

packages/spec/src/hub/plugin-security.zod.ts

@@ -3,7 +3,6 @@ import { z } from 'zod';
 import {
   // Field Mapping
   FieldMappingSchema,
-  FieldTransformSchema,
 
   // Data Sync
   DataSyncConfigSchema,
@@ -22,14 +21,12 @@ import {
   ConnectorSchema,
   ConnectorTypeSchema,
   ConnectorStatusSchema,
-  AuthenticationSchema,
 
   // Types
   type Connector,
   type FieldMapping,
   type DataSyncConfig,
   type WebhookConfig,
-  type Authentication,
 } from './connector.zod';
 
 // Import shared auth schemas from canonical source
@@ -128,7 +125,7 @@ describe('OAuth2Schema', () => {
   });
 });
 
-describe('AuthenticationSchema', () => {
+describe('ConnectorAuthConfigSchema (Authentication)', () => {
   it('should accept all authentication types via discriminated union', () => {
     const keyAuth = { type: 'api-key' as const, key: 'key' };
     const oauth2Auth = { 
@@ -141,10 +138,10 @@ describe('AuthenticationSchema', () => {
     const basicAuth = { type: 'basic' as const, username: 'user', password: 'pass' };
     const noAuth = { type: 'none' as const };
 
-    expect(() => AuthenticationSchema.parse(keyAuth)).not.toThrow();
-    expect(() => AuthenticationSchema.parse(oauth2Auth)).not.toThrow();
-    expect(() => AuthenticationSchema.parse(basicAuth)).not.toThrow();
-    expect(() => AuthenticationSchema.parse(noAuth)).not.toThrow();
+    expect(() => AuthConfigSchema.parse(keyAuth)).not.toThrow();
+    expect(() => AuthConfigSchema.parse(oauth2Auth)).not.toThrow();
+    expect(() => AuthConfigSchema.parse(basicAuth)).not.toThrow();
+    expect(() => AuthConfigSchema.parse(noAuth)).not.toThrow();
   });
 });
 

packages/spec/src/integration/connector.test.ts

@@ -67,44 +67,15 @@ import { FieldMappingSchema as BaseFieldMappingSchema } from '../shared/mapping.
 
 // ============================================================================
 // Authentication Schemas - IMPORTED FROM CANONICAL SOURCE
-// For backward compatibility, we re-export the auth types from auth/config.zod.ts
+// Use ConnectorAuthConfigSchema from shared/connector-auth.zod.ts
 // ============================================================================
 
-/**
- * @deprecated Use ConnectorAuthConfigSchema from auth/config.zod instead
- * Kept for backward compatibility
- */
-export const AuthenticationSchema = ConnectorAuthConfigSchema;
-export type Authentication = z.infer<typeof ConnectorAuthConfigSchema>;
-
 // ============================================================================
 // Field Mapping Schema
 // Uses the canonical field mapping protocol from shared/mapping.zod.ts
 // Extended with connector-specific features
 // ============================================================================
 
-/**
- * Field Transformation Function (Connector-specific)
- * 
- * @deprecated Use TransformTypeSchema from shared/mapping.zod.ts instead
- */
-export const FieldTransformSchema = z.object({
-  type: z.enum([
-    'uppercase',
-    'lowercase',
-    'trim',
-    'date_format',
-    'number_format',
-    'custom',
-  ]).describe('Transformation type'),
-  
-  params: z.record(z.string(), z.unknown()).optional().describe('Transformation parameters'),
-  
-  function: z.string().optional().describe('Custom JavaScript function for transformation'),
-});
-
-export type FieldTransform = z.infer<typeof FieldTransformSchema>;
-
 /**
  * Connector Field Mapping Configuration
  * 
@@ -483,7 +454,7 @@ export const ConnectorSchema = z.object({
   /**
    * Authentication configuration
    */
-  authentication: AuthenticationSchema.describe('Authentication configuration'),
+  authentication: ConnectorAuthConfigSchema.describe('Authentication configuration'),
 
   /** Zapier-style Capabilities */
   actions: z.array(ConnectorActionSchema).optional(),

packages/spec/src/integration/connector.zod.ts

@@ -236,7 +236,11 @@ export const PluginCompatibilityMatrixSchema = z.object({
 
 /**
  * Dependency Conflict
- * Represents a conflict in plugin dependencies
+ * Represents a conflict in plugin dependencies at the kernel level.
+ * Models plugin-to-plugin dependency conflicts with typed conflict categories.
+ * 
+ * @see hub/plugin-security.zod.ts DependencyConflictSchema for hub-level package version conflicts
+ *      which focuses on marketplace registry resolution.
  */
 export const DependencyConflictSchema = z.object({
   /**

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

@@ -14,14 +14,14 @@ export const TestActionTypeSchema = z.enum([
   'api_call',
   'run_script',
   'wait' // Testing async processes
-]);
+]).describe('Type of test action to perform');
 
 export const TestActionSchema = z.object({
-  type: TestActionTypeSchema,
+  type: TestActionTypeSchema.describe('The action type to execute'),
   target: z.string().describe('Target Object, API Endpoint, or Function Name'),
   payload: z.record(z.string(), z.unknown()).optional().describe('Data to send or use'),
-  user: z.string().optional().describe('Run as specific user/role') // Impersonation
-});
+  user: z.string().optional().describe('Run as specific user/role for impersonation testing')
+}).describe('A single test action to execute against the system');
 
 // Assertion Types
 export const TestAssertionTypeSchema = z.enum([
@@ -36,46 +36,46 @@ export const TestAssertionTypeSchema = z.enum([
   'lt',
   'lte',
   'error' // Expecting an error
-]);
+]).describe('Comparison operator for test assertions');
 
 export const TestAssertionSchema = z.object({
   field: z.string().describe('Field path in the result to check (e.g. "body.data.0.status")'),
-  operator: TestAssertionTypeSchema,
-  expectedValue: z.unknown()
-});
+  operator: TestAssertionTypeSchema.describe('Comparison operator to use'),
+  expectedValue: z.unknown().describe('Expected value to compare against')
+}).describe('A test assertion that validates the result of a test action');
 
 // --- Test Structure ---
 
 export const TestStepSchema = z.object({
-  name: z.string(),
-  description: z.string().optional(),
-  action: TestActionSchema,
-  assertions: z.array(TestAssertionSchema).optional(),
+  name: z.string().describe('Step name for identification in test reports'),
+  description: z.string().optional().describe('Human-readable description of what this step tests'),
+  action: TestActionSchema.describe('The action to execute in this step'),
+  assertions: z.array(TestAssertionSchema).optional().describe('Assertions to validate after the action completes'),
   // Capture outputs to variables for subsequent steps
   capture: z.record(z.string(), z.string()).optional().describe('Map result fields to context variables: { "newId": "body._id" }')
-});
+}).describe('A single step in a test scenario, consisting of an action and optional assertions');
 
 export const TestScenarioSchema = z.object({
-  id: z.string(),
-  name: z.string(),
-  description: z.string().optional(),
-  tags: z.array(z.string()).optional(), // e.g. "critical", "regression", "crm"
+  id: z.string().describe('Unique scenario identifier'),
+  name: z.string().describe('Scenario name for test reports'),
+  description: z.string().optional().describe('Detailed description of the test scenario'),
+  tags: z.array(z.string()).optional().describe('Tags for filtering and categorization (e.g. "critical", "regression", "crm")'),
 
-  setup: z.array(TestStepSchema).optional().describe('Steps to run before main test'),
-  steps: z.array(TestStepSchema).describe('Main test sequence'),
-  teardown: z.array(TestStepSchema).optional().describe('Steps to cleanup'),
+  setup: z.array(TestStepSchema).optional().describe('Steps to run before main test (preconditions)'),
+  steps: z.array(TestStepSchema).describe('Main test sequence to execute'),
+  teardown: z.array(TestStepSchema).optional().describe('Steps to cleanup after test execution'),
 
   // Environment requirements
   requires: z.object({
-    params: z.array(z.string()).optional(), // Required env vars or params
-    plugins: z.array(z.string()).optional()
-  }).optional()
-});
+    params: z.array(z.string()).optional().describe('Required environment variables or parameters'),
+    plugins: z.array(z.string()).optional().describe('Required plugins that must be loaded')
+  }).optional().describe('Environment requirements for this scenario')
+}).describe('A complete test scenario with setup, execution steps, and teardown');
 
 export const TestSuiteSchema = z.object({
-  name: z.string(),
-  scenarios: z.array(TestScenarioSchema)
-});
+  name: z.string().describe('Test suite name'),
+  scenarios: z.array(TestScenarioSchema).describe('List of test scenarios in this suite')
+}).describe('A collection of test scenarios grouped into a test suite');
 
 export type TestSuite = z.infer<typeof TestSuiteSchema>;
 export type TestScenario = z.infer<typeof TestScenarioSchema>;

packages/spec/src/qa/testing.zod.ts

@@ -90,7 +90,7 @@ export const OwnerSharingRuleSchema = BaseSharingRuleSchema.extend({
 /**
  * Master Sharing Rule Schema
  */
-export const SharingRuleSchema: z.ZodType<any> = z.discriminatedUnion('type', [
+export const SharingRuleSchema = z.discriminatedUnion('type', [
   CriteriaSharingRuleSchema,
   OwnerSharingRuleSchema
 ]);