tessl/npm-documentation

A comprehensive JavaScript documentation generator that transforms JSDoc-annotated source code into human-readable documentation in multiple formats

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Input Processing

Name: tessl/npm-documentation
Author: tessl

File dependency resolution and input expansion functionality that determines which files to include in documentation generation based on import/require relationships and configuration options.

Capabilities

Expand Inputs Function

Resolves file dependencies and expands input file lists based on configuration settings for comprehensive documentation coverage.

/**
 * Resolve dependencies for given input files based on configuration
 * @param indexes - Files to process (string or array of strings)
 * @param config - Configuration object containing processing options
 * @returns Promise resolving to array of resolved file paths
 */
function expandInputs(
  indexes: string[] | string,
  config: Config
): Promise<string[]>;

interface Config {
  /** Whether to avoid dependency parsing */
  shallow?: boolean;
  /** Whether to document only exported values */
  documentExported?: boolean;
  /** String regex/glob patterns for external modules to include */
  external?: string[];
  /** Additional file extensions to treat as JavaScript */
  extension?: string | string[];
  /** Parse additional file extensions */
  parseExtension?: string[];
  /** Files and directories to exclude */
  exclude?: string[];
  /** Base directory for file resolution */
  cwd?: string;
  /** Module resolution configuration */
  resolve?: ResolveConfig;
}

interface ResolveConfig {
  /** Additional module directories */
  modules?: string[];
  /** File extensions to resolve */
  extensions?: string[];
  /** Module alias mappings */
  alias?: { [key: string]: string };
}

Usage Examples:

import { expandInputs } from "documentation";

// Basic input expansion with dependency resolution
const files = await expandInputs(['index.js'], {
  shallow: false,
  external: ['lodash', 'express']
});
console.log(files); // ['index.js', 'lib/utils.js', 'lib/api.js', ...]

// Shallow processing - no dependency resolution
const files = await expandInputs(['src/'], {
  shallow: true
});

// Document only exported values
const files = await expandInputs(['lib/index.js'], {
  documentExported: true,
  shallow: false
});

// Custom file extensions
const files = await expandInputs(['src/'], {
  extension: ['ts', 'tsx', 'vue'],
  parseExtension: ['ts', 'tsx']
});

Dependency Resolution Strategies

The input processing system supports two main strategies for file discovery:

Deep Dependency Analysis (Default)

Analyzes import/require statements to build a complete dependency graph:

const files = await expandInputs(['index.js'], {
  shallow: false
});

This approach:

Follows all import and require statements
Includes transitively imported files
Respects module resolution rules
Handles both ES modules and CommonJS
Supports dynamic imports when statically analyzable

Shallow Processing

Processes only explicitly specified files without dependency resolution:

const files = await expandInputs(['src/**/*.js'], {
  shallow: true
});

This approach:

Only includes files matching the glob patterns
Does not follow import/require statements
Faster processing for large codebases
Useful for documenting specific modules

External Module Handling

Configure which external dependencies to include in documentation:

const files = await expandInputs(['index.js'], {
  external: [
    'lodash.*',      // Include all lodash submodules
    'express',       // Include express module
    '@company/.*'    // Include all @company scoped packages
  ]
});

External module patterns support:

Exact matches: 'lodash' matches only lodash
Glob patterns: 'lodash.*' matches lodash.get, lodash.set, etc.
Scoped packages: '@company/.*' matches all packages in the @company scope
Regular expressions: Full regex support for complex patterns

File Extension Support

Control which file types are processed as JavaScript:

const files = await expandInputs(['src/'], {
  extension: ['ts', 'tsx', 'vue', 'jsx'],
  parseExtension: ['ts', 'tsx']
});

Configuration options:

extension: File extensions to treat as JavaScript
parseExtension: Extensions requiring special parsing (TypeScript, JSX)
Default extensions: js, es6, jsx, mjs

Exclusion Patterns

Exclude specific files or directories from processing:

const files = await expandInputs(['src/'], {
  exclude: [
    'src/test/**',
    'src/**/*.test.js',
    'src/legacy/**',
    'node_modules/**'
  ]
});

Exclusion supports:

Glob patterns: Standard glob syntax for flexible matching
Directory exclusion: Exclude entire directory trees
File pattern exclusion: Exclude files by name patterns
Default exclusions: node_modules, .git, common build directories

Module Resolution

Configure how modules are resolved for dependency analysis:

const files = await expandInputs(['src/'], {
  resolve: {
    modules: ['node_modules', 'src', 'lib'],
    extensions: ['.js', '.ts', '.tsx', '.json'],
    alias: {
      '@utils': './src/utils',
      '@components': './src/components'
    }
  }
});

Resolution configuration:

modules: Directories to search for modules
extensions: File extensions to try when resolving imports
alias: Path aliases for cleaner imports

Working Directory

Set the base directory for file resolution:

const files = await expandInputs(['lib/'], {
  cwd: '/path/to/project',
  shallow: false
});

The working directory affects:

Relative path resolution: Base for resolving relative imports
Glob pattern matching: Starting point for glob expansion
Output file paths: Base for generated file paths

Export-Only Documentation

Focus documentation on only exported values:

const files = await expandInputs(['lib/index.js'], {
  documentExported: true
});

This mode:

Documents only explicitly exported functions, classes, and constants
Ignores internal implementation details
Ideal for library API documentation
Reduces documentation noise

Performance Considerations

Input processing performance can be optimized based on project characteristics:

Large Codebases

// Use shallow processing for faster builds
const files = await expandInputs(['src/'], {
  shallow: true,
  exclude: ['src/test/**', 'src/**/*.test.js']
});

Selective Documentation

// Document only specific modules
const files = await expandInputs(['src/api.js', 'src/utils.js'], {
  shallow: true
});

Incremental Builds

// Process only changed files
const changedFiles = getChangedFiles(); // Custom implementation
const files = await expandInputs(changedFiles, {
  shallow: true
});

Error Handling

Input processing handles various error conditions gracefully:

try {
  const files = await expandInputs(['nonexistent.js'], {});
} catch (error) {
  if (error.code === 'ENOENT') {
    console.error('Input file not found');
  } else if (error.message.includes('Cannot resolve module')) {
    console.error('Module resolution failed');
  }
}

Common error scenarios:

Missing files: Input files that don't exist
Module resolution failures: Unresolvable imports
Permission errors: Inaccessible files or directories
Circular dependencies: Detected and handled appropriately

Integration with Build Systems

Input processing integrates well with various build tools:

// Webpack-style configuration
const files = await expandInputs(['src/index.js'], {
  resolve: {
    modules: ['node_modules', 'src'],
    alias: {
      '@': './src'
    }
  }
});

// TypeScript project
const files = await expandInputs(['src/'], {
  extension: ['ts', 'tsx'],
  parseExtension: ['ts', 'tsx'],
  resolve: {
    extensions: ['.ts', '.tsx', '.js']
  }
});

Install with Tessl CLI