WIP

Co-Authored-By: Aviv Keller <[email protected]>

Author: AugustinMauroy

.c8rc.json

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

…rators/metadata/__tests__/parse.test.mjs …/metadata/utils/__tests__/parse.test.mjssrc/generators/metadata/__tests__/parse.test.mjs renamed to src/generators/metadata/utils/__tests__/parse.test.mjs src/generators/metadata/__tests__/parse.test.mjs renamed to src/generators/metadata/utils/__tests__/parse.test.mjs

@@ -1,12 +1,12 @@
-import { strictEqual, deepStrictEqual } from 'node:assert';
+import { deepStrictEqual, strictEqual } from 'node:assert/strict';
 import { describe, it } from 'node:test';
 
 import { u } from 'unist-builder';
 import { VFile } from 'vfile';
 
-import { parseApiDoc } from '../utils/parse.mjs';
+import { parseApiDoc } from '../parse.mjs';
 
-describe('generators/metadata/utils/parse', () => {
+describe('parseApiDoc', () => {
   it('parses heading, stability, YAML and converts markdown links', () => {
     const tree = u('root', [
       u('heading', { depth: 1 }, [u('text', 'My API')]),

src/generators/web/__tests__/index-generate.test.mjs

@@ -0,0 +1,39 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile } from 'node:fs/promises';
+import os from 'node:os';
+import { join } from 'node:path';
+import { describe, it } from 'node:test';
+
+import webGen from '../index.mjs';
+
+describe('generators/web - index generate', () => {
+  it('writes files when output is provided', async () => {
+    const tmp = await mkdtemp(join(os.tmpdir(), 'doc-kit-test-'));
+
+    const results = [{ html: Buffer.from('<div>ok</div>'), api: 'api' }];
+    const css = 'body{}';
+    const chunks = [{ fileName: 'chunk.js', code: 'console.log(1)' }];
+
+    const stubProcess = async () => ({ results, css, chunks });
+
+    const out = await webGen.generate([], {
+      output: tmp,
+      version: { version: '1.2.3' },
+      overrides: { processJSXEntries: stubProcess },
+    });
+
+    // returns results as strings + css
+    assert.equal(out.length, 1);
+    const htmlPath = join(tmp, 'api.html');
+    const written = await readFile(htmlPath, 'utf-8');
+    assert.ok(written.includes('<div>ok</div>'));
+
+    const chunkPath = join(tmp, 'chunk.js');
+    const chunkContent = await readFile(chunkPath, 'utf-8');
+    assert.equal(chunkContent, 'console.log(1)');
+
+    const cssPath = join(tmp, 'styles.css');
+    const cssContent = await readFile(cssPath, 'utf-8');
+    assert.equal(cssContent, css);
+  });
+});

src/generators/web/index.mjs

@@ -37,7 +37,7 @@ export default {
    * @param {Partial<GeneratorOptions>} options - Generator options.
    * @returns {Promise<Output>} Processed HTML/CSS/JS content.
    */
-  async generate(input, { output, version }) {
+  async generate(input, { output, version, overrides } = {}) {
     const template = await readFile(
       new URL('template.html', import.meta.url),
       'utf-8'
@@ -50,12 +50,14 @@ export default {
     const requireFn = createRequire(import.meta.url);
 
     // Process all entries: convert JSX to HTML/CSS/JS
-    const { results, css, chunks } = await processJSXEntries(
+    const processFn = overrides?.processJSXEntries || processJSXEntries;
+
+    const { results, css, chunks } = await processFn(
       input,
       template,
       astBuilders,
       requireFn,
-      { version }
+      { version, overrides }
     );
 
     // Process all entries together (required for code-split bundles)

src/generators/web/utils/__tests__/bundle.test.mjs

@@ -0,0 +1,25 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+describe('generators/web/utils - bundle', () => {
+  it('bundleCode separates assets and chunks and returns expected shape', async () => {
+    const bundleCode = (await import('../bundle.mjs')).default;
+
+    const codeMap = new Map([['a.js', 'export default 1;']]);
+
+    const result = await bundleCode(codeMap, { server: false });
+
+    // Basic shape assertions to keep this test hermetic without module mocking
+    assert.equal(typeof result.css, 'string');
+    assert.ok(Array.isArray(result.chunks));
+    assert.equal(
+      typeof result.importMap === 'string' || result.importMap === undefined,
+      true
+    );
+    assert.ok(
+      result.chunks.every(
+        c => typeof c.fileName === 'string' && 'code' in c && 'isEntry' in c
+      )
+    );
+  });
+});

src/generators/web/utils/__tests__/chunks.test.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { createChunkedRequire } from '../chunks.mjs';
+
+describe('generators/web/utils - chunks', () => {
+  it('createChunkedRequire resolves virtual chunks and falls back to require', () => {
+    const chunks = [
+      { fileName: 'a.js', code: 'module.exports = { val: 1 };' },
+      {
+        fileName: 'b.js',
+        code: 'const a = require("./a.js"); module.exports = { val: a.val + 1 };',
+      },
+    ];
+
+    const fakeRequire = path => {
+      if (path === 'fs') {
+        return { read: true };
+      }
+      return null;
+    };
+
+    const req = createChunkedRequire(chunks, fakeRequire);
+
+    // resolve virtual module
+    const a = req('./a.js');
+    assert.deepEqual(a, { val: 1 });
+
+    // module that requires another virtual module
+    const b = req('./b.js');
+    assert.deepEqual(b, { val: 2 });
+
+    // fallback to external
+    const ext = req('fs');
+    assert.deepEqual(ext, { read: true });
+  });
+});

src/generators/web/utils/__tests__/css.test.mjs

@@ -0,0 +1,52 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import cssPlugin from '../css.mjs';
+
+describe('generators/web/utils - css', () => {
+  it('css plugin buildEnd is a no-op when no chunks processed', () => {
+    const plugin = cssPlugin();
+
+    let emitted = null;
+    const thisArg = { emitFile: info => (emitted = info) };
+
+    // Should not throw and should not emit anything
+    plugin.buildEnd.call(thisArg);
+    assert.equal(emitted, null);
+  });
+
+  it('css plugin processes .module.css files and emits styles.css asset', async () => {
+    const plugin = cssPlugin();
+
+    // create temp .module.css file
+    const { writeFile, unlink } = await import('node:fs/promises');
+    const { tmpdir } = await import('node:os');
+    const { join } = await import('node:path');
+
+    const id = join(
+      tmpdir(),
+      `doc-kit-test-${Date.now()}-${Math.random()}.module.css`
+    );
+    await writeFile(id, '.btn { color: red; }', 'utf8');
+
+    // Call the handler to process the css file
+    const { handler } = plugin.load;
+    const result = await handler(id);
+
+    // Should return a JS module exporting the mapped class names
+    assert.match(result.code, /export default/);
+    assert.match(result.code, /"btn"/);
+
+    // buildEnd should emit a styles.css asset containing the compiled CSS
+    let emitted = null;
+    const thisArg = { emitFile: info => (emitted = info) };
+    plugin.buildEnd.call(thisArg);
+
+    assert.ok(emitted, 'expected styles.css to be emitted');
+    assert.equal(emitted.name, 'styles.css');
+    assert.match(String(emitted.source), /color:\s*red/);
+
+    // cleanup
+    await unlink(id);
+  });
+});

src/generators/web/utils/__tests__/generate.test.mjs

@@ -0,0 +1,37 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import createBuilders, { createImportDeclaration } from '../generate.mjs';
+
+describe('generators/web/utils - generate', () => {
+  it('createImportDeclaration produces correct import strings', () => {
+    // side-effect import
+    assert.equal(
+      createImportDeclaration(null, './style.css'),
+      'import "./style.css";'
+    );
+
+    // default import
+    assert.equal(
+      createImportDeclaration('X', './mod'),
+      'import X from "./mod";'
+    );
+
+    // named import
+    assert.equal(
+      createImportDeclaration('Y', './mod', false),
+      'import { Y } from "./mod";'
+    );
+  });
+
+  it('builders produce client and server programs containing expected markers', () => {
+    const { buildClientProgram, buildServerProgram } = createBuilders();
+
+    const client = buildClientProgram('MyComp()');
+    assert.match(client, /hydrate\(MyComp\(\)/);
+    assert.match(client, /index\.css/);
+
+    const server = buildServerProgram('MyComp()');
+    assert.match(server, /return render\(MyComp\(\)\);/);
+  });
+});

src/generators/web/utils/__tests__/processing-injectable.test.mjs

@@ -0,0 +1,81 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+
+import { executeServerCode, processWithCodeMaps } from '../processing.mjs';
+
+describe('generators/web/utils - processing (injectable)', () => {
+  it('executeServerCode accepts injected bundler and chunked require', async () => {
+    const serverCodeMap = new Map([[`api.jsx`, 'ignored']]);
+
+    const fakeRequire = () => ({ fs: true });
+
+    const mockBundle = async () => ({
+      chunks: [
+        { fileName: 'api.js', isEntry: true, code: 'return "<p>ok</p>";' },
+      ],
+      css: 'body{}',
+    });
+
+    const { pages, css } = await executeServerCode(serverCodeMap, fakeRequire, {
+      bundleCode: mockBundle,
+      createChunkedRequire: (chunks, req) => req,
+    });
+
+    assert.equal(pages.get('api.js'), '<p>ok</p>');
+    assert.equal(css, 'body{}');
+  });
+
+  it('processWithCodeMaps builds final HTML and css using injected bundlers', async () => {
+    const serverCodeMap = new Map([[`api.jsx`, 'ignored']]);
+    const clientCodeMap = new Map([[`api.jsx`, 'ignored']]);
+
+    const entries = [
+      { data: { api: 'api', heading: { data: { name: 'My API' } } } },
+    ];
+
+    const template =
+      '<title>{{title}}</title>{{dehydrated}}{{importMap}}{{entrypoint}}{{speculationRules}}';
+
+    const fakeRequire = () => ({ fs: true });
+
+    const mockServerBundle = async () => ({
+      chunks: [
+        {
+          fileName: 'api.js',
+          isEntry: true,
+          code: 'return "<div>server</div>";',
+        },
+      ],
+      css: 's{}',
+    });
+
+    const mockClientBundle = async () => ({
+      chunks: [{ fileName: 'api.js', isEntry: true, code: '/* client */' }],
+      css: 'c{}',
+      importMap: '{}',
+    });
+
+    const { results, css } = await processWithCodeMaps(
+      serverCodeMap,
+      clientCodeMap,
+      entries,
+      template,
+      fakeRequire,
+      { version: { version: '1.0.0' } },
+      {
+        bundleCode: async map =>
+          map === serverCodeMap
+            ? await mockServerBundle()
+            : await mockClientBundle(),
+        createChunkedRequire: (chunks, req) => req,
+        transform: ({ code }) => ({ code: Buffer.from(String(code)) }),
+      }
+    );
+
+    assert.equal(results.length, 1);
+    const html = results[0].html.toString();
+    assert.match(html, /<div>server<\/div>/);
+    assert.match(html, /My API/);
+    assert.ok(String(css).includes('s{}') || String(css).includes('c{}'));
+  });
+});