Programmatic API

/**
 * Main class for analyzing JavaScript projects and managing dependencies
 * Extends EventEmitter for error handling and status updates
 */
class Autod extends EventEmitter {
  constructor(options: AutodOptions);
  prepare(): void;
  findJsFile(): FileDiscoveryResult;
  findDependencies(): DependencyDiscoveryResult;
  findVersions(): Promise<VersionResult>;
}

interface AutodOptions {
  /** Root path to analyze (required) */
  root: string;
  /** NPM registry URL (default: 'https://registry.npmmirror.com') */
  registry?: string;
  /** Directories/files to exclude from analysis */
  exclude?: string[];
  /** Directories/files to treat as test files */
  test?: string[];
  /** Additional dependencies to include */
  dep?: string[];
  /** Additional devDependencies to include */
  devdep?: string[];
  /** Custom version constraints for specific packages */
  semver?: Record<string, string>;
  /** Plugin module name for custom parsing */
  plugin?: string;
  /** Disable Babel ES6 transformation */
  notransform?: boolean;
}

const Autod = require('autod');

// Basic usage
const autod = new Autod({
  root: process.cwd()
});

// Advanced configuration
const autod = new Autod({
  root: '/path/to/project',
  registry: 'https://registry.npmjs.org',
  exclude: ['build', 'dist'],
  test: ['spec', 'tests'],
  dep: ['lodash'],
  devdep: ['mocha'],
  semver: {
    'lodash': '^4.0.0'
  }
});

// Error handling
autod.on('warn', (err) => {
  console.warn('Warning:', err.message);
});

/**
 * Creates a new Autod instance with specified configuration
 * @param options - Configuration object with root path and optional settings
 */
constructor(options: AutodOptions);

/**
 * Prepares and validates options, processes exclude/test patterns
 * Called automatically by constructor
 */
prepare(): void;

/**
 * Discovers JavaScript files in project, categorizes as source or test files
 * @returns Object containing arrays of JavaScript file paths
 */
findJsFile(): FileDiscoveryResult;

interface FileDiscoveryResult {
  /** Array of JavaScript source file paths */
  jsFiles: string[];
  /** Array of JavaScript test file paths */
  jsTestFiles: string[];
}

const autod = new Autod({ root: './my-project' });
const files = autod.findJsFile();

console.log('Source files:', files.jsFiles);
console.log('Test files:', files.jsTestFiles);

/**
 * Analyzes require/import statements to find used dependencies
 * @returns Object containing dependency arrays categorized by type
 */
findDependencies(): DependencyDiscoveryResult;

interface DependencyDiscoveryResult {
  /** Array of production dependency names */
  dependencies: string[];
  /** Array of development dependency names */
  devDependencies: string[];
}

const autod = new Autod({ root: './my-project' });
const deps = autod.findDependencies();

console.log('Production dependencies:', deps.dependencies);
console.log('Development dependencies:', deps.devDependencies);

/**
 * Fetches latest versions for discovered dependencies from npm registry
 * @returns Promise resolving to object with dependency versions
 */
findVersions(): Promise<VersionResult>;

interface VersionResult {
  /** Object mapping dependency names to their latest versions */
  dependencies: Record<string, string>;
  /** Object mapping devDependency names to their latest versions */
  devDependencies: Record<string, string>;
}

const autod = new Autod({ root: './my-project' });

async function updateDependencies() {
  const versions = await autod.findVersions();
  
  console.log('Latest dependency versions:');
  Object.entries(versions.dependencies).forEach(([name, version]) => {
    console.log(`  ${name}: ${version}`);
  });
  
  console.log('Latest devDependency versions:');
  Object.entries(versions.devDependencies).forEach(([name, version]) => {
    console.log(`  ${name}: ${version}`);
  });
}

updateDependencies().catch(console.error);

interface AutodInstance {
  /** Maps dependency names to files that require them */
  dependencyMap: Record<string, string[]>;
  /** Collection of errors encountered during processing */
  errors: Error[];
  /** Configuration options passed to constructor */
  options: AutodOptions;
}

/**
 * Event emitted when file read/transform errors occur
 * @event warn
 * @param error - Error object describing the issue
 */
autod.on('warn', (error: Error) => void);

/**
 * Plugin function signature for custom dependency parsing
 * @param filepath - Path to the file being parsed
 * @param content - File content as string
 * @param modules - Array of modules found by default parser
 * @returns Array of additional module names to include
 */
type PluginFunction = (
  filepath: string,
  content: string,
  modules: string[]
) => string[];

// my-autod-plugin.js
module.exports = function(filepath, content, modules) {
  // Custom logic to find additional dependencies
  const customModules = [];
  
  // Example: find dynamic requires
  const dynamicRequires = content.match(/require\(['"`]([^'"`]+)['"`]\)/g);
  if (dynamicRequires) {
    dynamicRequires.forEach(match => {
      const moduleName = match.match(/['"`]([^'"`]+)['"`]/)[1];
      customModules.push(moduleName);
    });
  }
  
  return modules.concat(customModules);
};

// Usage
const autod = new Autod({
  root: './my-project',
  plugin: 'my-autod-plugin'
});