Flow Version Management

/**
 * Represents a specific Flow version with major, minor, patch components
 */
interface FlowSpecificVer {
  /** Major version number */
  major: number;
  /** Minor version number or 'x' for wildcard */
  minor: number | 'x';
  /** Patch version number or 'x' for wildcard */
  patch: number | 'x';
  /** Pre-release identifier or 'x' for wildcard, null if none */
  prerel: string | 'x' | null;
}

/**
 * Union type representing different Flow version specifications
 */
type FlowVersion =
  | { kind: 'all' }
  | { kind: 'specific', ver: FlowSpecificVer }
  | { 
      kind: 'ranged', 
      upper: FlowSpecificVer | null, 
      lower: FlowSpecificVer | null 
    };

/**
 * Parse Flow version directory string into FlowVersion object
 * @param verStr - Version string to parse (e.g., "v0.83.x", "v0.80.0-v0.85.x")
 * @returns Parsed FlowVersion object
 */
function parseDirString(verStr: string): FlowVersion;

/**
 * Parse a specific Flow version string
 * @param verStr - Specific version string (e.g., "v0.83.0")
 * @returns Parsed FlowSpecificVer object
 */
function parseFlowSpecificVer(verStr: string): FlowSpecificVer;

import { parseDirString, parseFlowSpecificVer } from "flow-typed";

// Parse single version
const singleVersion = parseDirString("v0.83.x");
// Result: { kind: 'specific', ver: { major: 0, minor: 83, patch: 'x', prerel: null } }

// Parse version range
const rangeVersion = parseDirString("v0.80.0-v0.85.x");
// Result: { kind: 'ranged', lower: {...}, upper: {...} }

// Parse specific version
const specificVer = parseFlowSpecificVer("v0.83.0");
// Result: { major: 0, minor: 83, patch: 0, prerel: null }

/**
 * Determine the Flow version for a project directory
 * Checks .flowconfig, package.json, and other sources
 * @param cwd - Current working directory containing the project
 * @param flowVersionArg - Optional explicit Flow version override
 * @returns Promise resolving to specific FlowVersion object
 */
function determineFlowSpecificVersion(
  cwd: string,
  flowVersionArg?: string
): Promise<{kind: 'specific', ver: FlowSpecificVer}>;

/**
 * Find specific Flow version from package configuration
 * @param startingPath - Starting path to search for Flow version
 * @returns Promise resolving to FlowSpecificVer
 */
function findFlowSpecificVer(startingPath: string): Promise<FlowSpecificVer>;

import { determineFlowSpecificVersion } from "flow-typed";
// Note: findFlowSpecificVer is available from flow-typed/lib/npm/npmProjectUtils

// Determine Flow version for current project
const version = await determineFlowSpecificVersion(process.cwd());

// Determine with explicit version override
const version = await determineFlowSpecificVersion(
  "/path/to/project", 
  "v0.83.0"
);

/**
 * Compare two Flow versions in ascending order
 * @param a - First FlowVersion to compare
 * @param b - Second FlowVersion to compare
 * @returns Number: negative if a < b, 0 if equal, positive if a > b
 */
function compareFlowVersionAsc(a: FlowVersion, b: FlowVersion): number;

/**
 * Check if all provided versions are disjoint (non-overlapping)
 * @param vers - Array of FlowVersions to check
 * @returns Boolean indicating if all versions are disjoint
 */
function disjointVersionsAll(vers: Array<FlowVersion>): boolean;

import { compareFlowVersionAsc, disjointVersionsAll } from "flow-typed";

const v1 = parseDirString("v0.83.0");
const v2 = parseDirString("v0.85.0");

// Compare versions
const comparison = compareFlowVersionAsc(v1, v2); // -1 (v1 < v2)

// Check if versions overlap
const versions = [
  parseDirString("v0.80.x"),
  parseDirString("v0.85.x")
];
const areDisjoint = disjointVersionsAll(versions); // true

/**
 * Convert FlowVersion to directory string format
 * @param ver - FlowVersion object to convert
 * @returns Directory string representation (e.g., "v0.83.x")
 */
function toDirString(ver: FlowVersion): string;

/**
 * Convert FlowVersion to semver-compatible string
 * @param ver - FlowVersion object to convert
 * @returns Semver string representation (e.g., "0.83.0")
 */
function toSemverString(ver: FlowVersion): string;

import { toDirString, toSemverString, parseDirString } from "flow-typed";

const version = parseDirString("v0.83.x");

// Convert to directory string
const dirStr = toDirString(version); // "v0.83.x"

// Convert to semver string
const semverStr = toSemverString(version); // "0.83.0"

// Determine project Flow version
const flowVersion = await determineFlowSpecificVersion('./');
const versionStr = toSemverString(flowVersion);
console.log(`Using Flow version: ${versionStr}`);

// Filter definitions by Flow version compatibility
const compatibleDefs = libdefs.filter(def => {
  return compareFlowVersionAsc(def.flowVersion, targetVersion) <= 0;
});

// Check if definition versions overlap
const hasOverlap = !disjointVersionsAll([
  parseDirString("v0.80.x"),
  parseDirString("v0.83.x")
]);