yet another linter rule

eslint/src/rules/outOfLineRule.ts

@@ -1,7 +1,7 @@
 import type { RuleModule } from 'eslint-plugin-yml/lib/types.js';
 import { createRule } from 'eslint-plugin-yml/lib/utils';
 
-import { isNullable, isPairWithKey } from '../utils.js';
+import { isBlockScalar, isMapping, isNullable, isPairWithKey, isScalar } from '../utils.js';
 
 export function createOutOfLineRule({
   property,
@@ -24,6 +24,8 @@ export function createOutOfLineRule({
       },
       messages: {
         [messageId]: message,
+        nullDescription: 'description must not be present for `null` type',
+        descriptionLevel: 'description must not be next to the property',
       },
       type: 'layout',
       schema: [],
@@ -38,6 +40,29 @@ export function createOutOfLineRule({
           if (!isPairWithKey(node, property)) {
             return;
           }
+
+          // the 'null' must not have a description otherwise it will generate a model for it
+          if (
+            property === 'oneOf' &&
+            isNullable(node.value) &&
+            node.value.entries.some(
+              (entry) =>
+                isMapping(entry) &&
+                isPairWithKey(entry.pairs[0], 'type') &&
+                isScalar(entry.pairs[0].value) &&
+                !isBlockScalar(entry.pairs[0].value) &&
+                entry.pairs[0].value.raw === "'null'" &&
+                entry.pairs.length > 1,
+            )
+          ) {
+            context.report({
+              node: node.value,
+              messageId: 'nullDescription',
+            });
+
+            return;
+          }
+
           // parent is mapping, and parent is real parent that must be to the far left
           if (node.parent.parent.loc.start.column === 0) {
             return;

eslint/src/utils.ts

@@ -33,7 +33,7 @@ export function isPairWithValue(node: AST.YAMLNode | null, value: string): node
   return isScalar(node.value) && node.value.value === value;
 }
 
-export function isNullable(node: AST.YAMLNode | null): boolean {
+export function isNullable(node: AST.YAMLNode | null): node is AST.YAMLSequence {
   return (
     isSequence(node) &&
     node.entries.some(

eslint/tests/outOfLineRule.test.ts

@@ -105,6 +105,32 @@ simple:
       `,
         errors: [{ messageId: 'oneOfNotOutOfLine' }],
       },
+      {
+        code: `
+simple:
+  type: object
+  properties:
+    name:
+      oneOf:
+        - type: string
+          description: bla bla bla
+        - type: 'null'
+          description: bla bla bla
+      `,
+        errors: [{ messageId: 'nullDescription' }],
+      },
+      {
+        code: `
+root:
+  oneOf:
+    oneOf:
+      - type: string
+        description: bla bla bla
+      - type: 'null'
+        description: bla bla bla
+      `,
+        errors: [{ messageId: 'nullDescription' }],
+      },
     ],
   },
   {

mise.toml

@@ -0,0 +1,2 @@
+[tools]
+node = "22.13.1"

specs/abtesting/common/schemas/ABTest.yml

@@ -1,11 +1,10 @@
 ABTests:
   oneOf:
     - type: array
-      description: A/B tests.
+      description: The list of A/B tests, null if no A/B tests are configured for this application.
       items:
         $ref: '#/ABTest'
     - type: 'null'
-      description: No A/B tests are configured for this application.
 
 ABTest:
   type: object

specs/common/responses/common.yml

@@ -33,14 +33,12 @@ updatedAt:
   description: Date and time when the object was updated, in RFC 3339 format.
 
 updatedAtNullable:
-  default: null
   oneOf:
     - type: string
+      default: null
+      description: Date and time when the object was updated, in RFC 3339 format.
       example: 2023-07-04T12:49:15Z
-      description: |
-        Date and time when the object was updated, in RFC 3339 format.
     - type: 'null'
-      description: If null, this object wasn't updated yet.
 
 deletedAt:
   type: string

specs/crawler/common/schemas/getCrawlerResponse.yml

@@ -41,14 +41,12 @@ BaseResponse:
           description: Date and time when the last crawl started, in RFC 3339 format.
           example: 2024-04-07T09:16:04Z
         - type: 'null'
-          description: If null, this crawler hasn't indexed anything yet.
     lastReindexEndedAt:
       default: null
       oneOf:
         - type: string
           description: Date and time when the last crawl finished, in RFC 3339 format.
         - type: 'null'
-          description: If null, this crawler hasn't indexed anything yet.
   required:
     - name
     - createdAt