@doc-kit/core 0.0.0

package/src/logger/logger.mjs

@@ -0,0 +1,177 @@
+'use strict';
+
+import { LogLevel } from './constants.mjs';
+
+/**
+ * @typedef {import('./types').Metadata} Metadata
+ * @typedef {import('./types').LogMessage} LogMessage
+ */
+
+/**
+ * Creates a logger instance with the specified transport, log level and an
+ * optional module name. Child loggers share the parent's log level.
+ *
+ * @param {import('./types').Transport} transport - Function to handle log output.
+ * @param {number} [loggerLevel] - Minimum log level to output.
+ * @param {string} [module] - Optional module name for the logger.
+ */
+export const createLogger = (
+  transport,
+  loggerLevel = LogLevel.info,
+  module
+) => {
+  /** @type {number} */
+  let currentLevel = loggerLevel;
+
+  /** @type {Set<ReturnType<typeof createLogger>>} */
+  const children = new Set();
+
+  /**
+   * Checks if the given log level should be logged based on the current logger
+   * level.
+   *
+   * @param {number} level - Log level to check.
+   * @returns {boolean}
+   */
+  const shouldLog = level => level >= currentLevel;
+
+  /**
+   * Logs a message at the given level with optional metadata.
+   *
+   * @param {number} level - Log level for the message.
+   * @param {LogMessage} message - Message to log.
+   * @param {Metadata} metadata - Additional metadata
+   * @returns {void}
+   */
+  const log = (level, message, metadata = {}) => {
+    if (!shouldLog(level)) {
+      return;
+    }
+
+    if (Array.isArray(message)) {
+      return message.forEach(msg => log(level, msg, metadata));
+    }
+
+    const timestamp = Date.now();
+
+    // Extract message string from Error object or use message as-is
+    let msg;
+
+    if (message instanceof Error) {
+      msg = message.message;
+
+      metadata.stack = message.stack;
+    } else {
+      msg = message;
+    }
+
+    transport({
+      level,
+      message: msg,
+      timestamp,
+      metadata,
+      module,
+    });
+  };
+
+  /**
+   * Logs an info message.
+   *
+   * @param {LogMessage} message - Info message to log.
+   * @param {Metadata} metadata - Additional metadata
+   * @returns {void}
+   */
+  const info = (message, metadata = {}) =>
+    log(LogLevel.info, message, metadata);
+
+  /**
+   * Logs a warning message.
+   *
+   * @param {LogMessage} message - Warning message to log.
+   * @param {Metadata} metadata - Additional metadata
+   * @returns {void}
+   */
+  const warn = (message, metadata = {}) =>
+    log(LogLevel.warn, message, metadata);
+
+  /**
+   * Logs an error message or Error object.
+   *
+   * @param {LogMessage} message - Error message or Error object to log.
+   * @param {Metadata} metadata - Additional metadata
+   * @returns {void}
+   */
+  const error = (message, metadata = {}) =>
+    log(LogLevel.error, message, metadata);
+
+  /**
+   * Logs a fatal error message or Error object.
+   *
+   * @param {LogMessage} message - Fatal error message or Error object to log.
+   * @param {Metadata} metadata - Additional metadata
+   * @returns {void}
+   */
+  const fatal = (message, metadata = {}) =>
+    log(LogLevel.fatal, message, metadata);
+
+  /**
+   * Logs a debug message.
+   *
+   * @param {LogMessage} message - Debug message to log.
+   * @param {Metadata} metadata - Additional metadata
+   * @returns {void}
+   */
+  const debug = (message, metadata = {}) =>
+    log(LogLevel.debug, message, metadata);
+
+  /**
+   * Creates a child logger for a specific module. Child loggers share the
+   * parent's log level.
+   *
+   * @param {string} childModule - Module name for the child logger.
+   * @returns {ReturnType<typeof createLogger>}
+   */
+  const child = childModule => {
+    const childLogger = createLogger(transport, currentLevel, childModule);
+
+    children.add(childLogger);
+
+    return childLogger;
+  };
+
+  /**
+   * Sets the log level for this logger instance and all child loggers.
+   *
+   * @param {number | string} level - Log level (number) or level name (string)
+   */
+  const setLogLevel = level => {
+    let newLogLevel = level;
+
+    if (typeof newLogLevel === 'string') {
+      newLogLevel = newLogLevel.toLowerCase();
+
+      if (newLogLevel in LogLevel === false) {
+        return;
+      }
+
+      newLogLevel = LogLevel[newLogLevel];
+    }
+
+    currentLevel = newLogLevel;
+
+    // Propagate to all child loggers
+    for (const childLogger of children) {
+      childLogger.setLogLevel(currentLevel);
+    }
+  };
+
+  return {
+    info,
+    warn,
+    error,
+    fatal,
+    debug,
+    child,
+    setLogLevel,
+  };
+};

package/src/logger/transports/console.mjs

@@ -0,0 +1,54 @@
+'use strict';
+
+import { styleText } from 'node:util';
+
+import { prettifyLevel } from '../utils/colors.mjs';
+import { prettifyTimestamp } from '../utils/time.mjs';
+
+/**
+ * Logs a formatted message to stdout for human-friendly CLI output.
+ *
+ * @param {import('../types').TransportContext} context
+ * @returns {void}
+ */
+const console = ({ level, message, timestamp, metadata = {}, module }) => {
+  const { file, stack, ...rest } = metadata;
+
+  const time = prettifyTimestamp(timestamp);
+
+  process.stdout.write(`[${time}]`);
+
+  const prettyLevel = prettifyLevel(level);
+
+  process.stdout.write(` ${prettyLevel}`);
+
+  if (module) {
+    process.stdout.write(` (${module})`);
+  }
+
+  process.stdout.write(`: ${message}`);
+
+  if (file) {
+    process.stdout.write(` at ${file.path}`);
+  }
+
+  if (file?.position) {
+    const position = `(${file.position.start.line}:${file.position.end.line})`;
+
+    process.stdout.write(position);
+  }
+
+  // Print remaining metadata inline in purple
+  if (Object.keys(rest).length > 0) {
+    const metaStr = styleText('magenta', JSON.stringify(rest));
+    process.stdout.write(` ${metaStr}`);
+  }
+
+  process.stdout.write('\n');
+
+  if (stack) {
+    process.stdout.write(stack);
+  }
+};
+
+export default console;

package/src/logger/transports/github.mjs

@@ -0,0 +1,42 @@
+'use strict';
+
+import { debug, notice, warning, error } from '@actions/core';
+
+import { LogLevel } from '../constants.mjs';
+import { prettifyLevel } from '../utils/colors.mjs';
+import { prettifyTimestamp } from '../utils/time.mjs';
+
+const actions = {
+  [LogLevel.debug]: debug,
+  [LogLevel.info]: notice,
+  [LogLevel.warn]: warning,
+  [LogLevel.error]: error,
+  [LogLevel.fatal]: error,
+};
+
+/**
+ * Logs messages to GitHub Actions with formatted output and file info with
+ * appropriate gh actions based on level.
+ *
+ * @param {import('../types').TransportContext} context
+ * @returns {void}
+ */
+const github = ({ level, message, timestamp, metadata = {}, module }) => {
+  const { file } = metadata;
+
+  const time = prettifyTimestamp(timestamp);
+
+  const prettyLevel = prettifyLevel(level);
+
+  const logMessage = `[${time}] ${prettyLevel}${module ? ` (${module})` : ''}: ${message}`;
+
+  const logFn = actions[level] ?? notice;
+
+  logFn(logMessage, {
+    file: file?.path,
+    startLine: file?.position?.start.line,
+    endLine: file?.position?.end.line,
+  });
+};
+
+export default github;

package/src/logger/transports/index.mjs

@@ -0,0 +1,11 @@
+'use strict';
+
+import console from './console.mjs';
+import github from './github.mjs';
+
+export const transports = {
+  console,
+  github,
+};
+
+export const availableTransports = Object.keys(transports);

package/src/logger/types.d.ts

@@ -0,0 +1,29 @@
+export type LogLevel = 'info' | 'warn' | 'error' | 'fatal' | 'trace' | 'debug';
+
+export type LogMessage = string | Error | string[];
+
+export interface Position {
+  start: { line: number };
+  end: { line: number };
+}
+
+export interface File {
+  path: string;
+  position?: Position;
+}
+
+interface Metadata {
+  file?: File;
+  // Stack trace if the message is an error
+  stack?: string;
+}
+
+interface TransportContext {
+  level: number;
+  message: string;
+  timestamp: number;
+  metadata?: Metadata;
+  module?: string;
+}
+
+export type Transport = (context: TransportContext) => void;

package/src/logger/utils/colors.mjs

@@ -0,0 +1,18 @@
+'use strict';
+
+import { styleText } from 'node:util';
+
+import { levelTags, levelToColorMap } from '../constants.mjs';
+
+/**
+ * Returns a styled, uppercase log level tag for CLI output with color mapping
+ * for better readability.
+ *
+ * @param {number} level
+ * @returns {string}
+ */
+export const prettifyLevel = level => {
+  const tag = levelTags[level] ?? String(level);
+
+  return styleText(levelToColorMap[level], tag.toUpperCase());
+};

package/src/logger/utils/time.mjs

@@ -0,0 +1,21 @@
+'use strict';
+
+/**
+ * Formats a Unix timestamp in milliseconds as a human-readable time string
+ * in UTC timezone for CLI output.
+ *
+ * @param {number} timestamp
+ * @returns {string}
+ */
+export const prettifyTimestamp = timestamp => {
+  const date = new Date(timestamp);
+
+  return new Intl.DateTimeFormat('en-US', {
+    timeZone: 'UTC',
+    hour12: false,
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+    fractionalSecondDigits: 3,
+  }).format(date);
+};

package/src/parsers/markdown.mjs

@@ -0,0 +1,49 @@
+'use strict';
+
+import { coerce } from 'semver';
+
+import { loadFromURL } from '../utils/loaders.mjs';
+
+// A ReGeX for retrieving Node.js version headers from the CHANGELOG.md
+const NODE_VERSIONS_REGEX = /\* \[Node\.js ([0-9.]+)\]\S+ (.*)\r?\n/g;
+
+// A ReGeX for retrieving the list items in the index document
+const LIST_ITEM_REGEX = /\* \[(.*?)\]\((.*?)\.md\)/g;
+
+// A ReGeX for checking if a Node.js version is an LTS release
+const NODE_LTS_VERSION_REGEX = /Long Term Support/i;
+
+/**
+ * Retrieves all Node.js major versions from the provided CHANGELOG.md file
+ * and returns an array of objects containing the version and LTS status.
+ * @param {string|URL} path Path to changelog
+ * @returns {Promise<Array<import('./types').ReleaseEntry>>}
+ */
+export const parseChangelog = async path => {
+  const changelog = await loadFromURL(path);
+
+  const nodeMajors = Array.from(changelog.matchAll(NODE_VERSIONS_REGEX));
+
+  return nodeMajors.map(match => ({
+    version: coerce(match[1]),
+    isLts: NODE_LTS_VERSION_REGEX.test(match[2]),
+  }));
+};
+
+/**
+ * Retrieves all the document titles for sidebar generation.
+ *
+ * @param {string|URL} path Path to changelog
+ * @returns {Promise<Array<{ section: string, api: string }>>}
+ */
+export const parseIndex = async path => {
+  if (!path || !path.length) {
+    return [];
+  }
+
+  const index = await loadFromURL(path);
+
+  const items = Array.from(index.matchAll(LIST_ITEM_REGEX));
+
+  return items.map(([, section, api]) => ({ section, api }));
+};

package/src/parsers/types.d.ts

@@ -0,0 +1,7 @@
+import type { SemVer } from 'semver';
+
+export interface ReleaseEntry {
+  version: SemVer;
+  isLts: boolean;
+  isCurrent: boolean;
+}

package/src/threading/chunk-worker.mjs

@@ -0,0 +1,23 @@
+import { loadGenerator } from '../generators/loader.mjs';
+import { setConfig } from '../utils/configuration/index.mjs';
+
+/**
+ * Processes a chunk of items using the specified generator's processChunk method.
+ * This is the worker entry point for Piscina.
+ *
+ * @param {ParallelTaskOptions} opts - Task options from Piscina
+ * @returns {Promise<unknown>} The processed result
+ */
+export default async ({
+  generatorSpecifier,
+  input,
+  itemIndices,
+  extra,
+  configuration,
+}) => {
+  await setConfig(configuration);
+
+  const generator = await loadGenerator(generatorSpecifier);
+
+  return generator.processChunk(input, itemIndices, extra);
+};

package/src/threading/index.mjs

@@ -0,0 +1,27 @@
+import Piscina from 'piscina';
+
+import logger from '../logger/index.mjs';
+
+const poolLogger = logger.child('WorkerPool');
+
+const workerScript = import.meta.resolve('./chunk-worker.mjs');
+
+/**
+ * Creates a Piscina worker pool for parallel processing.
+ *
+ * @param {number} threads - Maximum number of worker threads
+ * @returns {import('piscina').Piscina} Configured Piscina instance
+ */
+export default function createWorkerPool(threads) {
+  poolLogger.debug(`WorkerPool initialized`, {
+    threads,
+    workerScript,
+  });
+
+  return new Piscina({
+    filename: workerScript,
+    minThreads: 0,
+    maxThreads: threads,
+    idleTimeout: 1_000,
+  });
+}

package/src/threading/parallel.mjs

@@ -0,0 +1,140 @@
+'use strict';
+
+import logger from '../logger/index.mjs';
+
+const parallelLogger = logger.child('parallel');
+
+/**
+ * Splits items into chunks of specified size.
+ *
+ * @param {number} count - Total number of items
+ * @param {number} size - Maximum items per chunk
+ * @returns {number[][]} Array of index arrays for each chunk
+ */
+const createChunks = (count, size) => {
+  const chunks = [];
+
+  for (let i = 0; i < count; i += size) {
+    chunks.push(
+      Array.from({ length: Math.min(size, count - i) }, (_, j) => i + j)
+    );
+  }
+
+  return chunks;
+};
+
+/**
+ * Prepares task data for a chunk, slicing input to only include relevant items.
+ *
+ * @param {unknown[]} fullInput - Full input array
+ * @param {number[]} indices - Indices to process
+ * @param {Object} extra - Stuff to pass to the worker
+ * @param {import('../utils/configuration/types').Configuration} configuration - Serialized options
+ * @param {string} generatorSpecifier - Resolved specifier of the generator
+ * @param {string} generatorName - Name of the generator
+ * @returns {ParallelTaskOptions} Task data for Piscina
+ */
+const createTask = (
+  fullInput,
+  indices,
+  extra,
+  configuration,
+  generatorSpecifier,
+  generatorName
+) => {
+  return {
+    generatorSpecifier,
+    // Only send the items needed for this chunk (reduces serialization overhead)
+    input: indices.map(i => fullInput[i]),
+    // Remap indices to 0-based for the sliced array
+    itemIndices: indices.map((_, i) => i),
+    extra,
+    // Only pass the needed configuration to this generator
+    configuration: {
+      [generatorName]: configuration[generatorName],
+    },
+  };
+};
+
+/**
+ * Creates a parallel worker that distributes work across a Piscina thread pool.
+ *
+ * @param {string} specifier - Resolved generator specifier (importable from workers)
+ * @param {GeneratorMetadata} generator - The loaded generator
+ * @param {import('piscina').Piscina} pool - Piscina instance
+ * @param {import('../utils/configuration/types').Configuration} configuration - Generator options
+ * @returns {ParallelWorker}
+ */
+export default function createParallelWorker(
+  specifier,
+  generator,
+  pool,
+  configuration
+) {
+  const { threads, chunkSize } = configuration;
+
+  const { name } = generator;
+
+  return {
+    /**
+     * Processes items in parallel, yielding results as chunks complete.
+     *
+     * @template T
+     * @param {T[]} items - Items to process
+     * @param {object} extra - Extra options
+     * @yields {R[]} Chunk results as they complete
+     */
+    async *stream(items, extra) {
+      if (items.length === 0) {
+        return;
+      }
+
+      const chunks = createChunks(items.length, chunkSize);
+
+      parallelLogger.debug(
+        `Distributing ${items.length} items across ${chunks.length} chunks`,
+        { generator: name, chunks: chunks.length, chunkSize, threads }
+      );
+
+      const runInOneGo = threads <= 1 || items.length <= 2;
+
+      // Submit all tasks to Piscina - each promise resolves to itself for removal
+      const pending = new Set(
+        chunks.map(indices => {
+          if (runInOneGo) {
+            const promise = generator
+              .processChunk(items, indices, extra)
+              .then(result => ({ promise, result }));
+
+            return promise;
+          }
+
+          const promise = pool
+            .run(
+              createTask(items, indices, extra, configuration, specifier, name)
+            )
+            .then(result => ({ promise, result }));
+
+          return promise;
+        })
+      );
+
+      // Yield results as they complete (true parallel collection)
+      let completed = 0;
+
+      while (pending.size > 0) {
+        const { promise, result } = await Promise.race(pending);
+
+        pending.delete(promise);
+
+        completed++;
+
+        parallelLogger.debug(`Chunk ${completed}/${chunks.length} completed`, {
+          generator: name,
+        });
+
+        yield result;
+      }
+    },
+  };
+}

package/src/utils/array.mjs

@@ -0,0 +1,7 @@
+/**
+ * Converts a value to an array.
+ * @template T
+ * @param {T | T[]} val - The value to convert.
+ * @returns {T[]} The value as an array.
+ */
+export const enforceArray = val => (Array.isArray(val) ? val : [val]);