feat(linter): create llm description rule

Author: araujogui

src/linter/constants.mjs

@@ -5,4 +5,6 @@ export const LINT_MESSAGES = {
   missingChangeVersion: 'Missing version field in the API doc entry',
   invalidChangeVersion: 'Invalid version number: {{version}}',
   duplicateStabilityNode: 'Duplicate stability node',
+  missingLlmDescription:
+    'Missing llm_description field or paragraph node in the API doc entry',
 };

src/linter/rules/index.mjs

@@ -3,6 +3,7 @@
 import { duplicateStabilityNodes } from './duplicate-stability-nodes.mjs';
 import { invalidChangeVersion } from './invalid-change-version.mjs';
 import { missingIntroducedIn } from './missing-introduced-in.mjs';
+import { missingLlmDescription } from './missing-llm-description.mjs';
 
 /**
  * @type {Record<string, import('../types').LintRule>}
@@ -11,4 +12,5 @@ export default {
   'duplicate-stability-nodes': duplicateStabilityNodes,
   'invalid-change-version': invalidChangeVersion,
   'missing-introduced-in': missingIntroducedIn,
+  'missing-llm-description': missingLlmDescription,
 };

src/linter/rules/missing-llm-description.mjs

@@ -0,0 +1,34 @@
+import { LINT_MESSAGES } from '../constants.mjs';
+
+/**
+ * Checks if a top-level entry is missing a llm_description field or a paragraph
+ * node.
+ *
+ * @param {ApiDocMetadataEntry[]} entries
+ * @returns {Array<import('../types.d.ts').LintIssue>}
+ */
+export const missingLlmDescription = entries => {
+  const issues = [];
+
+  for (const entry of entries) {
+    if (entry.heading.depth !== 1 || entry.llm_description) {
+      continue;
+    }
+
+    const descriptionNode = entry.content.children.find(
+      child => child.type === 'paragraph'
+    );
+
+    if (!descriptionNode) {
+      issues.push({
+        level: 'warn',
+        message: LINT_MESSAGES.missingLlmDescription,
+        location: {
+          path: entry.api_doc_source,
+        },
+      });
+    }
+  }
+
+  return issues;
+};