nx 20.8.4 → 22.7.7

package/dist/src/native/index.d.ts

@@ -0,0 +1,672 @@
+/**
+ * Opaque branded types for native ExternalObject handles.
+ *
+ * These types are not constructed directly — they exist only to brand
+ * ExternalObject<T> so that different native handles are not interchangeable.
+ */
+
+interface NxDbConnection {
+  readonly __brand: unique symbol;
+}
+
+interface ParserArc {
+  readonly __brand: unique symbol;
+}
+
+interface WriterArc {
+  readonly __brand: unique symbol;
+}
+
+interface HashInstruction {
+  readonly __brand: unique symbol;
+}
+
+export declare class ExternalObject<T> {
+  readonly '': {
+    readonly '': unique symbol
+    [K: symbol]: T
+  }
+}
+export declare class AppLifeCycle {
+  constructor(tasks: Array<Task>, initiatingTasks: Array<string>, runMode: RunMode, pinnedTasks: Array<string>, tuiCliArgs: TuiCliArgs, tuiConfig: TuiConfig, titleText: string, workspaceRoot: string, taskGraph: TaskGraph)
+  startCommand(threadCount?: number | undefined | null): void
+  scheduleTask(task: Task): void
+  startTasks(tasks: Array<Task>, metadata: object): void
+  printTaskTerminalOutput(task: Task, status: string, output: string): void
+  endTasks(taskResults: Array<TaskResult>, metadata: object): void
+  endCommand(): void
+  __init(doneCallback: (() => unknown)): void
+  registerRunningTask(taskId: string, parserAndWriter: ExternalObject<[ParserArc, WriterArc]>): void
+  registerRunningTaskWithEmptyParser(taskId: string): void
+  appendTaskOutput(taskId: string, output: string, isPtyOutput: boolean): void
+  setTaskStatus(taskId: string, status: TaskStatus): void
+  setTaskTiming(taskId: string, startTime: number, endTime: number): void
+  registerForcedShutdownCallback(forcedShutdownCallback: (() => unknown)): void
+  __setCloudMessage(message: string): Promise<void>
+  setEstimatedTaskTimings(timings: Record<string, number>): void
+  registerRunningBatch(batchId: string, batchInfo: BatchInfo): void
+  appendBatchOutput(batchId: string, output: string): void
+  setBatchStatus(batchId: string, status: BatchStatus): void
+}
+
+export declare class ChildProcess {
+  getParserAndWriter(): ExternalObject<[ParserArc, WriterArc]>
+  getPid(): number
+  kill(signal?: NodeJS.Signals): void
+  onExit(callback: (message: string) => void): void
+  onOutput(callback: (message: string) => void): void
+  cleanup(): void
+}
+
+export declare class FileLock {
+  locked: boolean
+  constructor(lockFilePath: string)
+  unlock(): void
+  check(): boolean
+  wait(): Promise<void>
+  lock(): void
+}
+
+export declare class HashPlanInspector {
+  constructor(allWorkspaceFiles: ExternalObject<Array<FileData>>, projectFileMap: ExternalObject<Record<string, Array<FileData>>>, workspaceRoot: string)
+  /** @deprecated Use `inspectInputs()` instead for structured output. */
+  inspect(hashPlans: ExternalObject<Record<string, Array<HashInstruction>>>): Record<string, string[]>
+  /**
+   * Like `inspect()` but returns structured `HashInputs` objects instead of flat strings.
+   * Each `HashInstruction` is categorized into the appropriate bucket (files, runtime,
+   * environment, depOutputs, external). TsConfiguration is resolved to the root tsconfig
+   * file path. JsonFileSet is resolved to the matched JSON file paths (field/excludeField
+   * filters only affect hashing, not which files are reported as inputs).
+   * ProjectConfiguration is skipped for now. Cwd is skipped as it's ambient.
+   */
+  inspectInputs(hashPlans: ExternalObject<Record<string, Array<HashInstruction>>>): Record<string, HashInputs>
+}
+
+export declare class HashPlanner {
+  constructor(nxJson: NxJson, projectGraph: ExternalObject<ProjectGraph>)
+  getPlans(taskIds: Array<string>, taskGraph: TaskGraph): Record<string, string[]>
+  getPlansReference(taskIds: Array<string>, taskGraph: TaskGraph): ExternalObject<Record<string, Array<HashInstruction>>>
+}
+
+export declare class HttpRemoteCache {
+  constructor()
+  retrieve(hash: string, cacheDirectory: string): Promise<CachedResult | null>
+  store(hash: string, cacheDirectory: string, terminalOutput: string, code: number): Promise<boolean>
+}
+
+export declare class ImportResult {
+  file: string
+  sourceProject: string
+  dynamicImportExpressions: Array<string>
+  staticImportExpressions: Array<string>
+}
+
+export declare class NxCache {
+  cacheDirectory: string
+  constructor(workspaceRoot: string, cachePath: string, dbConnection: ExternalObject<NxDbConnection>, linkTaskDetails?: boolean | undefined | null, maxCacheSize?: number | undefined | null)
+  get(hash: string): CachedResult | null
+  /**
+   * Batch version of get() that fetches multiple cache entries in a single
+   * SQL query and reads terminal output files in parallel via Rayon.
+   */
+  getBatch(hashes: Array<string>): Array<CachedResult | undefined | null>
+  put(hash: string, terminalOutput: string, outputs: Array<string>, code: number): Array<string>
+  applyRemoteCacheResults(hash: string, result: CachedResult, outputs?: Array<string> | undefined | null): void
+  getTaskOutputsPath(hash: string): string
+  getCacheSize(): number
+  copyFilesFromCache(cachedResult: CachedResult, outputs: Array<string>): number
+  removeOldCacheRecords(): void
+  checkCacheFsInSync(): boolean
+}
+
+export declare class NxConsolePreferences {
+  constructor(homeDir: string)
+  getAutoInstallPreference(): boolean | null
+  setAutoInstallPreference(autoInstall: boolean): void
+}
+
+export declare class NxTaskHistory {
+  constructor(db: ExternalObject<NxDbConnection>)
+  recordTaskRuns(taskRuns: Array<TaskRun>): void
+  getFlakyTasks(hashes: Array<string>): Array<string>
+  getEstimatedTaskTimings(targets: Array<TaskTarget>): Record<string, number>
+}
+
+/**
+ * High-performance metrics collector for Nx tasks
+ * Thread-safe and designed for minimal overhead
+ */
+export declare class ProcessMetricsCollector {
+  /** Create a new ProcessMetricsCollector with default configuration */
+  constructor()
+  /**
+   * Start metrics collection
+   * Idempotent - safe to call multiple times
+   */
+  startCollection(): void
+  /**
+   * Stop metrics collection
+   * Returns true if collection was stopped, false if not running
+   */
+  stopCollection(): boolean
+  /**
+   * Get system information (CPU cores and total memory)
+   * This is separate from the collection interval and meant to be called imperatively
+   */
+  getSystemInfo(): SystemInfo
+  /** Register the main CLI process for metrics collection */
+  registerMainCliProcess(pid: number): void
+  /** Register a subprocess of the main CLI for metrics collection */
+  registerMainCliSubprocess(pid: number, alias?: string | undefined | null): void
+  /** Register the daemon process for metrics collection */
+  registerDaemonProcess(pid: number): void
+  /**
+   * Register a process for a specific task
+   * Automatically creates the task if it doesn't exist
+   */
+  registerTaskProcess(taskId: string, pid: number): void
+  /** Register a batch with multiple tasks sharing a worker */
+  registerBatch(batchId: string, taskIds: Array<string>, pid: number): void
+  /** Subscribe to push-based metrics notifications from TypeScript */
+  subscribe(callback: (err: Error | null, event: MetricsUpdate) => void): void
+}
+
+export declare class RunningTasksService {
+  constructor(db: ExternalObject<NxDbConnection>)
+  getRunningTasks(ids: Array<string>): Array<string>
+  addRunningTask(taskId: string): void
+  removeRunningTask(taskId: string): void
+}
+
+export declare class RustPseudoTerminal {
+  constructor()
+  runCommand(command: string, commandDir?: string | undefined | null, jsEnv?: Record<string, string> | undefined | null, execArgv?: Array<string> | undefined | null, quiet?: boolean | undefined | null, tty?: boolean | undefined | null, commandLabel?: string | undefined | null): ChildProcess
+  /**
+   * This allows us to run a pseudoterminal with a fake node ipc channel
+   * this makes it possible to be backwards compatible with the old implementation
+   */
+  fork(id: string, forkScript: string, pseudoIpcPath: string, commandDir: string | undefined | null, jsEnv: Record<string, string> | undefined | null, execArgv: Array<string> | undefined | null, quiet: boolean, commandLabel?: string | undefined | null): ChildProcess
+}
+
+export declare class TaskDetails {
+  constructor(db: ExternalObject<NxDbConnection>)
+  recordTaskDetails(tasks: Array<HashedTask>): void
+}
+
+export declare class TaskHasher {
+  constructor(workspaceRoot: string, projectGraph: ExternalObject<ProjectGraph>, projectFileMap: ExternalObject<Record<string, Array<FileData>>>, allWorkspaceFiles: ExternalObject<Array<FileData>>, tsConfig: Buffer, tsConfigPaths: Record<string, Array<string>>, rootTsconfigPath?: string | undefined | null, options?: HasherOptions | undefined | null)
+  /**
+   * Hash each task's instructions using the env map keyed by `task.id`.
+   * Every task in `hash_plans` must have an entry in `per_task_envs` —
+   * a missing id surfaces as an error rather than silently hashing
+   * against an empty env. Callers that want to hash all tasks against
+   * the same env should build `per_task_envs` by keying that env under
+   * every task id.
+   */
+  hashPlans(hashPlans: ExternalObject<Record<string, Array<HashInstruction>>>, perTaskEnvs: Record<string, Record<string, string>>, cwd: string, collectTaskInputs?: boolean | undefined | null): Record<string, HashDetails>
+}
+
+export declare class Watcher {
+  origin: string
+  /**
+   * Creates a new Watcher instance.
+   * Will always ignore directories from HARDCODED_IGNORE_PATTERNS plus
+   * watcher-specific patterns like vite/vitest timestamp files.
+   */
+  constructor(origin: string, additionalGlobs?: Array<string> | undefined | null, useIgnore?: boolean | undefined | null)
+  watch(callbackTsfn: (err: string | null, events: WatchEvent[]) => void): void
+  stop(): Promise<void>
+}
+
+export declare class WorkspaceContext {
+  workspaceRoot: string
+  constructor(workspaceRoot: string, cacheDir: string)
+  getWorkspaceFiles(projectRootMap: Record<string, string>): NxWorkspaceFiles
+  glob(globs: Array<string>, exclude?: Array<string> | undefined | null): Array<string>
+  /**
+   * Performs multiple glob pattern matches against workspace files in parallel
+   * @returns An array of arrays, where each inner array contains the file paths
+   * that matched the corresponding glob pattern in the input. The outer array maintains the same order
+   * as the input globs.
+   */
+  multiGlob(globs: Array<string>, exclude?: Array<string> | undefined | null): Array<Array<string>>
+  hashFilesMatchingGlobs(globGroups: Array<Array<string>>): Array<string>
+  hashFilesMatchingGlob(globs: Array<string>, exclude?: Array<string> | undefined | null): string
+  incrementalUpdate(updatedFiles: Array<string>, deletedFiles: Array<string>): Record<string, string>
+  updateProjectFiles(projectRootMappings: Record<string, string>, projectFiles: ExternalObject<Record<string, Array<FileData>>>, globalFiles: ExternalObject<Array<FileData>>, updatedFiles: Record<string, string>, deletedFiles: Array<string>): UpdatedWorkspaceFiles
+  allFileData(): Array<FileData>
+  getFilesInDirectory(directory: string): Array<string>
+}
+
+export interface BatchInfo {
+  executorName: string
+  taskIds: Array<string>
+}
+
+export declare const enum BatchStatus {
+  Running = 'Running',
+  Success = 'Success',
+  Failure = 'Failure'
+}
+
+export interface CachedResult {
+  code: number
+  terminalOutput?: string
+  outputsPath: string
+  size?: number
+}
+
+export declare function canInstallNxConsole(): Promise<boolean>
+
+export declare function canInstallNxConsoleForEditor(editor: SupportedEditor): Promise<boolean>
+
+export declare function closeDbConnection(connection: ExternalObject<NxDbConnection>): void
+
+export declare function connectToNxDb(cacheDir: string, dbName?: string | undefined | null): ExternalObject<NxDbConnection>
+
+export declare function copy(src: string, dest: string): number
+
+export interface DepsOutputsInput {
+  dependentTasksOutputFiles: string
+  transitive?: boolean
+}
+
+/**
+ * Detects which AI agent is running and returns its name.
+ * Returns None if no agent is detected or when running inside the Nx daemon.
+ * Filtering against supported agents should be done on the TypeScript side.
+ */
+export declare function detectAiAgent(): string | null
+
+export interface EnvironmentInput {
+  env: string
+}
+
+/**
+ * Canonical event dimension and metric names for GA4.
+ * TypeScript imports these from the native module instead of redefining the strings.
+ */
+export interface EventDimensions {
+  command: string
+  generatorName: string
+  packageName: string
+  packageVersion: string
+  duration: string
+  taskCount: string
+  projectCount: string
+  cachedTaskCount: string
+}
+
+export declare const enum EventType {
+  delete = 'delete',
+  update = 'update',
+  create = 'create'
+}
+
+export declare function expandOutputs(directory: string, entries: Array<string>): Array<string>
+
+export interface ExternalDependenciesInput {
+  externalDependencies: Array<string>
+}
+
+export interface ExternalNode {
+  packageName?: string
+  version: string
+  hash?: string
+}
+
+export interface FileData {
+  file: string
+  hash: string
+}
+
+export interface FileMap {
+  projectFileMap: Record<string, Array<FileData>>
+  nonProjectFiles: Array<FileData>
+}
+
+export interface FileSetInput {
+  fileset: string
+  dependencies?: boolean
+}
+
+export declare function findImports(projectFileMap: Record<string, Array<string>>): Array<ImportResult>
+
+/**
+ * Flush all pending telemetry data
+ * This should be called before process exit
+ */
+export declare function flushTelemetry(): void
+
+export declare function getBinaryTarget(): string
+
+export declare function getDefaultMaxCacheSize(cachePath: string): number
+
+/** Returns the canonical event dimension names. */
+export declare function getEventDimensions(): EventDimensions
+
+/**
+ * Batch version of get_files_for_outputs that processes multiple output
+ * entries in parallel using Rayon. Each entry is a list of output paths
+ * for a single task.
+ */
+export declare function getFilesForOutputsBatch(directory: string, entriesBatch: Array<Array<string>>): Array<Array<string>>
+
+/**
+ * If `workspace_root` is inside a git worktree, returns the main repo root.
+ * Returns `None` when already in the main repo (or not in a git repo at all).
+ */
+export declare function getMainWorktreeRoot(workspaceRoot: string): string | null
+
+export declare function getTransformableOutputs(outputs: Array<string>): Array<string>
+
+/**
+ * Group information - union of different process group types
+ * Use group_type to discriminate which optional fields are present
+ */
+export interface GroupInfo {
+  /** Type discriminator: MainCLI, Daemon, Task, or Batch */
+  groupType: GroupType
+  /** Display name for the group */
+  displayName: string
+  /** Unique ID for this group */
+  id: string
+  /** Task IDs in this batch (present for Batch groups) */
+  taskIds?: Array<string>
+}
+
+/** Group type discriminator */
+export declare const enum GroupType {
+  MainCLI = 'MainCLI',
+  MainCliSubprocesses = 'MainCliSubprocesses',
+  Daemon = 'Daemon',
+  DaemonSubprocesses = 'DaemonSubprocesses',
+  Task = 'Task',
+  Batch = 'Batch'
+}
+
+export declare function hashArray(input: Array<string | undefined | null>): string
+
+export interface HashDetails {
+  value: string
+  details: Record<string, string>
+  /** Structured inputs used for hashing (file patterns, env vars, etc.) */
+  inputs: HashInputs
+}
+
+export interface HashedTask {
+  hash: string
+  project: string
+  target: string
+  configuration?: string
+}
+
+export interface HasherOptions {
+  selectivelyHashTsConfig: boolean
+}
+
+export declare function hashFile(file: string): string | null
+
+/** NAPI-compatible struct for returning hash inputs to JavaScript */
+export interface HashInputs {
+  /** Expanded file paths that were used as inputs */
+  files: Array<string>
+  /** Runtime commands */
+  runtime: Array<string>
+  /** Environment variable names */
+  environment: Array<string>
+  /** Dependent task outputs */
+  depOutputs: Array<string>
+  /** External dependencies */
+  external: Array<string>
+}
+
+/**
+ * Initialize telemetry using a DB connection.
+ * Gets/creates the session ID from the DB, stores the connection
+ * for persisting session refreshes on flush, and returns the session ID
+ * so the caller can set it as an env var for child processes.
+ * Used by CLI and daemon.
+ */
+export declare function initializeTelemetry(connection: ExternalObject<NxDbConnection>, workspaceId: string, userId: string, nxVersion: string, packageManagerName: string, packageManagerVersion: string | undefined | null, nodeVersion: string, osArch: string, osPlatform: string, osRelease: string, isCi: boolean, isNxCloud: boolean): string
+
+/**
+ * Initialize telemetry with a pre-fetched session ID.
+ * No DB connection — used by plugin workers that inherit the
+ * session ID from their parent process via env var.
+ */
+export declare function initializeTelemetryWithSessionId(sessionId: string, workspaceId: string, userId: string, nxVersion: string, packageManagerName: string, packageManagerVersion: string | undefined | null, nodeVersion: string, osArch: string, osPlatform: string, osRelease: string, isCi: boolean, isNxCloud: boolean): void
+
+export interface InputsInput {
+  input: string
+  dependencies?: boolean
+  projects?: string | Array<string>
+}
+
+export declare function installNxConsole(): Promise<boolean>
+
+export declare function installNxConsoleForEditor(editor: SupportedEditor): Promise<boolean>
+
+export const IS_WASM: boolean
+
+/**
+ * Detects if the current process is being run by an AI agent.
+ * Always returns false when running inside the Nx daemon, since the daemon
+ * is a long-lived process that should not inherit AI agent behavior from
+ * the client that connected to it.
+ */
+export declare function isAiAgent(): boolean
+
+export declare function isEditorInstalled(editor: SupportedEditor): Promise<boolean>
+
+export interface JsonInput {
+  json: string
+  fields?: Array<string>
+  excludeFields?: Array<string>
+}
+
+export declare function logDebug(message: string): void
+
+/** Combined metadata for groups and processes */
+export interface Metadata {
+  /** Group-level metadata */
+  groups: Record<string, GroupInfo>
+  /** Process-level metadata (keyed by PID as string for NAPI compatibility) */
+  processes: Record<string, ProcessMetadata>
+}
+
+/** Metrics update sent every collection cycle */
+export interface MetricsUpdate {
+  timestamp: number
+  processes: Array<ProcessMetrics>
+  metadata: Metadata
+}
+
+/** Stripped version of the NxJson interface for use in rust */
+export interface NxJson {
+  namedInputs?: Record<string, Array<InputsInput | string | FileSetInput | RuntimeInput | EnvironmentInput | ExternalDependenciesInput | DepsOutputsInput | WorkingDirectoryInput | JsonInput>>
+}
+
+export interface NxWorkspaceFiles {
+  projectFileMap: Record<string, Array<FileData>>
+  globalFiles: Array<FileData>
+  externalReferences?: NxWorkspaceFilesExternals
+}
+
+/**
+ * Return-only struct (Rust → JS). `object_from_js = false` skips generating
+ * `FromNapiValue` since `External<T>` only supports `FromNapiRef` in napi v3.
+ */
+export interface NxWorkspaceFilesExternals {
+  projectFiles: ExternalObject<Record<string, Array<FileData>>>
+  globalFiles: ExternalObject<Array<FileData>>
+  allWorkspaceFiles: ExternalObject<Array<FileData>>
+}
+
+export declare function parseTaskStatus(stringStatus: string): TaskStatus
+
+/** Process metadata (static, doesn't change during process lifetime) */
+export interface ProcessMetadata {
+  ppid: number
+  name: string
+  command: string
+  exePath: string
+  cwd: string
+  alias?: string
+  groupId: string
+  isRoot: boolean
+}
+
+/** Process metrics (dynamic, changes every collection) */
+export interface ProcessMetrics {
+  pid: number
+  cpu: number
+  memory: number
+}
+
+export interface Project {
+  root: string
+  namedInputs?: Record<string, Array<InputsInput | string | FileSetInput | RuntimeInput | EnvironmentInput | ExternalDependenciesInput | DepsOutputsInput | WorkingDirectoryInput | JsonInput>>
+  tags?: Array<string>
+  targets: Record<string, Target>
+}
+
+export interface ProjectGraph {
+  nodes: Record<string, Project>
+  dependencies: Record<string, Array<string>>
+  externalNodes: Record<string, ExternalNode>
+}
+
+export declare function remove(src: string): void
+
+export declare function restoreTerminal(): void
+
+export declare const enum RunMode {
+  RunOne = 0,
+  RunMany = 1
+}
+
+export interface RuntimeInput {
+  runtime: string
+}
+
+export declare const enum SupportedEditor {
+  VSCode = 0,
+  VSCodeInsiders = 1,
+  Cursor = 2,
+  Windsurf = 3,
+  JetBrains = 4,
+  Unknown = 5
+}
+
+/** System information (static system-level data) */
+export interface SystemInfo {
+  cpuCores: number
+  totalMemory: number
+}
+
+export interface Target {
+  executor?: string
+  inputs?: Array<InputsInput | string | FileSetInput | RuntimeInput | EnvironmentInput | ExternalDependenciesInput | DepsOutputsInput | WorkingDirectoryInput | JsonInput>
+  outputs?: Array<string>
+  options?: string
+  configurations?: string
+  parallelism?: boolean
+}
+
+export interface Task {
+  id: string
+  target: TaskTarget
+  outputs: Array<string>
+  projectRoot?: string
+  startTime?: number
+  endTime?: number
+  continuous?: boolean
+}
+
+export interface TaskGraph {
+  roots: Array<string>
+  tasks: Record<string, Task>
+  dependencies: Record<string, Array<string>>
+  continuousDependencies: Record<string, Array<string>>
+}
+
+export interface TaskResult {
+  task: Task
+  status: string
+  code: number
+  terminalOutput?: string
+}
+
+export interface TaskRun {
+  hash: string
+  status: string
+  code: number
+  start: number
+  end: number
+}
+
+export declare const enum TaskStatus {
+  Success = 0,
+  Failure = 1,
+  Skipped = 2,
+  LocalCacheKeptExisting = 3,
+  LocalCache = 4,
+  RemoteCache = 5,
+  NotStarted = 6,
+  InProgress = 7,
+  Shared = 8,
+  Stopped = 9
+}
+
+export interface TaskTarget {
+  project: string
+  target: string
+  configuration?: string
+}
+
+export declare function testOnlyTransferFileMap(projectFiles: Record<string, Array<FileData>>, nonProjectFiles: Array<FileData>): NxWorkspaceFilesExternals
+
+/** Track an event using the global telemetry instance */
+export declare function trackEvent(eventName: string, parameters?: Record<string, string> | undefined | null): void
+
+/** Track a page view using the global telemetry instance */
+export declare function trackPageView(pageTitle: string, pageLocation?: string | undefined | null, parameters?: Record<string, string> | undefined | null): void
+
+/**
+ * Transfer the project graph from the JS world to the Rust world, so that we can pass the project graph via memory quicker
+ * This wont be needed once the project graph is created in Rust
+ */
+export declare function transferProjectGraph(projectGraph: ProjectGraph): ExternalObject<ProjectGraph>
+
+export interface TuiCliArgs {
+  targets?: string[] | undefined
+  tuiAutoExit?: boolean | number | undefined
+}
+
+export interface TuiConfig {
+  autoExit?: boolean | number | undefined
+  suppressHints?: boolean
+}
+
+export interface UpdatedWorkspaceFiles {
+  fileMap: FileMap
+  externalReferences: NxWorkspaceFilesExternals
+}
+
+export declare function validateOutputs(outputs: Array<string>): void
+
+export interface WatchEvent {
+  path: string
+  type: EventType
+}
+
+export interface WorkingDirectoryInput {
+  workingDirectory: string
+}
+
+/** Public NAPI error codes that are for Node */
+export declare const enum WorkspaceErrors {
+  ParseError = 'ParseError',
+  Generic = 'Generic'
+}