docpensieve 0.1.0

package/src/commands/dev.js

@@ -0,0 +1,132 @@
+/**
+ * `docpensieve dev` command — build, watch and reload.
+ *
+ * @module docpensieve/commands/dev
+ */
+
+import path from 'node:path';
+
+import { componentsCss, createRegistry, setSiteContext } from '@docpensieve/components';
+import { SiteGenerator, loadConfig } from '@docpensieve/core';
+import { CONFIG_FILENAME, DocPensieveError } from '@docpensieve/shared';
+import chokidar from 'chokidar';
+
+import { RELOAD_PATH, createStaticServer, listen } from '../server.js';
+import { createTheme } from '../theme.js';
+
+/** Default port of `dev`, distinct from that of `serve`. */
+const DEFAULT_PORT = 3000;
+
+/** Delay for grouping file events, in milliseconds. */
+const DEBOUNCE = 120;
+
+/**
+ * Reload script injected on the fly, never written to disk.
+ *
+ * The injection happens when serving the page, not when generating it: the
+ * output of `build` stays free of any JavaScript, as the project requires.
+ */
+const RELOAD_SCRIPT =
+  `<script>new EventSource(${JSON.stringify(RELOAD_PATH)})` +
+  `.addEventListener("message",()=>location.reload())</script>`;
+
+/**
+ * @param {{ port?: number, cwd?: string }} [options]
+ * @returns {Promise<{
+ *   server: import('node:http').Server,
+ *   watcher: import('chokidar').FSWatcher,
+ *   port: number,
+ *   url: string,
+ *   close: () => Promise<void>,
+ * }>}
+ */
+export async function dev(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const config = await loadConfig(cwd);
+  const outDir = path.resolve(cwd, config.outDir);
+
+  const rebuild = async () => {
+    const started = Date.now();
+    // The configuration is read again every time: changing it must show
+    // without restarting the command.
+    const current = await loadConfig(cwd);
+    const generator = new SiteGenerator(current, {
+      // `globalComponents: false` removes the shipped components: a project
+      // that defines its own thus avoids a name collision. The option was
+      // declared and documented, but nobody read it.
+      components: current.globalComponents === false ? {} : createRegistry(),
+      onPage: setSiteContext,
+      theme: createTheme(current, await componentsCss()),
+    });
+    const result = await generator.buildAll();
+    console.log(`${result.pages} page(s) in ${Date.now() - started} ms`);
+  };
+
+  await rebuild();
+
+  /** @type {() => void} */
+  let notify = () => {};
+  const server = createStaticServer({
+    root: outDir,
+    basePath: config.baseUrl,
+    inject: RELOAD_SCRIPT,
+    onReload: (send) => {
+      notify = send;
+    },
+  });
+
+  const port = await listen(server, options.port ?? DEFAULT_PORT);
+  const url = `http://localhost:${port}${config.baseUrl}`;
+  console.log(`served at ${url}`);
+
+  const watched = [
+    path.resolve(cwd, CONFIG_FILENAME),
+    ...config.versions.map((version) => path.resolve(cwd, version.folder)),
+  ];
+  const watcher = chokidar.watch(watched, { ignoreInitial: true });
+
+  // Until chokidar has finished its inventory, `ignoreInitial` swallows the
+  // events: a change made in the second after startup went unnoticed. Control
+  // is only handed back once watching is active.
+  await new Promise((resolve) => watcher.once('ready', () => resolve(undefined)));
+
+  /** @type {NodeJS.Timeout | undefined} */
+  let pending;
+  watcher.on('all', (_event, changed) => {
+    // An editor emits several events per save: group them.
+    clearTimeout(pending);
+    pending = setTimeout(async () => {
+      console.log(`\n${path.relative(cwd, changed)} changed`);
+      try {
+        await rebuild();
+        notify();
+      } catch (error) {
+        // A content error must not kill the watch: print it and wait for the
+        // fix.
+        if (error instanceof DocPensieveError) {
+          console.error(error.message);
+          if (error.hint) console.error(error.hint);
+        } else {
+          console.error(error);
+        }
+      }
+    }, DEBOUNCE);
+  });
+
+  console.log('watching — Ctrl+C to stop');
+
+  return {
+    server,
+    watcher,
+    port,
+    url,
+    close: async () => {
+      clearTimeout(pending);
+      await watcher.close();
+      // Without this, close() waits for keep-alive connections to expire —
+      // the reload stream keeps one open permanently.
+      server.closeAllConnections();
+      await new Promise((resolve) => server.close(resolve));
+    },
+  };
+}

package/src/commands/init.js

@@ -0,0 +1,298 @@
+/**
+ * `docpensieve init` command — sets up a documentation project.
+ *
+ * @module docpensieve/commands/init
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+
+import { CONFIG_FILENAME, DocPensieveError, THEME_FRAMEWORKS } from '@docpensieve/shared';
+
+/**
+ * Description shown next to each framework.
+ * @type {Record<string, string>}
+ */
+const FRAMEWORK_LABELS = {
+  tailwind: 'Tailwind CSS — ships with the tool, nothing to install',
+  custom: 'custom theme, light stylesheet, no utilities',
+};
+
+/** Answers used when there is no dialogue. */
+const DEFAULTS = { name: 'My documentation', siteUrl: '', theme: 'tailwind', version: '1.0' };
+
+/**
+ * Asks a question, with a default value shown between brackets.
+ *
+ * @param {import('node:readline/promises').Interface} rl
+ * @param {string} question
+ * @param {string} fallback
+ * @returns {Promise<string>}
+ */
+async function ask(rl, question, fallback) {
+  const suffix = fallback ? ` [${fallback}]` : '';
+  const answer = (await rl.question(`${question}${suffix}: `)).trim();
+  return answer || fallback;
+}
+
+/**
+ * Asks for the CSS framework among those the configuration accepts.
+ *
+ * @param {import('node:readline/promises').Interface} rl
+ * @returns {Promise<string>}
+ */
+async function askFramework(rl) {
+  console.log('\nCSS framework:');
+  THEME_FRAMEWORKS.forEach((framework, index) => {
+    console.log(`  ${index + 1}. ${framework} — ${FRAMEWORK_LABELS[framework] ?? ''}`);
+  });
+
+  for (;;) {
+    const answer = (await rl.question(`Your choice [1-${THEME_FRAMEWORKS.length}]: `)).trim();
+    if (answer === '') return THEME_FRAMEWORKS[0];
+
+    // Accept the number as well as the name: typing “tailwind” is more natural
+    // than counting lines.
+    const byName = THEME_FRAMEWORKS.find((framework) => framework === answer.toLowerCase());
+    if (byName) return byName;
+
+    const index = Number(answer);
+    if (Number.isInteger(index) && index >= 1 && index <= THEME_FRAMEWORKS.length) {
+      return THEME_FRAMEWORKS[index - 1];
+    }
+    console.log(`Answer not understood. Expected: a number, or ${THEME_FRAMEWORKS.join(', ')}.`);
+  }
+}
+
+/**
+ * Gathers the answers, through a dialogue or from the options.
+ *
+ * @param {{ name?: string, theme?: string, siteUrl?: string, version?: string, yes?: boolean }} options
+ * @returns {Promise<{ name: string, theme: string, siteUrl: string, version: string }>}
+ */
+async function collect(options) {
+  const fromOptions = {
+    name: options.name ?? DEFAULTS.name,
+    siteUrl: options.siteUrl ?? DEFAULTS.siteUrl,
+    theme: options.theme ?? DEFAULTS.theme,
+    version: options.version ?? DEFAULTS.version,
+  };
+
+  // Without a terminal — script, CI, pipe — the dialogue would never complete:
+  // stick to the options and the defaults.
+  if (options.yes || !process.stdin.isTTY) return fromOptions;
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const name = await ask(rl, 'Project name', fromOptions.name);
+    const siteUrl = await ask(rl, 'Public URL of the site (optional)', fromOptions.siteUrl);
+    const version = await ask(rl, 'First version', fromOptions.version);
+    const theme = options.theme ?? (await askFramework(rl));
+    return { name, siteUrl, version, theme };
+  } finally {
+    rl.close();
+  }
+}
+
+/**
+ * Quotes a string in the project's style.
+ *
+ * `JSON.stringify` would produce double quotes, against the grain of the rest
+ * of the generated file — the one the user opens first.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+const quote = (value) => `'${String(value).replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+
+/**
+ * @param {{ name: string, theme: string, siteUrl: string, version: string }} answers
+ * @returns {string} Contents of `docpensieve.config.js`.
+ */
+function renderConfig({ name, theme, siteUrl, version }) {
+  const slug = versionSlug(version);
+  // A type annotation rather than an `import`: `defineConfig` transforms
+  // nothing, it is only there for autocompletion. Actually importing it would
+  // make the configuration unreadable in a folder where the package is not
+  // installed — that is, at the first `build` after an `npx`. A JSDoc
+  // `import()` type disappears at run time.
+  const lines = [
+    "/** @type {import('@docpensieve/core').DocPensieveConfig} */",
+    'export default {',
+    `  projectName: ${quote(name)},`,
+  ];
+
+  if (siteUrl) {
+    lines.push(
+      `  siteUrl: ${quote(siteUrl)},`,
+      '  // baseUrl is derived from the path of siteUrl. Set it to force it.',
+    );
+  }
+
+  lines.push(
+    '',
+    '  // One entry per version. The compiled output then goes to an orphan',
+    '  // branch with the same slug.',
+    '  versions: [',
+    `    {`,
+    `      slug: ${quote(slug)},`,
+    `      name: ${quote(version)},`,
+    `      folder: ${quote(`docs/${slug}`)},`,
+    `      current: true,`,
+    `    },`,
+    '  ],',
+    '',
+    "  outDir: 'dist',",
+    '',
+    '  theme: {',
+    `    framework: ${quote(theme)},`,
+    "    darkMode: 'class',",
+    "    // Override the palette: tokens: { '--dp-accent': '#008060' },",
+    '  },',
+    '',
+    "  // 'auto': the sidebar follows the file tree and the 01-, 02- prefixes.",
+    "  sidebar: 'auto',",
+    '',
+    '  globalComponents: true,',
+    '  jsonld: { enabled: true },',
+    '};',
+    '',
+  );
+
+  return lines.join('\n');
+}
+
+/**
+ * Slug of a version, as it names both the folder and the branch.
+ *
+ * A “v” is added when the user left it out: “1.0” and “v1.0” must give the
+ * same project.
+ *
+ * @param {string} version
+ * @returns {string}
+ */
+function versionSlug(version) {
+  const trimmed = String(version).trim();
+  return /^v/i.test(trimmed) ? trimmed : `v${trimmed}`;
+}
+
+/**
+ * @param {string} name Project name, for the title of the home page.
+ * @returns {string}
+ */
+const renderIndex = (name) => `---
+title: Introduction
+description: Documentation of ${name}.
+date: ${new Date().toISOString().slice(0, 10)}
+
+jsonld:
+  type: TechArticle
+  breadcrumbs: true
+---
+
+# ${name}
+
+Welcome to the documentation.
+
+## Getting started
+
+Pages live in \`docs/\`. The \`01-\` prefix of a file orders the menu
+without appearing in the URL.
+
+See the [installation guide](/guide/installation/).
+`;
+
+/** @returns {string} Sample page, showing ordering and highlighting. */
+const renderGuide = () => `---
+title: Installation
+description: Install and run the project.
+
+jsonld:
+  type: TechArticle
+---
+
+# Installation
+
+## Requirements
+
+Node.js 22 or later.
+
+## Run
+
+\`\`\`bash
+npm install
+npm run dev
+\`\`\`
+`;
+
+/**
+ * Sets up a documentation project.
+ *
+ * @param {string} [dir] Target folder, created if needed.
+ * @param {{
+ *   name?: string, theme?: string, siteUrl?: string, version?: string,
+ *   yes?: boolean, force?: boolean,
+ * }} [options]
+ * @returns {Promise<{ dir: string, theme: string }>}
+ * @throws {DocPensieveError} Unknown framework, or project already initialised.
+ */
+export async function init(dir = '.', options = {}) {
+  const target = path.resolve(dir);
+  const configPath = path.join(target, CONFIG_FILENAME);
+
+  if (existsSync(configPath) && !options.force) {
+    throw new DocPensieveError(`${CONFIG_FILENAME} already exists in ${target}.`, {
+      hint: 'Use --force to overwrite it, or pick another folder.',
+    });
+  }
+
+  // Before the dialogue: answering three questions only to be told afterwards
+  // that the theme does not exist would be annoying. After it, the check would
+  // be pointless — the dialogue only offers valid values.
+  if (options.theme && !THEME_FRAMEWORKS.includes(options.theme)) {
+    throw new DocPensieveError(`Unknown framework: "${options.theme}".`, {
+      hint: `Accepted values: ${THEME_FRAMEWORKS.join(', ')}.`,
+    });
+  }
+
+  const answers = await collect(options);
+
+  const slug = versionSlug(answers.version);
+  const docsDir = path.join(target, 'docs', slug);
+
+  await mkdir(path.join(docsDir, 'guide'), { recursive: true });
+  await writeFile(configPath, renderConfig(answers), 'utf8');
+  await writeFile(path.join(docsDir, 'index.md'), renderIndex(answers.name), 'utf8');
+  await writeFile(path.join(docsDir, 'guide', '01-installation.md'), renderGuide(), 'utf8');
+  await ignoreOutput(target);
+
+  console.log(`\nProject initialised in ${target}`);
+  console.log(`  ${CONFIG_FILENAME}`);
+  console.log(`  docs/${slug}/index.md`);
+  console.log(`  docs/${slug}/guide/01-installation.md`);
+  console.log(`\nTheme: ${answers.theme} — ${FRAMEWORK_LABELS[answers.theme]}`);
+  console.log('\nNext:  npx docpensieve dev');
+
+  return { dir: target, theme: answers.theme };
+}
+
+/**
+ * Adds the output folder to .gitignore, without overwriting what is there.
+ *
+ * @param {string} target
+ */
+async function ignoreOutput(target) {
+  const file = path.join(target, '.gitignore');
+  let current = '';
+  try {
+    current = await readFile(file, 'utf8');
+  } catch {
+    // No .gitignore: create it.
+  }
+
+  if (/^dist\/?$/m.test(current)) return;
+  const separator = current && !current.endsWith('\n') ? '\n' : '';
+  await writeFile(file, `${current}${separator}dist/\nnode_modules/\n`, 'utf8');
+}

package/src/commands/serve.js

@@ -0,0 +1,44 @@
+/**
+ * `docpensieve serve` command — serves the output folder statically.
+ *
+ * @module docpensieve/commands/serve
+ */
+
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+
+import { loadConfig } from '@docpensieve/core';
+import { DocPensieveError } from '@docpensieve/shared';
+
+import { createStaticServer, listen } from '../server.js';
+
+/** Default port of `serve`, distinct from that of `dev`. */
+const DEFAULT_PORT = 4000;
+
+/**
+ * @param {{ port?: number, dir?: string, cwd?: string }} [options]
+ * @returns {Promise<{ server: import('node:http').Server, port: number, url: string }>}
+ * @throws {DocPensieveError} When the folder to serve does not exist.
+ */
+export async function serve(options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const config = await loadConfig(cwd);
+  const root = path.resolve(cwd, options.dir ?? config.outDir);
+
+  if (!existsSync(root)) {
+    throw new DocPensieveError(`Nothing to serve: ${root} does not exist.`, {
+      hint: 'Run "docpensieve build" before "serve".',
+    });
+  }
+
+  // The site is mounted under the configuration's baseUrl: otherwise the links
+  // of the generated pages would not resolve locally.
+  const server = createStaticServer({ root, basePath: config.baseUrl });
+  const port = await listen(server, options.port ?? DEFAULT_PORT);
+  const url = `http://localhost:${port}${config.baseUrl}`;
+
+  console.log(`${root}`);
+  console.log(`served at ${url}`);
+
+  return { server, port, url };
+}

package/src/index.js

@@ -0,0 +1,15 @@
+/**
+ * docpensieve — implementations of the commands.
+ *
+ * The binary (`bin/docpensieve.js`) only parses arguments: the logic lives
+ * here, to stay testable without spawning a subprocess.
+ *
+ * @module docpensieve
+ */
+
+export { build } from './commands/build.js';
+export { check, verifyLinks, verifyMarkup } from './commands/check.js';
+export { dev } from './commands/dev.js';
+export { init } from './commands/init.js';
+export { serve } from './commands/serve.js';
+export { createStaticServer, listen, resolveRequestPath } from './server.js';

package/src/server.js

@@ -0,0 +1,207 @@
+/**
+ * Static HTTP server shared by the `serve` and `dev` commands.
+ *
+ * @module docpensieve/server
+ */
+
+import { createReadStream } from 'node:fs';
+import { stat } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import path from 'node:path';
+
+import { DocPensieveError } from '@docpensieve/shared';
+
+/**
+ * MIME types of the files a documentation site produces.
+ * @type {Record<string, string>}
+ */
+const MIME_TYPES = {
+  '.html': 'text/html; charset=utf-8',
+  '.css': 'text/css; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json; charset=utf-8',
+  '.svg': 'image/svg+xml',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.avif': 'image/avif',
+  '.ico': 'image/x-icon',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.pdf': 'application/pdf',
+  '.txt': 'text/plain; charset=utf-8',
+  '.md': 'text/plain; charset=utf-8',
+  '.xml': 'application/xml; charset=utf-8',
+};
+
+/** Path reserved for the reload stream of the development server. */
+export const RELOAD_PATH = '/__docpensieve/reload';
+
+/**
+ * Resolves a request URL into a file path, without leaving the root.
+ *
+ * @param {string} pathname Request path, `basePath` already removed.
+ * @param {string} root Served folder.
+ * @returns {string | null} Absolute path, or `null` when the target escapes `root`.
+ */
+export function resolveRequestPath(pathname, root) {
+  let decoded;
+  try {
+    decoded = decodeURIComponent(pathname);
+  } catch {
+    // Invalid escape sequence: the request designates nothing.
+    return null;
+  }
+
+  // A folder is served by its index page, like on any static host. A path
+  // without an extension is treated the same way.
+  const relative = decoded.replace(/^\/+/, '');
+  const candidate =
+    decoded.endsWith('/') || path.extname(relative) === ''
+      ? path.join(relative, 'index.html')
+      : relative;
+
+  const resolved = path.resolve(root, candidate);
+
+  // path.resolve absorbs the "..": check afterwards that the target is indeed
+  // under the root, otherwise a "/../../etc/passwd" request would get out.
+  const relativeToRoot = path.relative(root, resolved);
+  if (relativeToRoot.startsWith('..') || path.isAbsolute(relativeToRoot)) return null;
+
+  return resolved;
+}
+
+/**
+ * Creates a static file server.
+ *
+ * @param {{
+ *   root: string,
+ *   basePath?: string,
+ *   inject?: string | null,
+ *   onReload?: (send: () => void) => void,
+ * }} options
+ *   `basePath` is the prefix under which the site is mounted: it must reflect
+ *   the configuration's `baseUrl`, otherwise the links of the pages do not
+ *   resolve locally. `inject` is an HTML fragment inserted before `</body>` —
+ *   the development server uses it for its reload script, which leaves the
+ *   generated output intact.
+ * @returns {import('node:http').Server}
+ */
+export function createStaticServer({ root, basePath = '/', inject = null, onReload }) {
+  /** @type {Set<import('node:http').ServerResponse>} */
+  const listeners = new Set();
+
+  if (onReload) {
+    onReload(() => {
+      for (const client of listeners) client.write('data: reload\n\n');
+    });
+  }
+
+  return createServer(async (request, response) => {
+    // `request.url` is optional in Node's signature: a malformed request must
+    // not make `new URL` throw.
+    const url = new URL(request.url ?? '/', 'http://localhost');
+
+    if (onReload && url.pathname === RELOAD_PATH) {
+      response.writeHead(200, {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache',
+        connection: 'keep-alive',
+      });
+      response.write('\n');
+      listeners.add(response);
+      request.on('close', () => listeners.delete(response));
+      return;
+    }
+
+    // The site is mounted under basePath: outside that prefix, redirect there
+    // rather than answer 404 on the root, which is the URL one types first.
+    if (basePath !== '/' && !url.pathname.startsWith(basePath)) {
+      response.writeHead(302, { location: basePath });
+      response.end();
+      return;
+    }
+
+    const pathname = basePath === '/' ? url.pathname : url.pathname.slice(basePath.length - 1);
+    const filepath = resolveRequestPath(pathname, root);
+
+    if (!filepath) {
+      response.writeHead(403, { 'content-type': 'text/plain; charset=utf-8' });
+      response.end('403 — path outside the served folder.');
+      return;
+    }
+
+    let stats;
+    try {
+      stats = await stat(filepath);
+    } catch {
+      response.writeHead(404, { 'content-type': 'text/plain; charset=utf-8' });
+      response.end(`404 — ${url.pathname}`);
+      return;
+    }
+
+    const type = MIME_TYPES[path.extname(filepath).toLowerCase()] ?? 'application/octet-stream';
+    const headers = { 'content-type': type, 'cache-control': 'no-cache' };
+
+    if (inject && type.startsWith('text/html')) {
+      const { readFile } = await import('node:fs/promises');
+      const html = await readFile(filepath, 'utf8');
+      const body = html.includes('</body>')
+        ? html.replace('</body>', `${inject}</body>`)
+        : html + inject;
+      response.writeHead(200, { ...headers, 'content-length': Buffer.byteLength(body) });
+      response.end(body);
+      return;
+    }
+
+    response.writeHead(200, { ...headers, 'content-length': stats.size });
+    createReadStream(filepath).pipe(response);
+  });
+}
+
+/**
+ * Starts listening, looking for a free port if needed.
+ *
+ * @param {import('node:http').Server} server
+ * @param {number} port Desired port.
+ * @param {number} [attempts] Number of ports tried from `port` on.
+ * @returns {Promise<number>} The port actually used.
+ * @throws {DocPensieveError} When no port is free in the range.
+ */
+export function listen(server, port, attempts = 10) {
+  return new Promise((resolve, reject) => {
+    let current = port;
+
+    /** @param {NodeJS.ErrnoException} error */
+    const onError = (error) => {
+      // A busy port is the common case when restarting a dev server: trying
+      // the next one beats forcing --port.
+      if (error.code === 'EADDRINUSE' && current < port + attempts - 1) {
+        current += 1;
+        server.listen(current);
+        return;
+      }
+      server.off('error', onError);
+      reject(
+        new DocPensieveError(`Could not listen on port ${port}.`, {
+          cause: error,
+          hint: `No free port between ${port} and ${port + attempts - 1}. Use --port.`,
+        }),
+      );
+    };
+
+    server.on('error', onError);
+    server.once('listening', () => {
+      server.off('error', onError);
+      // The effective port, not the requested one: with 0, the system assigns
+      // a free one and the caller needs to know which. `address()` returns
+      // `null` or a string for a pipe, a case that does not concern us.
+      const address = server.address();
+      resolve(typeof address === 'object' && address !== null ? address.port : current);
+    });
+    server.listen(current);
+  });
+}