@reicek/neataptic-ts 0.1.25 → 0.1.26

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

@@ -0,0 +1,63 @@
+/*
+ * Generates per-folder README.md aggregating exported symbols' JSDoc.
+ * - Copies root README.md into docs/ (manual content retained)
+ * - Skips generating README for src root (leave top-level README manual)
+ * Usage: npm run docs:folders
+ *
+ * The folder split keeps this file orchestration-only: target resolution,
+ * source loading, symbol normalization, and markdown emission each live in a
+ * dedicated chapter file below.
+ */
+import {
+  emitDirectoryDocs,
+  emitFolderIndex,
+} from './output/generate-docs.output.js';
+import { createGenerateDocsState } from './generate-docs.state.js';
+import {
+  collectDirectorySymbols,
+  dedupeDirectorySymbols,
+} from './symbols/generate-docs.symbols.js';
+import {
+  initializeDocsTarget,
+  loadTargetSourceFiles,
+  resolveDocsTarget,
+} from './generate-docs.targets.js';
+
+/**
+ * Generates docs for the requested target.
+ *
+ * The script runs in four passes:
+ * 1. Resolve and prepare the target output tree.
+ * 2. Load source files into the shared ts-morph project.
+ * 3. Collect and normalize rendered symbols.
+ * 4. Emit directory README files and the optional folder index.
+ *
+ * @returns Nothing.
+ */
+async function main(): Promise<void> {
+  const state = createGenerateDocsState();
+
+  // Step 1: Resolve and prepare the requested target.
+  const target = resolveDocsTarget(process.argv.slice(2));
+  await initializeDocsTarget(target);
+
+  // Step 2: Load the target source files.
+  const sourceFiles = await loadTargetSourceFiles(state, target);
+
+  // Step 3: Collect and normalize rendered symbols.
+  const directorySymbolMap = collectDirectorySymbols(sourceFiles);
+  dedupeDirectorySymbols(directorySymbolMap);
+
+  // Step 4: Emit README files and the optional folder index.
+  await emitDirectoryDocs(state, directorySymbolMap, target);
+  if (target.includeFolderIndex) {
+    await emitFolderIndex(state, directorySymbolMap, target);
+  }
+
+  console.log(`[docs:${target.name}] Per-folder README generation complete.`);
+}
+
+main().catch((error: unknown) => {
+  console.error(error);
+  process.exit(1);
+});

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

@@ -0,0 +1,112 @@
+/*
+ * Shared contracts for the folder-based docs generator.
+ *
+ * The split keeps traversal, ordering, and markdown emission in separate
+ * modules, so these interfaces act as the small vocabulary that lets those
+ * chapters collaborate without reaching into each other's implementation.
+ */
+
+import type { Project } from 'ts-morph';
+
+/**
+ * Configures one docs-generation target.
+ */
+export interface DocsTargetConfig {
+  name: string;
+  sourceDir: string;
+  docsDir: string;
+  rootDocsDir: string;
+  rootReadmeSource?: string;
+  rootReadmeDestination?: string;
+  excludeRootSourceFiles?: boolean;
+  includeFolderIndex?: boolean;
+  publishedRootDir?: string;
+  preservePublishedEntries?: readonly string[];
+}
+
+/**
+ * Renders one documented parameter description for README output.
+ */
+export interface RenderedParameter {
+  name: string;
+  type?: string;
+  doc?: string;
+}
+
+/**
+ * Stores the normalized docs-ready view of one exported or documented symbol.
+ */
+export interface RenderedSymbol {
+  kind: string;
+  name: string;
+  filePath: string;
+  parent?: string;
+  signature?: string;
+  jsdoc: {
+    summary?: string;
+    description?: string;
+    params?: RenderedParameter[];
+    returns?: string;
+    deprecated?: string;
+    examples?: string[];
+  };
+}
+
+/**
+ * Represents one folder inside the generated docs index tree.
+ */
+export interface FolderIndexNode {
+  name: string;
+  path: string;
+  sourceDirectoryPath: string;
+  children: Map<string, FolderIndexNode>;
+  fileCount?: number;
+}
+
+/**
+ * Captures the supported `docs.order.json` controls for one directory.
+ */
+export interface DirectoryDocsOrderConfig {
+  introFile?: string;
+  fileOrder?: string[];
+  symbolOrder?: Record<string, string[]>;
+  folderOrder?: string[];
+  hiddenFiles?: string[];
+  hiddenSymbols?: string[];
+}
+
+/**
+ * Stores one validated directory-order config plus its source path.
+ */
+export interface LoadedDirectoryDocsOrderConfig {
+  configPath: string;
+  config: DirectoryDocsOrderConfig;
+}
+
+/**
+ * Represents the promoted file-summary content for a source file.
+ */
+export interface RenderedFileSummary {
+  description?: string;
+  examples?: string[];
+}
+
+/**
+ * Groups rendered symbols by absolute directory path, then by absolute file path.
+ */
+export type DirectorySymbolMap = Map<string, Map<string, RenderedSymbol[]>>;
+
+/**
+ * Owns mutable state shared across one docs-generation run.
+ */
+export interface GenerateDocsState {
+  project: Project;
+  resolvedDirectoryDocsOrderConfigCache: Map<
+    string,
+    LoadedDirectoryDocsOrderConfig | undefined
+  >;
+  directoryDocsOrderConfigCache: Map<
+    string,
+    Promise<LoadedDirectoryDocsOrderConfig | undefined>
+  >;
+}

package/scripts/generate-docs/output/generate-docs.output.folder-index.utils.ts

@@ -0,0 +1,167 @@
+/*
+ * Builds the generated folder index markdown for docs output.
+ *
+ * This chapter owns tree construction and recursive index rendering so the
+ * output root can stay focused on orchestrating file writes.
+ */
+
+import * as path from 'path';
+
+import type {
+  DirectorySymbolMap,
+  DocsTargetConfig,
+  FolderIndexNode,
+  GenerateDocsState,
+} from '../generate-docs.types.js';
+import {
+  resolveSortedFolderIndexChildNames,
+  resolveVisibleDirectoryFiles,
+} from './generate-docs.output.ordering.utils.js';
+
+/**
+ * Builds markdown for the generated folder index.
+ *
+ * @param state - Shared docs-generator state.
+ * @param directorySymbolMap - Normalized directory symbol map.
+ * @param target - Target configuration.
+ * @returns Folder index markdown.
+ */
+export function buildFolderIndexMarkdown(
+  state: GenerateDocsState,
+  directorySymbolMap: DirectorySymbolMap,
+  target: DocsTargetConfig,
+): string {
+  const rootNode: FolderIndexNode = {
+    name: 'src',
+    path: 'src',
+    sourceDirectoryPath: target.sourceDir,
+    children: new Map(),
+    fileCount: 0,
+  };
+
+  const relativeDirectories = [...directorySymbolMap.keys()]
+    .map((directoryPath) => path.relative(target.sourceDir, directoryPath))
+    .filter((relativeDirectory) => !relativeDirectory.startsWith('..'));
+
+  for (const relativeDirectory of relativeDirectories) {
+    insertFolderIndexNode(
+      state,
+      rootNode,
+      relativeDirectory,
+      target,
+      directorySymbolMap,
+    );
+  }
+
+  const lines = [
+    '# Docs Index',
+    '',
+    'Auto-generated index of source folders (click to open folder README).',
+    '',
+  ];
+
+  renderFolderIndexNode(state, rootNode, 0, lines);
+  return `${lines.join('\n')}\n`;
+}
+
+/**
+ * Inserts one relative directory into the folder index tree.
+ *
+ * @param state - Shared docs-generator state.
+ * @param rootNode - Root folder index node.
+ * @param relativeDirectory - Relative directory from the target source root.
+ * @param target - Target configuration.
+ * @param directorySymbolMap - Directory symbol map used for file counts.
+ * @returns Nothing.
+ */
+function insertFolderIndexNode(
+  state: GenerateDocsState,
+  rootNode: FolderIndexNode,
+  relativeDirectory: string,
+  target: DocsTargetConfig,
+  directorySymbolMap: DirectorySymbolMap,
+): void {
+  const absoluteDirectoryPath = path.join(
+    target.sourceDir,
+    relativeDirectory === '' ? '' : relativeDirectory,
+  );
+  const fileSymbolMap = directorySymbolMap.get(absoluteDirectoryPath);
+
+  if (relativeDirectory === '') {
+    if (fileSymbolMap) {
+      rootNode.fileCount = resolveVisibleDirectoryFiles(
+        state,
+        absoluteDirectoryPath,
+        [...fileSymbolMap.keys()],
+      ).length;
+    }
+    return;
+  }
+
+  const pathParts = relativeDirectory.replace(/\\/g, '/').split('/');
+
+  let currentNode = rootNode;
+  let accumulatedPath = rootNode.path;
+  let accumulatedSourceDirectoryPath = rootNode.sourceDirectoryPath;
+
+  for (const pathPart of pathParts) {
+    accumulatedPath = `${accumulatedPath}/${pathPart}`;
+    accumulatedSourceDirectoryPath = path.join(
+      accumulatedSourceDirectoryPath,
+      pathPart,
+    );
+
+    if (!currentNode.children.has(pathPart)) {
+      currentNode.children.set(pathPart, {
+        name: pathPart,
+        path: accumulatedPath,
+        sourceDirectoryPath: accumulatedSourceDirectoryPath,
+        children: new Map(),
+      });
+    }
+
+    currentNode = currentNode.children.get(pathPart)!;
+  }
+
+  if (fileSymbolMap) {
+    currentNode.fileCount = resolveVisibleDirectoryFiles(
+      state,
+      absoluteDirectoryPath,
+      [...fileSymbolMap.keys()],
+    ).length;
+  }
+}
+
+/**
+ * Renders one folder index node and its children recursively.
+ *
+ * @param state - Shared docs-generator state.
+ * @param node - Current folder index node.
+ * @param level - Nesting level.
+ * @param lines - Output line buffer.
+ * @returns Nothing.
+ */
+function renderFolderIndexNode(
+  state: GenerateDocsState,
+  node: FolderIndexNode,
+  level: number,
+  lines: string[],
+): void {
+  const indent = '  '.repeat(Math.max(0, level));
+  const label = node.path === 'src' && level === 0 ? 'src (root)' : node.name;
+  const countSuffix = node.fileCount
+    ? ` — ${node.fileCount} file${node.fileCount > 1 ? 's' : ''}`
+    : '';
+
+  lines.push(`${indent}- [${label}](${node.path}/README.md)${countSuffix}`);
+
+  const childNames = resolveSortedFolderIndexChildNames(state, node);
+  for (const childName of childNames) {
+    renderFolderIndexNode(
+      state,
+      node.children.get(childName)!,
+      level + 1,
+      lines,
+    );
+  }
+}

package/scripts/generate-docs/output/generate-docs.output.ordering.utils.ts

@@ -0,0 +1,353 @@
+/*
+ * Resolves ordering and visibility policy for generated output.
+ *
+ * This chapter folds docs.order.json preferences together with the stable
+ * fallback heuristics used to order files, symbols, and folder-index entries.
+ */
+
+import * as path from 'path';
+
+import { FILE_SUMMARY_SYMBOL_NAME } from '../generate-docs.constants.js';
+import { getCachedDirectoryDocsOrderConfig } from '../generate-docs.order.js';
+import type {
+  FolderIndexNode,
+  GenerateDocsState,
+  RenderedSymbol,
+} from '../generate-docs.types.js';
+import {
+  warnForUnknownConfiguredDirectoryFiles,
+  warnForUnknownConfiguredDirectoryIntroFile,
+  warnForUnknownConfiguredFileSectionSymbols,
+  warnForUnknownConfiguredFolderIndexChildren,
+  warnForUnknownConfiguredHiddenFiles,
+  warnForUnknownConfiguredHiddenSymbols,
+} from './generate-docs.output.warnings.utils.js';
+
+/**
+ * Resolves directory file order using config-first ordering with stable
+ * fallback to the existing heuristic rank.
+ *
+ * After explicit `fileOrder` entries are placed, fallback ranking prefers:
+ * index-style entrypoints, files with promoted summaries, non-utility files,
+ * type-focused files, then shorter file names before lexical tie-breaks.
+ *
+ * @param state - Shared docs-generator state.
+ * @param directoryPath - Absolute directory path.
+ * @param fileSymbolMap - Symbols grouped by file within the directory.
+ * @returns Files sorted for one directory README.
+ */
+export function resolveSortedDirectoryFiles(
+  state: GenerateDocsState,
+  directoryPath: string,
+  fileSymbolMap: Map<string, RenderedSymbol[]>,
+): string[] {
+  const loadedConfig = getCachedDirectoryDocsOrderConfig(state, directoryPath);
+  const configuredFileOrder = loadedConfig?.config.fileOrder;
+
+  if (configuredFileOrder?.length) {
+    warnForUnknownConfiguredDirectoryFiles(
+      configuredFileOrder,
+      [...fileSymbolMap.keys()],
+      loadedConfig?.configPath,
+    );
+  }
+
+  const explicitFileOrderIndex = new Map(
+    (configuredFileOrder ?? []).map(
+      (fileName, index) => [fileName, index] as const,
+    ),
+  );
+
+  return [...fileSymbolMap.keys()].toSorted((leftFile, rightFile) => {
+    const leftExplicitOrder = explicitFileOrderIndex.get(
+      path.basename(leftFile),
+    );
+    const rightExplicitOrder = explicitFileOrderIndex.get(
+      path.basename(rightFile),
+    );
+
+    if (leftExplicitOrder !== undefined || rightExplicitOrder !== undefined) {
+      if (leftExplicitOrder === undefined) {
+        return 1;
+      }
+
+      if (rightExplicitOrder === undefined) {
+        return -1;
+      }
+
+      if (leftExplicitOrder !== rightExplicitOrder) {
+        return leftExplicitOrder - rightExplicitOrder;
+      }
+    }
+
+    return compareDirectoryReadmeFiles(leftFile, rightFile, fileSymbolMap);
+  });
+}
+
+/**
+ * Resolves visible files for one directory README after applying optional
+ * `hiddenFiles` filtering.
+ *
+ * @param state - Shared docs-generator state.
+ * @param directoryPath - Absolute directory path.
+ * @param sortedFiles - Already sorted directory files.
+ * @returns Visible files that should remain in the generated output.
+ */
+export function resolveVisibleDirectoryFiles(
+  state: GenerateDocsState,
+  directoryPath: string,
+  sortedFiles: readonly string[],
+): string[] {
+  const loadedConfig = getCachedDirectoryDocsOrderConfig(state, directoryPath);
+  const configuredHiddenFiles = loadedConfig?.config.hiddenFiles;
+
+  if (configuredHiddenFiles?.length) {
+    warnForUnknownConfiguredHiddenFiles(
+      configuredHiddenFiles,
+      sortedFiles,
+      loadedConfig?.configPath,
+    );
+  }
+
+  const hiddenFileNames = new Set(configuredHiddenFiles ?? []);
+  return sortedFiles.filter(
+    (filePath) => !hiddenFileNames.has(path.basename(filePath)),
+  );
+}
+
+/**
+ * Resolves hidden symbol names for one directory README.
+ *
+ * @param state - Shared docs-generator state.
+ * @param directoryPath - Absolute directory path.
+ * @param fileSymbolMap - Symbols grouped by file within the directory.
+ * @returns Hidden symbol-name set for render-time filtering.
+ */
+export function resolveHiddenDirectorySymbolNames(
+  state: GenerateDocsState,
+  directoryPath: string,
+  fileSymbolMap: Map<string, RenderedSymbol[]>,
+): ReadonlySet<string> {
+  const loadedConfig = getCachedDirectoryDocsOrderConfig(state, directoryPath);
+  const configuredHiddenSymbols = loadedConfig?.config.hiddenSymbols;
+
+  if (configuredHiddenSymbols?.length) {
+    warnForUnknownConfiguredHiddenSymbols(
+      configuredHiddenSymbols,
+      fileSymbolMap,
+      loadedConfig?.configPath,
+    );
+  }
+
+  return new Set(configuredHiddenSymbols ?? []);
+}
+
+/**
+ * Resolves top-level symbol order for one rendered file section.
+ *
+ * @param state - Shared docs-generator state.
+ * @param filePath - Absolute source file path.
+ * @param topLevelSymbols - Stable fallback-sorted top-level symbols.
+ * @returns Top-level symbols ordered for rendering.
+ */
+export function resolveSortedTopLevelFileSectionSymbols(
+  state: GenerateDocsState,
+  filePath: string,
+  topLevelSymbols: readonly RenderedSymbol[],
+): RenderedSymbol[] {
+  const directoryPath = path.dirname(filePath);
+  const loadedConfig = getCachedDirectoryDocsOrderConfig(state, directoryPath);
+  const configuredSymbolOrder =
+    loadedConfig?.config.symbolOrder?.[path.basename(filePath)];
+
+  if (!configuredSymbolOrder?.length) {
+    return [...topLevelSymbols];
+  }
+
+  warnForUnknownConfiguredFileSectionSymbols(
+    configuredSymbolOrder,
+    topLevelSymbols,
+    loadedConfig?.configPath,
+    filePath,
+  );
+
+  const explicitSymbolOrderIndex = new Map(
+    configuredSymbolOrder.map(
+      (symbolName, index) => [symbolName, index] as const,
+    ),
+  );
+
+  return [...topLevelSymbols].toSorted((leftSymbol, rightSymbol) => {
+    const leftExplicitOrder = explicitSymbolOrderIndex.get(leftSymbol.name);
+    const rightExplicitOrder = explicitSymbolOrderIndex.get(rightSymbol.name);
+
+    if (leftExplicitOrder !== undefined || rightExplicitOrder !== undefined) {
+      if (leftExplicitOrder === undefined) {
+        return 1;
+      }
+
+      if (rightExplicitOrder === undefined) {
+        return -1;
+      }
+
+      if (leftExplicitOrder !== rightExplicitOrder) {
+        return leftExplicitOrder - rightExplicitOrder;
+      }
+    }
+
+    return 0;
+  });
+}
+
+/**
+ * Resolves child-folder order for one folder-index node.
+ *
+ * @param state - Shared docs-generator state.
+ * @param node - Folder index node whose children should be ordered.
+ * @returns Sorted child folder names.
+ */
+export function resolveSortedFolderIndexChildNames(
+  state: GenerateDocsState,
+  node: FolderIndexNode,
+): string[] {
+  const loadedConfig = getCachedDirectoryDocsOrderConfig(
+    state,
+    node.sourceDirectoryPath,
+  );
+  const configuredFolderOrder = loadedConfig?.config.folderOrder;
+
+  if (configuredFolderOrder?.length) {
+    warnForUnknownConfiguredFolderIndexChildren(
+      configuredFolderOrder,
+      [...node.children.keys()],
+      loadedConfig?.configPath,
+      node.sourceDirectoryPath,
+    );
+  }
+
+  const explicitFolderOrderIndex = new Map(
+    (configuredFolderOrder ?? []).map(
+      (folderName, index) => [folderName, index] as const,
+    ),
+  );
+
+  return [...node.children.keys()].toSorted((leftName, rightName) => {
+    const leftExplicitOrder = explicitFolderOrderIndex.get(leftName);
+    const rightExplicitOrder = explicitFolderOrderIndex.get(rightName);
+
+    if (leftExplicitOrder !== undefined || rightExplicitOrder !== undefined) {
+      if (leftExplicitOrder === undefined) {
+        return 1;
+      }
+
+      if (rightExplicitOrder === undefined) {
+        return -1;
+      }
+
+      if (leftExplicitOrder !== rightExplicitOrder) {
+        return leftExplicitOrder - rightExplicitOrder;
+      }
+    }
+
+    return leftName.localeCompare(rightName);
+  });
+}
+
+/**
+ * Warns when `introFile` references a file missing from the current folder.
+ *
+ * @param state - Shared docs-generator state.
+ * @param directoryPath - Absolute directory path.
+ * @param configuredIntroFile - Configured intro file name.
+ * @param sortedFiles - Actual files in the current directory README.
+ * @returns Nothing.
+ */
+export function warnForConfiguredIntroFileIfNeeded(
+  state: GenerateDocsState,
+  directoryPath: string,
+  configuredIntroFile: string,
+  sortedFiles: readonly string[],
+): void {
+  const loadedConfig = getCachedDirectoryDocsOrderConfig(state, directoryPath);
+  warnForUnknownConfiguredDirectoryIntroFile(
+    configuredIntroFile,
+    sortedFiles,
+    loadedConfig?.configPath,
+  );
+}
+
+/**
+ * Ranks files within a directory README so entrypoints appear before helpers.
+ *
+ * The goal is not semantic perfection; it is a deterministic educational order
+ * that usually reads well for humans when no explicit `docs.order.json`
+ * override exists.
+ *
+ * @param filePath - Absolute source file path.
+ * @param fileSymbolMap - Symbols grouped by file within the directory.
+ * @returns Sort rank tuple.
+ */
+function rankFileForDirectoryReadme(
+  filePath: string,
+  fileSymbolMap: Map<string, RenderedSymbol[]>,
+): number[] {
+  const fileName = path.basename(filePath).toLowerCase();
+  const renderedSymbols = fileSymbolMap.get(filePath) ?? [];
+
+  const hasFileSummary = renderedSymbols.some((renderedSymbol) => {
+    if (
+      renderedSymbol.kind !== 'File' ||
+      renderedSymbol.name !== FILE_SUMMARY_SYMBOL_NAME
+    ) {
+      return false;
+    }
+
+    return Boolean(renderedSymbol.jsdoc.description?.trim());
+  });
+
+  const isIndexFile = fileName === 'index.ts';
+  const isTypesFile =
+    fileName.includes('.types.') || fileName.endsWith('.types.ts');
+  const isUtilityLike =
+    /(\.utils\.|\.export-|\.import-|\.internal\.|\.private\.)/i.test(fileName);
+  const isEntrypointLike = !isUtilityLike;
+
+  return [
+    isIndexFile ? 0 : 1,
+    hasFileSummary ? 0 : 1,
+    isEntrypointLike ? 0 : 1,
+    isTypesFile ? 0 : 1,
+    fileName.length,
+  ];
+}
+
+/**
+ * Compares two files using the existing directory README heuristic.
+ *
+ * @param leftFile - Left file path.
+ * @param rightFile - Right file path.
+ * @param fileSymbolMap - Symbols grouped by file within the directory.
+ * @returns Negative when left sorts before right.
+ */
+function compareDirectoryReadmeFiles(
+  leftFile: string,
+  rightFile: string,
+  fileSymbolMap: Map<string, RenderedSymbol[]>,
+): number {
+  const leftRank = rankFileForDirectoryReadme(leftFile, fileSymbolMap);
+  const rightRank = rankFileForDirectoryReadme(rightFile, fileSymbolMap);
+
+  for (
+    let index = 0;
+    index < Math.max(leftRank.length, rightRank.length);
+    index += 1
+  ) {
+    const leftValue = leftRank[index] ?? 0;
+    const rightValue = rightRank[index] ?? 0;
+    if (leftValue !== rightValue) {
+      return leftValue - rightValue;
+    }
+  }
+
+  return leftFile.localeCompare(rightFile);
+}