docpensieve 0.1.0

package/src/theme.js

@@ -0,0 +1,60 @@
+/**
+ * Builds the theme engine from the configuration.
+ *
+ * @module docpensieve/theme
+ */
+
+import { setThemeClasses } from '@docpensieve/components';
+import { ConfigError, THEME_FRAMEWORKS } from '@docpensieve/shared';
+import { CustomProvider, TailwindProvider, ThemeEngine } from '@docpensieve/theme';
+
+/**
+ * Mounts the ThemeEngine matching the declared framework.
+ *
+ * The CLI does this wiring: `core` deliberately ignores the `theme` package
+ * and receives the engine by injection (ADR-002).
+ *
+ * Along the way, the class table is handed to the components: that is what
+ * lets them ask for their class instead of hard-coding it (ADR-007).
+ *
+ * @param {Record<string, any>} config Normalised configuration.
+ * @param {string} [extraCss] CSS appended after the theme's — the look of the
+ *   components, which the caller has read.
+ * @returns {ThemeEngine}
+ * @throws {ConfigError} For a framework the project does not know.
+ */
+export function createTheme(config, extraCss = '') {
+  const theme = config.theme ?? {};
+  const framework = theme.framework ?? 'tailwind';
+
+  // Components first, project CSS second: the latter must be able to correct
+  // them.
+  const options = {
+    tokens: theme.tokens,
+    css: [extraCss, theme.css].filter(Boolean).join('\n\n'),
+  };
+
+  /** @param {ThemeEngine} engine */
+  const mount = (engine) => {
+    setThemeClasses(engine.classes);
+    return engine;
+  };
+
+  if (framework === 'custom') {
+    return mount(new ThemeEngine().register('custom', new CustomProvider(options)));
+  }
+  if (framework === 'tailwind') {
+    return mount(
+      new ThemeEngine().register(
+        'tailwind',
+        new TailwindProvider({ ...options, source: theme.source }),
+      ),
+    );
+  }
+
+  // The announced frameworks are all written: getting here means a faulty
+  // configuration, not an upcoming milestone.
+  throw new ConfigError(`Unknown theme framework: "${framework}".`, {
+    hint: `Accepted values: ${THEME_FRAMEWORKS.join(', ')}.`,
+  });
+}

package/types/commands/build.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `docpensieve build` command.
+ *
+ * @module docpensieve/commands/build
+ */
+/**
+ * @param {string | undefined} versionSlug Version to generate, or all of them when omitted.
+ * @param {{ out?: string, cwd?: string }} [options]
+ * @returns {Promise<void>}
+ */
+export declare function build(versionSlug: string | undefined, options?: {
+    out?: string;
+    cwd?: string;
+}): Promise<void>;

package/types/commands/check.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `docpensieve check` command — reads the produced site back.
+ *
+ * A successful build says nothing of a dead link or of invalid markup:
+ * nothing in the chain looks at them, and they only show when opening the
+ * pages one by one. This command does that reading.
+ *
+ * @module docpensieve/commands/check
+ */
+export type Fault = {
+    /**
+     * Page path, relative to the checked root.
+     */
+    page: string;
+    /**
+     * What is at stake — a target, a tag.
+     */
+    subject: string;
+    /**
+     * What is wrong.
+     */
+    reason: string;
+};
+export type Page = {
+    /**
+     * Path relative to the checked root.
+     */
+    relative: string;
+    /**
+     * File contents.
+     */
+    html: string;
+};
+/**
+ * Checks the internal links of a generated site.
+ *
+ * Exported apart from the command: it reads no configuration and addresses no
+ * one, which makes it usable elsewhere and testable on its own.
+ *
+ * @param {string} root      Folder of the produced site.
+ * @param {string} [baseUrl] Deployment prefix, slashes included.
+ * @returns {Promise<{ pages: number, faults: Fault[] }>}
+ */
+export declare function verifyLinks(root: string, baseUrl?: string): Promise<{
+    pages: number;
+    faults: Fault[];
+}>;
+/**
+ * Checks the markup of a generated site.
+ *
+ * @param {string} root Folder of the produced site.
+ * @returns {Promise<{ pages: number, faults: Fault[] }>}
+ */
+export declare function verifyMarkup(root: string): Promise<{
+    pages: number;
+    faults: Fault[];
+}>;
+/**
+ * Reads the produced site back and reports what is wrong.
+ *
+ * @param {{ dir?: string, cwd?: string }} [options]
+ * @returns {Promise<{ root: string, pages: number, faults: Fault[] }>}
+ * @throws {DocPensieveError} When the folder does not exist, or when something
+ *   is left to fix — the exit code is then that of an expected error, which is
+ *   enough to fail a continuous integration run.
+ */
+export declare function check(options?: {
+    dir?: string;
+    cwd?: string;
+}): Promise<{
+    root: string;
+    pages: number;
+    faults: Fault[];
+}>;

package/types/commands/dev.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `docpensieve dev` command — build, watch and reload.
+ *
+ * @module docpensieve/commands/dev
+ */
+/**
+ * @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 declare function dev(options?: {
+    port?: number;
+    cwd?: string;
+}): Promise<{
+    server: import('node:http').Server;
+    watcher: import('chokidar').FSWatcher;
+    port: number;
+    url: string;
+    close: () => Promise<void>;
+}>;

package/types/commands/init.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `docpensieve init` command — sets up a documentation project.
+ *
+ * @module docpensieve/commands/init
+ */
+/**
+ * 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 declare function init(dir?: string, options?: {
+    name?: string;
+    theme?: string;
+    siteUrl?: string;
+    version?: string;
+    yes?: boolean;
+    force?: boolean;
+}): Promise<{
+    dir: string;
+    theme: string;
+}>;

package/types/commands/serve.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `docpensieve serve` command — serves the output folder statically.
+ *
+ * @module docpensieve/commands/serve
+ */
+/**
+ * @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 declare function serve(options?: {
+    port?: number;
+    dir?: string;
+    cwd?: string;
+}): Promise<{
+    server: import('node:http').Server;
+    port: number;
+    url: string;
+}>;

package/types/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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/types/server.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Static HTTP server shared by the `serve` and `dev` commands.
+ *
+ * @module docpensieve/server
+ */
+/** Path reserved for the reload stream of the development server. */
+export declare 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 declare function resolveRequestPath(pathname: string, root: string): string | null;
+/**
+ * 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 declare function createStaticServer({ root, basePath, inject, onReload }: {
+    root: string;
+    basePath?: string;
+    inject?: string | null;
+    onReload?: (send: () => void) => void;
+}): import('node:http').Server;
+/**
+ * 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 declare function listen(server: import('node:http').Server, port: number, attempts?: number): Promise<number>;

package/types/theme.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Builds the theme engine from the configuration.
+ *
+ * @module docpensieve/theme
+ */
+import { ThemeEngine } from '@docpensieve/theme';
+/**
+ * Mounts the ThemeEngine matching the declared framework.
+ *
+ * The CLI does this wiring: `core` deliberately ignores the `theme` package
+ * and receives the engine by injection (ADR-002).
+ *
+ * Along the way, the class table is handed to the components: that is what
+ * lets them ask for their class instead of hard-coding it (ADR-007).
+ *
+ * @param {Record<string, any>} config Normalised configuration.
+ * @param {string} [extraCss] CSS appended after the theme's — the look of the
+ *   components, which the caller has read.
+ * @returns {ThemeEngine}
+ * @throws {ConfigError} For a framework the project does not know.
+ */
+export declare function createTheme(config: Record<string, any>, extraCss?: string): ThemeEngine;