test: improve test coverage

Author: AugustinMauroy

.c8rc.json

@@ -2,6 +2,7 @@
   "all": true,
   "exclude": [
     "eslint.config.mjs",
+    "**/*.test.mjs",
     "**/fixtures",
     "src/generators/legacy-html/assets",
     "src/generators/web/ui",

src/generators/addon-verify/__tests__/index.test.mjs

@@ -0,0 +1,78 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { u } from 'unist-builder';
+
+import addon from '../index.mjs';
+import {
+  normalizeSectionName,
+  generateSectionFolderName,
+} from '../utils/section.mjs';
+
+test('returns empty array when no code blocks match filename comment', async () => {
+  const entry = {
+    heading: { data: { name: 'Section A' } },
+    content: u('root', [u('code', 'console.log("no filename header");')]),
+  };
+
+  const result = await addon.generate([entry], {});
+
+  // No sections were buildable / no filenames extracted
+  assert.deepEqual(result, []);
+});
+
+test('ignores non-buildable sections (needs both .cc and .js)', async () => {
+  // Only a .cc file present -> not buildable
+  const entry = {
+    heading: { data: { name: 'OnlyCC' } },
+    content: u('root', [u('code', '// file1.cc\nint main() {}')]),
+  };
+
+  const result = await addon.generate([entry], {});
+
+  assert.deepEqual(result, []);
+});
+
+test('generates files array and writes files to disk when output provided', async () => {
+  const sectionName = 'My Addon Section';
+
+  const entry = {
+    heading: { data: { name: sectionName } },
+    content: u('root', [
+      u('code', '// file1.cc\nint main() {}'),
+      u(
+        'code',
+        "// test.js\nmodule.exports = require('./build/Release/addon');"
+      ),
+    ]),
+  };
+
+  const tmp = await mkdtemp(join(tmpdir(), 'doc-kit-'));
+
+  const returned = await addon.generate([entry], { output: tmp });
+
+  // Returned is an array of file arrays (one per section)
+  assert.equal(Array.isArray(returned), true);
+  assert.equal(returned.length, 1);
+
+  const files = returned[0];
+
+  assert.ok(files.some(f => f.name === 'file1.cc'));
+  assert.ok(files.some(f => f.name === 'test.js'));
+  assert.ok(files.some(f => f.name === 'binding.gyp'));
+
+  // Verify files were written to disk under the computed folder name
+  const folderName = generateSectionFolderName(
+    normalizeSectionName(sectionName),
+    0
+  );
+
+  const file1 = await readFile(join(tmp, folderName, 'file1.cc'), 'utf-8');
+  const binding = await readFile(join(tmp, folderName, 'binding.gyp'), 'utf-8');
+
+  assert.match(file1, /int main/);
+  assert.match(binding, /targets/);
+});

src/generators/llms-txt/__tests__/index.test.mjs

@@ -0,0 +1,58 @@
+import assert from 'node:assert/strict';
+import { readFile, mkdtemp } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import llms from '../index.mjs';
+
+const makeEntry = ({
+  title = 'MyAPI',
+  depth = 1,
+  desc = 'A description',
+  api = 'doc/some/path.md',
+  llm_description,
+} = {}) => ({
+  heading: { depth, data: { name: title } },
+  content: {
+    children: [
+      { type: 'paragraph', children: [{ type: 'text', value: desc }] },
+    ],
+  },
+  api_doc_source: api,
+  llm_description,
+});
+
+test('generate returns filled template including depth 1 entries', async () => {
+  const entry = makeEntry({ title: 'Alpha', desc: 'Alpha description' });
+
+  const result = await llms.generate([entry], {});
+
+  assert.equal(typeof result, 'string');
+  assert.match(result, /- \[Alpha\]/);
+  assert.match(result, /Alpha description/);
+});
+
+test('generate only includes depth 1 headings', async () => {
+  const entry1 = makeEntry({ title: 'Top', depth: 1, desc: 'Top desc' });
+  const entry2 = makeEntry({ title: 'Sub', depth: 2, desc: 'Sub desc' });
+
+  const result = await llms.generate([entry1, entry2], {});
+
+  assert.match(result, /- \[Top\]/);
+  assert.doesNotMatch(result, /- \[Sub\]/);
+});
+
+test('generate writes llms.txt when output is provided', async () => {
+  const entry = makeEntry({ title: 'WriteTest', desc: 'Write description' });
+
+  const tmp = await mkdtemp(join(tmpdir(), 'doc-kit-'));
+
+  const returned = await llms.generate([entry], { output: tmp });
+
+  const file = await readFile(join(tmp, 'llms.txt'), 'utf-8');
+
+  assert.equal(returned, file);
+  assert.match(file, /- \[WriteTest\]/);
+  assert.match(file, /Write description/);
+});

src/generators/man-page/__tests__/index.test.mjs

@@ -0,0 +1,97 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { u } from 'unist-builder';
+
+import manpage from '../index.mjs';
+
+const textNode = txt => u('text', txt);
+
+const createMock = ({
+  api = 'cli',
+  slug = '',
+  depth = 2,
+  headingText = '',
+  desc = '',
+} = {}) => ({
+  api,
+  slug,
+  heading: { depth, data: { text: headingText } },
+  // eslint-disable-next-line no-sparse-arrays
+  content: u('root', [, u('paragraph', [textNode(desc)])]),
+});
+
+test('throws when no cli documentation present', async () => {
+  await assert.rejects(
+    async () => {
+      await manpage.generate([{ api: 'not-cli' }], {});
+    },
+    { message: /Could not find any `cli` documentation/ }
+  );
+});
+
+test('generates mandoc including options and environment entries', async () => {
+  const components = [
+    createMock({ api: 'cli', slug: 'cli', depth: 1 }),
+    createMock({ api: 'cli', slug: 'options', depth: 2 }),
+    createMock({
+      api: 'cli',
+      slug: 'opt-a',
+      depth: 3,
+      headingText: '`-a`, `--all`',
+      desc: 'Option A description',
+    }),
+    createMock({ api: 'cli', slug: 'environment-variables-1', depth: 2 }),
+    createMock({
+      api: 'cli',
+      slug: 'env-foo',
+      depth: 3,
+      headingText: '`FOO=bar`',
+      desc: 'Env FOO description',
+    }),
+    createMock({ api: 'cli', slug: 'after', depth: 2 }),
+  ];
+
+  const result = await manpage.generate(components, {});
+
+  // Ensure mandoc markers for options and environment variables are present
+  assert.match(result, /\.It Fl/);
+  assert.match(result, /Option A description/);
+  assert.match(result, /\.It Ev/);
+  assert.match(result, /Env FOO description/);
+});
+
+test('writes node.1 to output when provided', async () => {
+  const components = [
+    createMock({ api: 'cli', slug: 'options', depth: 2 }),
+    createMock({
+      api: 'cli',
+      slug: 'opt-a',
+      depth: 3,
+      headingText: '`-a`',
+      desc: 'desc',
+    }),
+    createMock({ api: 'cli', slug: 'environment-variables-1', depth: 2 }),
+    createMock({
+      api: 'cli',
+      slug: 'env',
+      depth: 3,
+      headingText: '`X=`',
+      desc: 'env desc',
+    }),
+    createMock({ api: 'cli', slug: 'end', depth: 2 }),
+  ];
+
+  const tmp = await mkdtemp(join(tmpdir(), 'doc-kit-'));
+
+  const returned = await manpage.generate(components, { output: tmp });
+
+  const file = await readFile(join(tmp, 'node.1'), 'utf-8');
+
+  assert.equal(returned, file);
+  assert.match(file, /desc/);
+  assert.match(file, /env desc/);
+});

src/generators/metadata/__tests__/index.test.mjs

@@ -0,0 +1,31 @@
+import { deepStrictEqual, strictEqual } from 'node:assert';
+import { describe, it } from 'node:test';
+
+import generator from '../index.mjs';
+
+describe('generators/metadata/index', () => {
+  it('streams chunk results and yields flattened arrays', async () => {
+    const inputs = [1, 2, 3];
+
+    const worker = {
+      // Simulate an async generator that yields chunked results
+      async *stream() {
+        yield [[1, 2], [3]];
+        yield [[4]];
+      },
+    };
+
+    const results = [];
+
+    for await (const chunk of generator.generate(inputs, {
+      typeMap: {},
+      worker,
+    })) {
+      results.push(chunk);
+    }
+
+    strictEqual(results.length, 2);
+    deepStrictEqual(results[0], [1, 2, 3]);
+    deepStrictEqual(results[1], [4]);
+  });
+});

src/generators/metadata/__tests__/parse.test.mjs

@@ -0,0 +1,118 @@
+import { strictEqual, deepStrictEqual } from 'node:assert';
+import { describe, it } from 'node:test';
+
+import { u } from 'unist-builder';
+import { VFile } from 'vfile';
+
+import { parseApiDoc } from '../utils/parse.mjs';
+
+describe('generators/metadata/utils/parse', () => {
+  it('parses heading, stability, YAML and converts markdown links', () => {
+    const tree = u('root', [
+      u('heading', { depth: 1 }, [u('text', 'My API')]),
+      u('blockquote', [u('paragraph', [u('text', 'Stability: 2 - stable')])]),
+      u('html', '<!-- YAML\nsource_link: https://example.com\n-->'),
+      u('paragraph', [
+        u('text', 'See '),
+        u('link', { url: 'other.md#foo' }, [u('text', 'other')]),
+      ]),
+    ]);
+
+    const file = new VFile({ path: 'doc/api/my-api.md' });
+
+    const results = parseApiDoc({ file, tree }, {});
+
+    strictEqual(results.length, 1);
+    const [entry] = results;
+
+    strictEqual(entry.source_link, 'https://example.com');
+    strictEqual(entry.stability.children.length, 1);
+    strictEqual(entry.stability.children[0].data.index, '2');
+
+    // Find a paragraph child that contains a link and assert transformed URL
+    const paragraph = entry.content.children.find(n => n.type === 'paragraph');
+    const link = paragraph.children.find(c => c.type === 'link');
+    strictEqual(link.url, 'other.html#foo');
+  });
+
+  it('inserts a fake heading when none exist', () => {
+    const tree = u('root', [u('paragraph', [u('text', 'No heading content')])]);
+    const file = new VFile({ path: 'doc/api/noheading.md' });
+
+    const results = parseApiDoc({ file, tree }, {});
+
+    strictEqual(results.length, 1);
+    const [entry] = results;
+
+    // Fake heading has empty text
+    deepStrictEqual(entry.heading.data.text, '');
+  });
+
+  it('converts link references using definitions and removes definitions', () => {
+    const heading = u('heading', { depth: 1 }, [u('text', 'Ref API')]);
+
+    const linkRef = u('linkReference', { identifier: 'def1' }, [
+      u('text', 'ref'),
+    ]);
+
+    const definition = u(
+      'definition',
+      { identifier: 'def1', url: 'https://def.example/' },
+      []
+    );
+
+    const tree = u('root', [
+      heading,
+      u('paragraph', [u('text', 'See '), linkRef]),
+      definition,
+    ]);
+
+    const file = new VFile({ path: 'doc/api/ref-api.md' });
+
+    const results = parseApiDoc({ file, tree }, {});
+
+    strictEqual(results.length, 1);
+    const [entry] = results;
+
+    const paragraph = entry.content.children.find(n => n.type === 'paragraph');
+    const link = paragraph.children.find(c => c.type === 'link');
+    strictEqual(link.url, 'https://def.example/');
+  });
+
+  it('converts type references to links using provided typeMap', () => {
+    const tree = u('root', [
+      u('heading', { depth: 1 }, [u('text', 'Types API')]),
+      u('paragraph', [u('text', 'Type is {Foo}')]),
+    ]);
+
+    const file = new VFile({ path: 'doc/api/types.md' });
+
+    const results = parseApiDoc({ file, tree }, { Foo: 'foo.html' });
+
+    strictEqual(results.length, 1);
+    const [entry] = results;
+
+    const paragraph = entry.content.children.find(n => n.type === 'paragraph');
+    const link = paragraph.children.find(c => c.type === 'link');
+    strictEqual(link.url, 'foo.html');
+  });
+
+  it('converts unix manual references to man7 links', () => {
+    const tree = u('root', [
+      u('heading', { depth: 1 }, [u('text', 'Man API')]),
+      u('paragraph', [u('text', 'Run ls(1) for help')]),
+    ]);
+
+    const file = new VFile({ path: 'doc/api/man.md' });
+
+    const results = parseApiDoc({ file, tree }, {});
+
+    strictEqual(results.length, 1);
+    const [entry] = results;
+
+    const paragraph = entry.content.children.find(n => n.type === 'paragraph');
+    const link = paragraph.children.find(c => c.type === 'link');
+    // should point to man7 man page for ls in section 1
+    strictEqual(link.url.includes('man-pages/man1/ls.1.html'), true);
+  });
+});