npm package: @flowspine/extractor
Description: Flowspine static DSL extractor (beta, not production-ready)
Latest version: 0.1.1-beta.20260407.1

﻿# @flowspine/extractor

Static extractor for Flowspine process definitions.

This package reads canonical Flowspine DSL from TypeScript source files and produces a machine-readable process catalog.

Use it when you need to:

- analyze existing process files
- build a process catalog in code
- inspect topology without executing business logic
- build custom tooling on top of Flowspine DSL

Do **not** use this package for:

- executing steps
- defining process logic
- validating/exporting through standard repository workflows when CLI already solves the task

For standard build/validate/export workflows, prefer `@flowspine/cli`.

---

## Installation

```bash
pnpm add @flowspine/extractor@beta
```

---

## What This Package Does

The extractor parses Flowspine process files and returns:

- extracted `processId`
- source file path
- process graph
- diagnostics when extraction is partial or non-canonical

This package is intentionally static.

It does **not** execute process code and it does **not** interpret arbitrary TypeScript semantics.

It works best when process files follow canonical Flowspine patterns.

---

## Mental Model

Use `@flowspine/extractor` when code needs to be treated as data.

Examples:

- “scan all process files in this repo”
- “generate a catalog for a custom viewer”
- “build analysis/reporting around Flowspine DSL”
- “inspect graph structure programmatically”

If the task is instead:

- define flow semantics → use `@flowspine/core`
- build/validate/export via normal dev workflow → use `@flowspine/cli`

---

## Main API

```ts
import { extractProcessesFromPaths } from "@flowspine/extractor";
```

### Example

```ts
import { extractProcessesFromPaths } from "@flowspine/extractor";

const result = extractProcessesFromPaths(["processes/**/*.ts"]);

console.log(result.generatedAt);
console.log(result.processes.length);

for (const process of result.processes) {
  console.log(process.processId, process.sourceFile);

  if (process.diagnostics.length > 0) {
    console.log("diagnostics:", process.diagnostics);
  }
}
```

---

## Output Shape

Each extracted process includes:

- `processId`
- `sourceFile`
- `graph`
- `diagnostics`

The result also includes:

- `generatedAt`
- `processes[]`

This makes the package useful as a low-level building block for custom automation and repository tooling.

---

## Canonical Patterns It Supports Best

The extractor is designed for canonical Flowspine DSL patterns such as:

```ts
import { defineProcess } from "@flowspine/core";

export default defineProcess("order-fulfillment", ({ step, branch, event, action, start, end, link, when }) => {
  const validateOrder = step("ValidateOrder");
  const paymentRequired = branch("PaymentRequired");
  const orderConfirmed = event("OrderConfirmed");

  start(validateOrder);
  link(validateOrder, paymentRequired);
  link(when(paymentRequired, "approved"), orderConfirmed);
  end(orderConfirmed);
});
```

Supported extraction patterns include:

- `defineProcess("id", ({ ... }) => { ... })`
- node declarations assigned to variables
- `step(...)`, `branch(...)`, `event(...)`, `action(...)`
- `link(from, to, condition?)`
- `link(when(branchNode, "condition"), target)`
- metadata passed as object literals with supported literal/object/array values

---

## Extraction Limitations

This package does **not** guarantee full extraction for dynamic or non-canonical code.

Extraction may fail partially or produce diagnostics if you use patterns such as:

- computed process IDs
- computed node IDs
- wrapped or indirect DSL calls
- dynamic metadata values
- non-literal branch conditions
- code structures that hide Flowspine calls from static analysis

In those cases, treat diagnostics as a signal that the source code is harder to analyze statically.

---

## Diagnostics

Diagnostics are warnings produced during extraction when the file is valid enough to inspect partially, but not canonical enough for clean extraction.

Examples of issues that may produce diagnostics:

- metadata is not an object literal
- metadata contains unsupported values
- DSL structure is too indirect for reliable parsing

If you need strict operational validation of a whole repository, run the output through `@flowspine/cli`.

---

## Typical Use Cases

### 1. Custom catalog generation

```ts
import { extractProcessesFromPaths } from "@flowspine/extractor";

const catalog = extractProcessesFromPaths([
  "processes/**/*.ts",
  "modules/**/processes/**/*.ts"
]);
```

### 2. Build your own reporting/tooling

```ts
import { extractProcessesFromPaths } from "@flowspine/extractor";

const result = extractProcessesFromPaths(["processes/**/*.ts"]);

const ids = result.processes.map((p) => p.processId);
console.log(ids);
```

### 3. Debug extractor compatibility

If a process file is not being extracted as expected, this package helps surface diagnostics before you move up to CLI-level workflows.

---

## When To Prefer CLI Instead

Prefer `@flowspine/cli` when you need:

- catalog file generation
- repository validation
- graph export
- watch mode
- standard team/CI workflow

The extractor is the lower-level programmatic layer.  
The CLI is the operational layer built on top of it.

---

## Related Packages

- `@flowspine/core`
- `@flowspine/cli`

## License

Apache 2.0

## Copyright

Copyright (c) 2026 Flowspine contributors.