add metadata rule

Author: avivkeller

packages/remark-lint/src/api.mjs

@@ -9,6 +9,7 @@ import basePreset from './index.mjs';
 import duplicateStabilityNodes from './rules/duplicate-stability-nodes.mjs';
 import hashedSelfReference from './rules/hashed-self-reference.mjs';
 import orderedReferences from './rules/ordered-references.mjs';
+import requiredMetadata from './rules/required-metadata.mjs';
 import yamlComments from './rules/yaml/index.mjs';
 
 export default {
@@ -23,6 +24,7 @@ export default {
     yamlComments,
     hashedSelfReference,
     orderedReferences,
+    requiredMetadata,
     remarkLintNoUnusedDefinitions,
     [remarkLintFencedCodeFlag, { allowEmpty: false }],
     [remarkLintMaximumLineLength, 120],

packages/remark-lint/src/rules/__tests__/required-metadata.test.mjs

@@ -0,0 +1,50 @@
+import { describe, it } from 'node:test';
+
+import dedent from 'dedent';
+
+import requiredMetadata from '../required-metadata.mjs';
+import { testRule } from './utils.mjs';
+
+const testCases = [
+  {
+    name: 'both metadata comments present',
+    input: dedent`
+      <!-- introduced_in=v20.0.0 -->
+      <!-- llm_description=This explains something. -->
+    `,
+    expected: [],
+  },
+  {
+    name: 'missing introduced_in',
+    input: '<!-- llm_description=This explains something. -->',
+    expected: ['Missing "introduced_in" metadata'],
+  },
+  {
+    name: 'missing llm_description, but paragraph exists',
+    input: dedent`
+      <!-- introduced_in=v20.0.0 -->
+
+      This is a short description for LLMs.
+    `,
+    expected: [],
+  },
+  {
+    name: 'missing both metadata entries',
+    input: '',
+    expected: [
+      'Missing "introduced_in" metadata',
+      'Missing "llm_description" metadata',
+    ],
+  },
+  {
+    name: 'only paragraph, no comments at all',
+    input: 'This is just a paragraph, nothing else.',
+    expected: ['Missing "introduced_in" metadata'],
+  },
+];
+
+describe('duplicate-stability-nodes', () => {
+  for (const { name, input, expected } of testCases) {
+    it(name, () => testRule(requiredMetadata, input, expected));
+  }
+});

packages/remark-lint/src/rules/required-metadata.mjs

@@ -0,0 +1,38 @@
+import { lintRule } from 'unified-lint-rule';
+import { visit } from 'unist-util-visit';
+
+const requiredKeys = ['introduced_in', 'llm_description'];
+const checks = requiredKeys.map(key => new RegExp(`<!--\\s*${key}=.*?-->`));
+
+const hasRequiredMetadata = (tree, vfile) => {
+  const found = new Set();
+  let paragraphFound = false;
+
+  visit(tree, ['html', 'paragraph'], node => {
+    if (node.type === 'html') {
+      checks.forEach((check, i) => {
+        if (new RegExp(check).test(node.value)) {
+          found.add(requiredKeys[i]);
+        }
+      });
+    } else if (node.type === 'paragraph') {
+      paragraphFound = true;
+    } else {
+      // Continue searching
+      return false;
+    }
+  });
+
+  requiredKeys
+    .filter(key => !found.has(key))
+    .forEach(missingKey => {
+      // The first paragraph can also be the LLM description.
+      if (missingKey === 'llm_description' && paragraphFound) {
+        return;
+      }
+
+      vfile.message(`Missing "${missingKey}" metadata`, tree);
+    });
+};
+
+export default lintRule('node-core:required-metadata', hasRequiredMetadata);