Library Definition Management

/**
 * Represents a Flow library definition
 */
interface LibDef {
  /** Package name (e.g., "lodash", "@types/react") */
  pkgName: string;
  /** Package version string (e.g., "4.x.x", "^16.0.0") */
  pkgVersionStr: string;
  /** Path to configuration file or null if none */
  configPath: string | null;
  /** Flow version compatibility object */
  flowVersion: FlowVersion;
  /** Flow version as string representation */
  flowVersionStr: string;
  /** File system path to the definition file */
  path: string;
  /** Array of paths to test files for this definition */
  testFilePaths: Array<string>;
}

/** Regular expression for identifying test files */
const TEST_FILE_NAME_RE: RegExp;

/**
 * Get library definitions from a definitions directory
 * Recursively scans directory structure for valid library definitions
 * @param defsDir - Directory containing library definitions
 * @returns Promise resolving to array of discovered LibDef objects
 */
function getLibDefs(defsDir: string): Promise<Array<LibDef>>;

/**
 * Parse repository directory item into library definition
 * @param dirPath - Path to directory item to parse
 * @param dirName - Name of the directory
 * @returns Parsed repository item or null if invalid
 */
function parseRepoDirItem(dirPath: string, dirName: string): any;

import { getLibDefs } from "flow-typed";

// Get all definitions from flow-typed directory
const localDefs = await getLibDefs("./flow-typed");

// Get definitions from cache repository
const cacheDefs = await getLibDefs("/path/to/cache/definitions");

/**
 * Get cached library definitions from the flow-typed repository
 * Updates cache if needed before returning definitions
 * @param verbose - Optional verbose output stream for logging
 * @returns Promise resolving to array of cached LibDef objects
 */
function getCacheLibDefs(verbose?: any): Promise<Array<LibDef>>;

import { getCacheLibDefs } from "flow-typed";

// Get all cached definitions
const allDefs = await getCacheLibDefs();

// Get with verbose logging
const allDefs = await getCacheLibDefs(process.stdout);

/**
 * Filter library definitions based on search criteria
 * @param defs - Array of library definitions to filter
 * @param filter - Filter configuration object
 * @returns Filtered array of library definitions matching criteria
 */
function filterLibDefs(
  defs: Array<LibDef>,
  filter: FilterOptions
): Array<LibDef>;

interface FilterOptions {
  /** Type of filtering to perform */
  type: 'fuzzy' | 'exact';
  /** Search term to match against package names */
  term: string;
  /** Optional Flow version string for compatibility filtering */
  flowVersionStr?: string;
}

import { filterLibDefs, getCacheLibDefs } from "flow-typed";

const allDefs = await getCacheLibDefs();

// Fuzzy search for React-related packages
const reactDefs = filterLibDefs(allDefs, {
  type: 'fuzzy',
  term: 'react',
  flowVersionStr: 'v0.83.0'
});

// Exact match for specific package
const lodashDef = filterLibDefs(allDefs, {
  type: 'exact',
  term: 'lodash'
});

/**
 * Clone git repository into specified directory
 * @param repoUrl - URL of the git repository to clone
 * @param targetDir - Directory to clone repository into
 * @returns Promise resolving when clone is complete
 */
function cloneInto(repoUrl: string, targetDir: string): Promise<void>;

/**
 * Rebase repository to latest mainline branch
 * @param repoDir - Directory containing the git repository
 * @returns Promise resolving when rebase is complete
 */
function rebaseRepoMainline(repoDir: string): Promise<void>;

/**
 * Get environment definitions for Flow
 * @param flowVersion - Flow version to get definitions for
 * @returns Promise resolving to array of environment definitions
 */
function getEnvDefs(flowVersion: FlowVersion): Promise<Array<any>>;

/**
 * Find specific environment definition
 * @param envDefs - Array of environment definitions
 * @param name - Name of environment definition to find
 * @returns Environment definition or null if not found
 */
function findEnvDef(envDefs: Array<any>, name: string): any | null;

/**
 * Get version hash for environment definition
 * @param envDef - Environment definition to get hash for
 * @returns Promise resolving to version hash string
 */
function getEnvDefVersionHash(envDef: any): Promise<string>;

/**
 * Find the root directory of a Flow project
 * Searches for .flowconfig file up the directory tree
 * @param startDir - Directory to start searching from
 * @returns Promise resolving to Flow project root path or null
 */
function findFlowRoot(startDir?: string): Promise<string | null>;

/**
 * Get flow-typed configuration for a project
 * @param rootDir - Root directory of the project
 * @returns Promise resolving to FtConfig object
 */
function getFtConfig(rootDir?: string): Promise<FtConfig>;

interface FtConfig {
  rootDir: string;
  cacheDir: string;
  libdefDir: string;
  [key: string]: any;
}

definitions/
├── npm/
│   ├── package-name_v1.x.x/
│   │   ├── flow_v0.83.x-/
│   │   │   ├── package-name_v1.x.x.js
│   │   │   └── test_package-name.js
│   │   └── flow_v0.85.x-/
│   │       ├── package-name_v1.x.x.js
│   │       └── test_package-name.js
│   └── another-package_v2.x.x/
└── environment/
    ├── dom_v0.0.x/
    └── node_v0.0.x/

// @flow

declare module 'package-name' {
  declare export default any;
  declare export function method(): any;
}

declare module 'package-name/submodule' {
  declare export var exported: string;
}