refactor(models): replace .describe('...') with recommended .meta({ description: '...' })

Author: matejchalk

packages/models/src/lib/audit-output.ts

@@ -10,35 +10,39 @@ import { issueSchema } from './issue.js';
 import { tableSchema } from './table.js';
 import { treeSchema } from './tree.js';
 
-export const auditValueSchema =
-  nonnegativeNumberSchema.describe('Raw numeric value');
+export const auditValueSchema = nonnegativeNumberSchema.meta({
+  description: 'Raw numeric value',
+});
 export const auditDisplayValueSchema = z
   .string()
   .optional()
-  .describe("Formatted value (e.g. '0.9 s', '2.1 MB')");
+  .meta({ description: "Formatted value (e.g. '0.9 s', '2.1 MB')" });
 
 export const auditDetailsSchema = z
   .object({
-    issues: z.array(issueSchema).describe('List of findings').optional(),
+    issues: z
+      .array(issueSchema)
+      .meta({ description: 'List of findings' })
+      .optional(),
     table: tableSchema('Table of related findings').optional(),
     trees: z
       .array(treeSchema)
-      .describe('Findings in tree structure')
+      .meta({ description: 'Findings in tree structure' })
       .optional(),
   })
-  .describe('Detailed information');
+  .meta({ description: 'Detailed information' });
 export type AuditDetails = z.infer<typeof auditDetailsSchema>;
 
 export const auditOutputSchema = z
   .object({
-    slug: slugSchema.describe('Reference to audit'),
+    slug: slugSchema.meta({ description: 'Reference to audit' }),
     displayValue: auditDisplayValueSchema,
     value: auditValueSchema,
     score: scoreSchema,
     scoreTarget: scoreTargetSchema,
     details: auditDetailsSchema.optional(),
   })
-  .describe('Audit information');
+  .meta({ description: 'Audit information' });
 
 export type AuditOutput = z.infer<typeof auditOutputSchema>;
 

packages/models/src/lib/audit.ts

@@ -4,7 +4,7 @@ import { metaSchema, slugSchema } from './implementation/schemas.js';
 
 export const auditSchema = z
   .object({
-    slug: slugSchema.describe('ID (unique within plugin)'),
+    slug: slugSchema.meta({ description: 'ID (unique within plugin)' }),
   })
   .extend(
     metaSchema({
@@ -21,4 +21,4 @@ export const pluginAuditsSchema = z
   .array(auditSchema)
   .min(1)
   .check(createDuplicateSlugsCheck('Audit'))
-  .describe('List of audits maintained in a plugin');
+  .meta({ description: 'List of audits maintained in a plugin' });

packages/models/src/lib/cache-config.ts

@@ -4,26 +4,27 @@ export const cacheConfigObjectSchema = z
   .object({
     read: z
       .boolean()
-      .describe('Whether to read from cache if available')
+      .meta({ description: 'Whether to read from cache if available' })
       .default(false),
     write: z
       .boolean()
-      .describe('Whether to write results to cache')
+      .meta({ description: 'Whether to write results to cache' })
       .default(false),
   })
-  .describe('Cache configuration object for read and/or write operations');
+  .meta({
+    description: 'Cache configuration object for read and/or write operations',
+  });
 export type CacheConfigObject = z.infer<typeof cacheConfigObjectSchema>;
 
-export const cacheConfigShorthandSchema = z
-  .boolean()
-  .describe(
+export const cacheConfigShorthandSchema = z.boolean().meta({
+  description:
     'Cache configuration shorthand for both, read and write operations',
-  );
+});
 export type CacheConfigShorthand = z.infer<typeof cacheConfigShorthandSchema>;
 
 export const cacheConfigSchema = z
   .union([cacheConfigShorthandSchema, cacheConfigObjectSchema])
-  .describe('Cache configuration for read and write operations')
+  .meta({ description: 'Cache configuration for read and write operations' })
   .default(false);
 
 export type CacheConfig = z.infer<typeof cacheConfigSchema>;

packages/models/src/lib/category-config.ts

@@ -16,11 +16,10 @@ export const categoryRefSchema = weightedRefSchema(
   'Weighted references to audits and/or groups for the category',
   'Slug of an audit or group (depending on `type`)',
 ).extend({
-  type: z
-    .enum(['audit', 'group'])
-    .describe(
+  type: z.enum(['audit', 'group']).meta({
+    description:
       'Discriminant for reference kind, affects where `slug` is looked up',
-    ),
+  }),
   plugin: slugSchema.describe(
     'Plugin slug (plugin should contain referenced audit or group)',
   ),
@@ -70,4 +69,4 @@ function formatSerializedCategoryRefTargets(keys: string[]): string {
 export const categoriesSchema = z
   .array(categoryConfigSchema)
   .check(createDuplicateSlugsCheck('Category'))
-  .describe('Categorization of individual audits');
+  .meta({ description: 'Categorization of individual audits' });

packages/models/src/lib/commit.ts

@@ -8,11 +8,13 @@ export const commitSchema = z
         /^[\da-f]{40}$/,
         'Commit SHA should be a 40-character hexadecimal string',
       )
-      .describe('Commit SHA (full)'),
-    message: z.string().describe('Commit message'),
-    date: z.coerce.date().describe('Date and time when commit was authored'),
-    author: z.string().trim().describe('Commit author name'),
+      .meta({ description: 'Commit SHA (full)' }),
+    message: z.string().meta({ description: 'Commit message' }),
+    date: z.coerce
+      .date()
+      .meta({ description: 'Date and time when commit was authored' }),
+    author: z.string().trim().meta({ description: 'Commit author name' }),
   })
-  .describe('Git commit');
+  .meta({ description: 'Git commit' });
 
 export type Commit = z.infer<typeof commitSchema>;

packages/models/src/lib/configuration.ts

@@ -5,9 +5,9 @@ import { globPathSchema } from './implementation/schemas.js';
  * Generic schema for a tool command configuration, reusable across plugins.
  */
 export const artifactGenerationCommandSchema = z.union([
-  z.string().min(1).describe('Generate artifact files'),
+  z.string().min(1).meta({ description: 'Generate artifact files' }),
   z.object({
-    command: z.string().min(1).describe('Generate artifact files'),
+    command: z.string().min(1).meta({ description: 'Generate artifact files' }),
     args: z.array(z.string()).optional(),
   }),
 ]);
@@ -16,7 +16,7 @@ export const pluginArtifactOptionsSchema = z.object({
   generateArtifactsCommand: artifactGenerationCommandSchema.optional(),
   artifactsPaths: z
     .union([globPathSchema, z.array(globPathSchema).min(1)])
-    .describe('File paths or glob patterns for artifact files'),
+    .meta({ description: 'File paths or glob patterns for artifact files' }),
 });
 
 export type PluginArtifactOptions = z.infer<typeof pluginArtifactOptionsSchema>;

packages/models/src/lib/group.ts

@@ -42,4 +42,4 @@ export const groupsSchema = z
   .array(groupSchema)
   .check(createDuplicateSlugsCheck('Group'))
   .optional()
-  .describe('List of groups');
+  .meta({ description: 'List of groups' });

packages/models/src/lib/implementation/schemas.ts

@@ -47,13 +47,13 @@ export const slugSchema = z
   .max(MAX_SLUG_LENGTH, {
     message: `The slug can be max ${MAX_SLUG_LENGTH} characters long`,
   })
-  .describe('Unique ID (human-readable, URL-safe)');
+  .meta({ description: 'Unique ID (human-readable, URL-safe)' });
 
 /**  Schema for a general description property */
 export const descriptionSchema = z
   .string()
   .max(MAX_DESCRIPTION_LENGTH)
-  .describe('Description (markdown)')
+  .meta({ description: 'Description (markdown)' })
   .optional();
 
 /* Schema for a URL */
@@ -79,20 +79,20 @@ export const docsUrlSchema = urlSchema
     }
     throw new ZodError(ctx.error.issues);
   })
-  .describe('Documentation site');
+  .meta({ description: 'Documentation site' });
 
 /** Schema for a title of a plugin, category and audit */
 export const titleSchema = z
   .string()
   .max(MAX_TITLE_LENGTH)
-  .describe('Descriptive name');
+  .meta({ description: 'Descriptive name' });
 
 /** Schema for score of audit, category or group */
 export const scoreSchema = z
   .number()
   .min(0)
   .max(1)
-  .describe('Value between 0 and 1');
+  .meta({ description: 'Value between 0 and 1' });
 
 /** Schema for a property indicating whether an entity is filtered out */
 export const isSkippedSchema = z.boolean().optional();
@@ -153,9 +153,10 @@ export const globPathSchema = z
     message:
       'The path must be a valid file path or glob pattern (supports *, **, {}, [], !, ?)',
   })
-  .describe(
-    'Schema for a glob pattern (supports wildcards like *, **, {}, !, etc.)',
-  );
+  .meta({
+    description:
+      'Schema for a glob pattern (supports wildcards like *, **, {}, !, etc.)',
+  });
 
 /** Schema for a fileNameSchema */
 export const fileNameSchema = z
@@ -176,16 +177,16 @@ export function packageVersionSchema<
 >(options?: { versionDescription?: string; required?: TRequired }) {
   const { versionDescription = 'NPM version of the package', required } =
     options ?? {};
-  const packageSchema = z.string().describe('NPM package name');
-  const versionSchema = z.string().describe(versionDescription);
+  const packageSchema = z.string().meta({ description: 'NPM package name' });
+  const versionSchema = z.string().meta({ description: versionDescription });
   return z
     .object({
       packageName: required ? packageSchema : packageSchema.optional(),
       version: required ? versionSchema : versionSchema.optional(),
     })
-    .describe(
-      'NPM package name and version of a published package',
-    ) as ZodObject<{
+    .meta({
+      description: 'NPM package name and version of a published package',
+    }) as ZodObject<{
     packageName: TRequired extends true ? ZodString : ZodOptional<ZodString>;
     version: TRequired extends true ? ZodString : ZodOptional<ZodString>;
   }>;
@@ -194,24 +195,27 @@ export function packageVersionSchema<
 /** Schema for a binary score threshold */
 export const scoreTargetSchema = nonnegativeNumberSchema
   .max(1)
-  .describe('Pass/fail score threshold (0-1)')
+  .meta({ description: 'Pass/fail score threshold (0-1)' })
   .optional();
 
 /** Schema for a weight */
-export const weightSchema = nonnegativeNumberSchema.describe(
-  'Coefficient for the given score (use weight 0 if only for display)',
-);
+export const weightSchema = nonnegativeNumberSchema.meta({
+  description:
+    'Coefficient for the given score (use weight 0 if only for display)',
+});
 
 export function weightedRefSchema(
   description: string,
   slugDescription: string,
 ) {
   return z
     .object({
-      slug: slugSchema.describe(slugDescription),
-      weight: weightSchema.describe('Weight used to calculate score'),
+      slug: slugSchema.meta({ description: slugDescription }),
+      weight: weightSchema.meta({
+        description: 'Weight used to calculate score',
+      }),
     })
-    .describe(description);
+    .meta({ description });
 }
 
 export type WeightedRef = z.infer<ReturnType<typeof weightedRefSchema>>;
@@ -223,7 +227,9 @@ export function scorableSchema<T extends ReturnType<typeof weightedRefSchema>>(
 ) {
   return z
     .object({
-      slug: slugSchema.describe('Human-readable unique ID, e.g. "performance"'),
+      slug: slugSchema.meta({
+        description: 'Human-readable unique ID, e.g. "performance"',
+      }),
       refs: z
         .array(refSchema)
         .min(1, { message: 'In a category, there has to be at least one ref' })
@@ -239,7 +245,7 @@ export function scorableSchema<T extends ReturnType<typeof weightedRefSchema>>(
 
 export const materialIconSchema = z
   .enum(MATERIAL_ICONS)
-  .describe('Icon from VSCode Material Icons extension');
+  .meta({ description: 'Icon from VSCode Material Icons extension' });
 export type MaterialIcon = z.infer<typeof materialIconSchema>;
 
 type Ref = { weight: number };
@@ -250,9 +256,11 @@ function hasNonZeroWeightedRef(refs: Ref[]) {
 
 export const filePositionSchema = z
   .object({
-    startLine: positiveIntSchema.describe('Start line'),
-    startColumn: positiveIntSchema.describe('Start column').optional(),
-    endLine: positiveIntSchema.describe('End line').optional(),
-    endColumn: positiveIntSchema.describe('End column').optional(),
+    startLine: positiveIntSchema.meta({ description: 'Start line' }),
+    startColumn: positiveIntSchema
+      .meta({ description: 'Start column' })
+      .optional(),
+    endLine: positiveIntSchema.meta({ description: 'End line' }).optional(),
+    endColumn: positiveIntSchema.meta({ description: 'End column' }).optional(),
   })
-  .describe('Location in file');
+  .meta({ description: 'Location in file' });

packages/models/src/lib/issue.ts

@@ -4,17 +4,17 @@ import { sourceFileLocationSchema } from './source.js';
 
 export const issueSeveritySchema = z
   .enum(['info', 'warning', 'error'])
-  .describe('Severity level');
+  .meta({ description: 'Severity level' });
 export type IssueSeverity = z.infer<typeof issueSeveritySchema>;
 
 export const issueSchema = z
   .object({
     message: z
       .string()
       .max(MAX_ISSUE_MESSAGE_LENGTH)
-      .describe('Descriptive error message'),
+      .meta({ description: 'Descriptive error message' }),
     severity: issueSeveritySchema,
     source: sourceFileLocationSchema.optional(),
   })
-  .describe('Issue information');
+  .meta({ description: 'Issue information' });
 export type Issue = z.infer<typeof issueSchema>;

packages/models/src/lib/persist-config.ts

@@ -5,9 +5,11 @@ export const formatSchema = z.enum(['json', 'md']);
 export type Format = z.infer<typeof formatSchema>;
 
 export const persistConfigSchema = z.object({
-  outputDir: filePathSchema.describe('Artifacts folder').optional(),
+  outputDir: filePathSchema
+    .meta({ description: 'Artifacts folder' })
+    .optional(),
   filename: fileNameSchema
-    .describe('Artifacts file name (without extension)')
+    .meta({ description: 'Artifacts file name (without extension)' })
     .optional(),
   format: z.array(formatSchema).optional(),
   skipReports: z.boolean().optional(),