# @probitas/discover

> Version: 0.4.0

Scenario file discovery utilities for Probitas.

This package provides utilities for discovering scenario files (`.probitas.ts`)
from file paths and directories. It supports glob patterns for flexible file
matching and is used internally by the CLI to find scenarios to execute.

## Links

- [GitHub Repository](https://github.com/probitas-test/probitas)
- [@probitas/probitas](https://jsr.io/@probitas/probitas) - Main package (recommended for most users)

## Related Packages

| Package | Description |
|---------|-------------|
| [@probitas/core](https://jsr.io/@probitas/core) | Load discovered files with `loadScenarios` |
| [@probitas/cli](https://jsr.io/@probitas/cli) | CLI that uses this discovery |

## Core Function

- {@linkcode discoverScenarioFiles} - Discover scenario files from paths

## Configuration Types

- {@linkcode DiscoverOptions} - Options for customizing discovery behavior
- {@linkcode DiscoverProgress} - Progress information during discovery

## Default Behavior

By default, the discovery function:
- Searches for files matching `**\/*.probitas.ts` in directories
- Returns direct file paths as-is (no pattern matching)
- Returns absolute paths sorted alphabetically

## Permissions

Requires `--allow-read` permission to read the file system.


## Interfaces

### `DiscoverProgress`

```typescript
interface DiscoverProgress
```

Progress information during file discovery.

Provides real-time feedback about the discovery process, useful for
displaying progress in CLI applications.

**Properties:**

- `currentPath`: `string` — The directory or file path currently being processed.
- `filesFound`: `number` — Total number of matching files found so far.

---

### `DiscoverOptions`

```typescript
interface DiscoverOptions
```

Options for discovering scenario files.

Controls which files are included or excluded when scanning directories.

**Properties:**

- `includes?`: `readonly string[]` — Glob patterns for files to include when scanning directories.

Uses standard glob syntax with `**` for recursive matching.

- `excludes?`: `readonly string[]` — Glob patterns for files to exclude.

- `onProgress?`: `(progress: DiscoverProgress) => unknown` — Callback invoked during discovery to report progress.

Called when processing each path (file or directory) and after
completing pattern matching within a directory. This allows CLI
applications to display real-time progress feedback.


---

## Functions

### `discoverScenarioFiles`

```typescript
async function discoverScenarioFiles(
  paths: readonly string[],
  _: unknown,
): Promise<string[]>
```

Discover scenario files from paths (files or directories).

Handles two input types:
- **File path**: Returns the file directly (no pattern matching)
- **Directory path**: Scans using include/exclude patterns


**Parameters:**

- `paths`: `readonly string[]` — - Array of file paths or directory paths to scan
- `_`: `unknown`

**Returns:** `Promise<string[]>`

Array of absolute file paths, sorted alphabetically


**Example:**

Discover from directories
```ts
import { discoverScenarioFiles } from "@probitas/discover";

// Use default patterns (*.probitas.ts)
const files = await discoverScenarioFiles(["./tests", "./integration"]);
```

Discover with custom patterns
```ts
const files = await discoverScenarioFiles(["./src"], {
  includes: ["**\/*.test.ts", "**\/*.spec.ts"],
  excludes: ["**\/__fixtures__/**"]
});
```

Mixed files and directories
```ts
const files = await discoverScenarioFiles([
  "./tests/",           // Scan directory
  "./smoke.probitas.ts" // Include specific file
]);
```

---

## Related Links

### This Package

- [`DiscoverProgress`](https://probitas-test.github.io/documents/api/discover#DiscoverProgress)

### Built-in Types

- [`Promise`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)

---

*Last updated: 2026-01-12*