perf: drop node positions after metadata

.changeset/drop-positions.md

@@ -0,0 +1,5 @@
+---
+'@doc-kit/core': minor
+---
+
+The nodes of `metadata`'s entries no longer keep their `position` in the source once they are parsed, since nothing after `metadata` reads it. Builds hold less in memory and are faster, and the output of `json-simple` no longer has them either, now about a third of its size.

packages/core/src/generators/metadata/utils/__tests__/parse.test.mjs

@@ -4,6 +4,7 @@ import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
 import { u } from 'unist-builder';
+import { visit } from 'unist-util-visit';
 
 import { parseApiDoc } from '../parse.mjs';
 
@@ -338,4 +339,35 @@ describe('parseApiDoc', () => {
       assert.strictEqual(secondContent[0].type, 'heading');
     });
   });
+
+  describe('source positions', () => {
+    it('drops position from every node of an entry', () => {
+      const tree = u('root', [
+        h('fs'),
+        stability('Stability: 2 - Stable'),
+        u('paragraph', [u('text', 'Content.')]),
+      ]);
+      const position = {
+        start: { line: 1, column: 1 },
+        end: { line: 1, column: 1 },
+      };
+
+      visit(tree, node => {
+        node.position = position;
+      });
+
+      const [entry] = parseApiDoc({ path, tree }, typeMap);
+      const positioned = [];
+
+      visit(entry.content, node => {
+        if ('position' in node) {
+          positioned.push(node.type);
+        }
+      });
+
+      assert.deepStrictEqual(positioned, []);
+      assert.ok(!('position' in entry.heading));
+      assert.ok(entry.stability && !('position' in entry.stability));
+    });
+  });
 });

packages/core/src/generators/metadata/utils/parse.mjs

@@ -155,5 +155,14 @@ export const parseApiDoc = ({ path, tree, mdx = false }, typeMap) => {
     return SKIP;
   });
 
+  // Nothing after this reads a node's `position` (resolveTypes' warning
+  // already ran): dropping it saves memory, and copying it to and from the
+  // worker threads. An entry's heading and stability are nodes of its content
+  for (const { content } of metadataCollection) {
+    visit(content, node => {
+      delete node.position;
+    });
+  }
+
   return metadataCollection;
 };