@reicek/neataptic-ts 0.1.25 → 0.1.26

package/scripts/generate-docs/generate-docs.constants.ts

@@ -0,0 +1,107 @@
+/*
+ * Centralizes stable docs-generator constants and target definitions.
+ *
+ * Keeping these values in one file makes it easier to audit what the generator
+ * considers a target, a published output root, or an ordering-control file
+ * without mixing that policy into traversal or rendering code.
+ */
+
+import * as path from 'path';
+
+import type { DocsTargetConfig } from './generate-docs.types.js';
+
+/** Root docs output directory mirrored into the published docs site. */
+export const DOCS_DIR = path.resolve('docs');
+
+/** Default docs target when no CLI or environment override is supplied. */
+export const DEFAULT_DOCS_TARGET = 'src';
+
+/** Synthetic symbol name used to store file-level summary content. */
+export const FILE_SUMMARY_SYMBOL_NAME = '__file_summary__';
+
+/** Source-file glob used to discover docs-generator inputs. */
+export const SOURCE_FILE_GLOBS = ['**/*.ts'];
+
+/** Ignore rules for files that should never become generated docs sources. */
+export const SOURCE_FILE_IGNORE_GLOBS = ['**/*.d.ts'];
+
+/** Generated docs landing page file name for the folder index. */
+export const FOLDER_INDEX_FILE_NAME = 'FOLDERS.md';
+
+/** Per-directory ordering config file name. */
+export const DOCS_ORDER_CONFIG_FILE_NAME = 'docs.order.json';
+
+/** Supported keys accepted inside `docs.order.json`. */
+export const DOCS_ORDER_SUPPORTED_KEYS = [
+  'introFile',
+  'fileOrder',
+  'symbolOrder',
+  'folderOrder',
+  'hiddenFiles',
+  'hiddenSymbols',
+] as const;
+
+/** Workspace root used to rewrite absolute ts-morph type paths into repo paths. */
+export const WORKSPACE_ROOT_DIR = path.resolve('.');
+
+/**
+ * Docs targets supported by the folder README generator.
+ *
+ * Each target maps one source tree into one published docs tree while keeping
+ * any target-specific root README mirroring rules local to the target.
+ */
+export const DOCS_TARGETS: Record<string, DocsTargetConfig> = {
+  src: {
+    name: 'src',
+    sourceDir: path.resolve('src'),
+    docsDir: DOCS_DIR,
+    rootDocsDir: path.join(DOCS_DIR, 'src'),
+    rootReadmeSource: path.resolve('README.md'),
+    rootReadmeDestination: path.join(DOCS_DIR, 'README.md'),
+    includeFolderIndex: true,
+  },
+  asciiMaze: {
+    name: 'asciiMaze',
+    sourceDir: path.resolve('test', 'examples', 'asciiMaze'),
+    docsDir: path.join(DOCS_DIR, 'examples', 'asciiMaze', 'docs'),
+    rootDocsDir: path.join(DOCS_DIR, 'examples', 'asciiMaze', 'docs'),
+    rootReadmeSource: path.resolve(
+      'test',
+      'examples',
+      'asciiMaze',
+      'README.md',
+    ),
+    rootReadmeDestination: path.join(
+      DOCS_DIR,
+      'examples',
+      'asciiMaze',
+      'docs',
+      'README.md',
+    ),
+    excludeRootSourceFiles: true,
+    publishedRootDir: path.join(DOCS_DIR, 'examples', 'asciiMaze'),
+    preservePublishedEntries: ['index.html'],
+  },
+  'flappy-bird': {
+    name: 'flappy-bird',
+    sourceDir: path.resolve('test', 'examples', 'flappy_bird'),
+    docsDir: path.join(DOCS_DIR, 'examples', 'flappy_bird', 'docs'),
+    rootDocsDir: path.join(DOCS_DIR, 'examples', 'flappy_bird', 'docs'),
+    rootReadmeSource: path.resolve(
+      'test',
+      'examples',
+      'flappy_bird',
+      'README.md',
+    ),
+    rootReadmeDestination: path.join(
+      DOCS_DIR,
+      'examples',
+      'flappy_bird',
+      'docs',
+      'README.md',
+    ),
+    excludeRootSourceFiles: true,
+    publishedRootDir: path.join(DOCS_DIR, 'examples', 'flappy_bird'),
+    preservePublishedEntries: ['index.html'],
+  },
+};

package/scripts/generate-docs/generate-docs.order.ts

@@ -0,0 +1,355 @@
+/*
+ * Owns `docs.order.json` loading, validation, and cached lookup.
+ *
+ * Rendering code only needs a validated config view; this chapter keeps JSON
+ * parsing, warning messages, and cache lifecycle separate from markdown logic.
+ */
+
+import fs from 'fs-extra';
+import * as path from 'path';
+
+import {
+  DOCS_ORDER_CONFIG_FILE_NAME,
+  DOCS_ORDER_SUPPORTED_KEYS,
+  WORKSPACE_ROOT_DIR,
+} from './generate-docs.constants.js';
+import type {
+  DirectoryDocsOrderConfig,
+  GenerateDocsState,
+  LoadedDirectoryDocsOrderConfig,
+} from './generate-docs.types.js';
+
+/**
+ * Loads and caches the optional per-folder docs ordering config.
+ *
+ * Phase 1 only validates and stores config so later rendering steps can reuse
+ * the same validated data without re-reading the file.
+ *
+ * @param state - Shared docs-generator state.
+ * @param directoryPath - Absolute directory path that may contain docs config.
+ * @returns Parsed and validated config when present.
+ */
+export async function loadDirectoryDocsOrderConfig(
+  state: GenerateDocsState,
+  directoryPath: string,
+): Promise<LoadedDirectoryDocsOrderConfig | undefined> {
+  const normalizedDirectoryPath = path.resolve(directoryPath);
+  if (state.directoryDocsOrderConfigCache.has(normalizedDirectoryPath)) {
+    return state.directoryDocsOrderConfigCache.get(normalizedDirectoryPath)!;
+  }
+
+  const pendingConfig = readDirectoryDocsOrderConfig(
+    normalizedDirectoryPath,
+  ).then((loadedConfig) => {
+    state.resolvedDirectoryDocsOrderConfigCache.set(
+      normalizedDirectoryPath,
+      loadedConfig,
+    );
+    return loadedConfig;
+  });
+
+  state.directoryDocsOrderConfigCache.set(
+    normalizedDirectoryPath,
+    pendingConfig,
+  );
+  return pendingConfig;
+}
+
+/**
+ * Returns the cached docs ordering config for a directory.
+ *
+ * @param state - Shared docs-generator state.
+ * @param directoryPath - Absolute directory path.
+ * @returns Cached config when already loaded.
+ */
+export function getCachedDirectoryDocsOrderConfig(
+  state: GenerateDocsState,
+  directoryPath: string,
+): LoadedDirectoryDocsOrderConfig | undefined {
+  return state.resolvedDirectoryDocsOrderConfigCache.get(
+    path.resolve(directoryPath),
+  );
+}
+
+/**
+ * Writes a scoped warning for one docs ordering config file.
+ *
+ * @param configPath - Absolute config path.
+ * @param message - Warning message.
+ * @returns Nothing.
+ */
+export function warnDirectoryDocsOrderConfig(
+  configPath: string,
+  message: string,
+): void {
+  const relativeConfigPath = path
+    .relative(WORKSPACE_ROOT_DIR, configPath)
+    .replace(/\\/g, '/');
+  console.warn(`[docs] ${relativeConfigPath}: ${message}`);
+}
+
+/**
+ * Reads and validates one directory's `docs.order.json` file when present.
+ *
+ * @param directoryPath - Absolute directory path.
+ * @returns Parsed config or undefined when absent or invalid.
+ */
+async function readDirectoryDocsOrderConfig(
+  directoryPath: string,
+): Promise<LoadedDirectoryDocsOrderConfig | undefined> {
+  const configPath = path.join(directoryPath, DOCS_ORDER_CONFIG_FILE_NAME);
+  if (!(await fs.pathExists(configPath))) {
+    return undefined;
+  }
+
+  try {
+    const rawConfigText = await fs.readFile(configPath, 'utf8');
+    const parsedConfig: unknown = JSON.parse(rawConfigText);
+    const validatedConfig = validateDirectoryDocsOrderConfig(
+      parsedConfig,
+      configPath,
+    );
+    return validatedConfig
+      ? { configPath, config: validatedConfig }
+      : undefined;
+  } catch (error) {
+    warnDirectoryDocsOrderConfig(
+      configPath,
+      `Failed to read ${DOCS_ORDER_CONFIG_FILE_NAME}: ${getErrorMessage(error)}`,
+    );
+    return undefined;
+  }
+}
+
+/**
+ * Validates the supported phase-1 docs ordering config keys.
+ *
+ * @param parsedConfig - Raw parsed JSON value.
+ * @param configPath - Absolute config path used in warnings.
+ * @returns Sanitized config when at least one supported value is valid.
+ */
+function validateDirectoryDocsOrderConfig(
+  parsedConfig: unknown,
+  configPath: string,
+): DirectoryDocsOrderConfig | undefined {
+  if (!isRecord(parsedConfig)) {
+    warnDirectoryDocsOrderConfig(
+      configPath,
+      'Config must be a JSON object. Ignoring file.',
+    );
+    return undefined;
+  }
+
+  for (const configKey of Object.keys(parsedConfig)) {
+    if (!DOCS_ORDER_SUPPORTED_KEYS.includes(configKey as never)) {
+      warnDirectoryDocsOrderConfig(
+        configPath,
+        `Unknown key "${configKey}". Supported keys: ${DOCS_ORDER_SUPPORTED_KEYS.join(', ')}`,
+      );
+    }
+  }
+
+  const validatedConfig: DirectoryDocsOrderConfig = {};
+  const introFile = normalizeOptionalStringConfigValue(
+    parsedConfig.introFile,
+    'introFile',
+    configPath,
+  );
+  if (introFile) {
+    validatedConfig.introFile = introFile;
+  }
+
+  const fileOrder = normalizeStringArrayConfigValue(
+    parsedConfig.fileOrder,
+    'fileOrder',
+    configPath,
+  );
+  if (fileOrder) {
+    validatedConfig.fileOrder = fileOrder;
+  }
+
+  const symbolOrder = normalizeSymbolOrderConfigValue(
+    parsedConfig.symbolOrder,
+    configPath,
+  );
+  if (symbolOrder) {
+    validatedConfig.symbolOrder = symbolOrder;
+  }
+
+  const folderOrder = normalizeStringArrayConfigValue(
+    parsedConfig.folderOrder,
+    'folderOrder',
+    configPath,
+  );
+  if (folderOrder) {
+    validatedConfig.folderOrder = folderOrder;
+  }
+
+  const hiddenFiles = normalizeStringArrayConfigValue(
+    parsedConfig.hiddenFiles,
+    'hiddenFiles',
+    configPath,
+  );
+  if (hiddenFiles) {
+    validatedConfig.hiddenFiles = hiddenFiles;
+  }
+
+  const hiddenSymbols = normalizeStringArrayConfigValue(
+    parsedConfig.hiddenSymbols,
+    'hiddenSymbols',
+    configPath,
+  );
+  if (hiddenSymbols) {
+    validatedConfig.hiddenSymbols = hiddenSymbols;
+  }
+
+  return Object.keys(validatedConfig).length > 0 ? validatedConfig : undefined;
+}
+
+/**
+ * Normalizes a single optional string config field.
+ *
+ * @param value - Raw config value.
+ * @param fieldName - Config field name.
+ * @param configPath - Absolute config path used in warnings.
+ * @returns Trimmed string when valid.
+ */
+function normalizeOptionalStringConfigValue(
+  value: unknown,
+  fieldName: string,
+  configPath: string,
+): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    warnDirectoryDocsOrderConfig(
+      configPath,
+      `Field "${fieldName}" must be a non-empty string. Ignoring value.`,
+    );
+    return undefined;
+  }
+
+  return value.trim();
+}
+
+/**
+ * Normalizes one string-array config field.
+ *
+ * @param value - Raw config value.
+ * @param fieldName - Config field name.
+ * @param configPath - Absolute config path used in warnings.
+ * @returns Unique non-empty strings when valid.
+ */
+function normalizeStringArrayConfigValue(
+  value: unknown,
+  fieldName: string,
+  configPath: string,
+): string[] | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!Array.isArray(value)) {
+    warnDirectoryDocsOrderConfig(
+      configPath,
+      `Field "${fieldName}" must be an array of non-empty strings. Ignoring value.`,
+    );
+    return undefined;
+  }
+
+  const normalizedEntries = value
+    .filter((entry): entry is string => typeof entry === 'string')
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+
+  if (normalizedEntries.length !== value.length) {
+    warnDirectoryDocsOrderConfig(
+      configPath,
+      `Field "${fieldName}" must contain only non-empty strings. Dropping invalid entries.`,
+    );
+  }
+
+  return normalizedEntries.length > 0
+    ? [...new Set(normalizedEntries)]
+    : undefined;
+}
+
+/**
+ * Normalizes the per-file symbol ordering map.
+ *
+ * @param value - Raw config value.
+ * @param configPath - Absolute config path used in warnings.
+ * @returns Sanitized symbol-order map when valid.
+ */
+function normalizeSymbolOrderConfigValue(
+  value: unknown,
+  configPath: string,
+): Record<string, string[]> | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+
+  if (!isRecord(value)) {
+    warnDirectoryDocsOrderConfig(
+      configPath,
+      'Field "symbolOrder" must be an object keyed by file name. Ignoring value.',
+    );
+    return undefined;
+  }
+
+  const normalizedSymbolOrderEntries = Object.entries(value)
+    .map(([fileName, symbolNames]) => {
+      const normalizedFileName = fileName.trim();
+      if (normalizedFileName.length === 0) {
+        warnDirectoryDocsOrderConfig(
+          configPath,
+          'Field "symbolOrder" contains an empty file key. Dropping entry.',
+        );
+        return undefined;
+      }
+
+      const normalizedSymbols = normalizeStringArrayConfigValue(
+        symbolNames,
+        `symbolOrder.${normalizedFileName}`,
+        configPath,
+      );
+      if (!normalizedSymbols) {
+        return undefined;
+      }
+
+      return [normalizedFileName, normalizedSymbols] as const;
+    })
+    .filter(
+      (entry): entry is readonly [string, string[]] => entry !== undefined,
+    );
+
+  return normalizedSymbolOrderEntries.length > 0
+    ? Object.fromEntries(normalizedSymbolOrderEntries)
+    : undefined;
+}
+
+/**
+ * Narrows unknown values to simple object records.
+ *
+ * @param value - Value to inspect.
+ * @returns True when the value is a plain record-like object.
+ */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Extracts a readable message from unknown thrown values.
+ *
+ * @param error - Thrown value.
+ * @returns Human-readable error text.
+ */
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+
+  return String(error);
+}

package/scripts/generate-docs/generate-docs.state.ts

@@ -0,0 +1,31 @@
+/*
+ * Creates the shared runtime state for one docs-generation process.
+ *
+ * The generator intentionally reuses one ts-morph project and one docs-order
+ * cache set so each chapter can stay pure about its responsibility while the
+ * process still shares expensive state safely.
+ */
+
+import { Project } from 'ts-morph';
+
+import type { GenerateDocsState } from './generate-docs.types.js';
+
+/**
+ * Creates the mutable runtime state shared across one docs-generation run.
+ *
+ * The generator intentionally keeps one ts-morph project and one pair of
+ * docs-order caches for the full process so each target run can reuse the same
+ * lookup behavior without relying on module-level globals.
+ *
+ * @returns Shared docs-generator state.
+ */
+export function createGenerateDocsState(): GenerateDocsState {
+  return {
+    project: new Project({
+      tsConfigFilePath: 'tsconfig.json',
+      skipAddingFilesFromTsConfig: true,
+    }),
+    resolvedDirectoryDocsOrderConfigCache: new Map(),
+    directoryDocsOrderConfigCache: new Map(),
+  };
+}

package/scripts/generate-docs/generate-docs.targets.ts

@@ -0,0 +1,165 @@
+/*
+ * Owns CLI target selection and source-tree preparation for one docs run.
+ *
+ * This chapter decides what tree is being documented and which source files are
+ * eligible before any ts-morph symbol work or markdown rendering begins.
+ */
+
+import fg from 'fast-glob';
+import fs from 'fs-extra';
+import * as path from 'path';
+import type { SourceFile } from 'ts-morph';
+
+import {
+  DEFAULT_DOCS_TARGET,
+  DOCS_TARGETS,
+  SOURCE_FILE_GLOBS,
+  SOURCE_FILE_IGNORE_GLOBS,
+} from './generate-docs.constants.js';
+import type {
+  DocsTargetConfig,
+  GenerateDocsState,
+} from './generate-docs.types.js';
+
+/**
+ * Resolves the active docs target from CLI or environment input.
+ *
+ * Lookup order:
+ * 1. `--target=...`
+ * 2. `DOCS_TARGET`
+ * 3. default target
+ *
+ * @param rawArguments - CLI arguments passed after the executable path.
+ * @returns Concrete docs target configuration.
+ */
+export function resolveDocsTarget(
+  rawArguments: readonly string[],
+): DocsTargetConfig {
+  const cliTarget = rawArguments
+    .find((argument) => argument.startsWith('--target='))
+    ?.slice('--target='.length);
+  const requestedTarget =
+    cliTarget ?? process.env.DOCS_TARGET ?? DEFAULT_DOCS_TARGET;
+  const resolvedTarget = DOCS_TARGETS[requestedTarget];
+
+  if (!resolvedTarget) {
+    const supportedTargets = Object.keys(DOCS_TARGETS).toSorted().join(', ');
+    throw new Error(
+      `Unknown docs target "${requestedTarget}". Supported targets: ${supportedTargets}`,
+    );
+  }
+
+  return resolvedTarget;
+}
+
+/**
+ * Prepares the output tree for the selected target.
+ *
+ * @param target - Target configuration.
+ * @returns Nothing.
+ */
+export async function initializeDocsTarget(
+  target: DocsTargetConfig,
+): Promise<void> {
+  await cleanupPublishedRoot(target);
+  await fs.ensureDir(target.docsDir);
+
+  if (
+    !target.rootReadmeSource ||
+    !target.rootReadmeDestination ||
+    !(await fs.pathExists(target.rootReadmeSource))
+  ) {
+    return;
+  }
+
+  await fs.ensureDir(path.dirname(target.rootReadmeDestination));
+  await fs.copyFile(target.rootReadmeSource, target.rootReadmeDestination);
+}
+
+/**
+ * Loads target source files into the shared ts-morph project.
+ *
+ * @param state - Shared docs-generator state.
+ * @param target - Target configuration.
+ * @returns Filtered source files that belong to the target tree.
+ */
+export async function loadTargetSourceFiles(
+  state: GenerateDocsState,
+  target: DocsTargetConfig,
+): Promise<SourceFile[]> {
+  const filePaths = await fg(SOURCE_FILE_GLOBS, {
+    cwd: target.sourceDir,
+    absolute: true,
+    ignore: SOURCE_FILE_IGNORE_GLOBS,
+  });
+
+  for (const filePath of filePaths) {
+    if (!shouldIncludeSourceFile(filePath, target)) {
+      continue;
+    }
+
+    state.project.addSourceFileAtPath(filePath);
+  }
+
+  const rawSourceFiles = state.project.getSourceFiles();
+  const sourceFiles = rawSourceFiles.filter((sourceFile) => {
+    const filePath = sourceFile.getFilePath();
+    return !filePath.endsWith('.d.ts') && !/node_modules/.test(filePath);
+  });
+
+  console.log(
+    `[docs:${target.name}] Loaded ${sourceFiles.length} source files (raw: ${rawSourceFiles.length})`,
+  );
+
+  return sourceFiles;
+}
+
+/**
+ * Determines whether a discovered file should participate in docs generation.
+ *
+ * @param filePath - Absolute source file path.
+ * @param target - Target configuration.
+ * @returns True when the file belongs in the target set.
+ */
+function shouldIncludeSourceFile(
+  filePath: string,
+  target: DocsTargetConfig,
+): boolean {
+  if (/\.test\.ts$/i.test(filePath)) {
+    return false;
+  }
+
+  if (!target.excludeRootSourceFiles) {
+    return true;
+  }
+
+  const relativeDirectory = path.dirname(
+    path.relative(target.sourceDir, filePath),
+  );
+  return relativeDirectory !== '' && relativeDirectory !== '.';
+}
+
+/**
+ * Removes previously published generated files for targets that mirror output
+ * into a browsable published directory.
+ *
+ * @param target - Target configuration.
+ * @returns Nothing.
+ */
+async function cleanupPublishedRoot(target: DocsTargetConfig): Promise<void> {
+  if (!target.publishedRootDir) {
+    return;
+  }
+
+  await fs.ensureDir(target.publishedRootDir);
+  const preservedEntries = new Set(target.preservePublishedEntries ?? []);
+  const childEntries = await fs.readdir(target.publishedRootDir);
+
+  for (const childEntry of childEntries) {
+    if (preservedEntries.has(childEntry)) {
+      continue;
+    }
+
+    await fs.remove(path.join(target.publishedRootDir, childEntry));
+  }
+}