@topogram/extractor-step-functions-workflows

Package-backed Topogram extractor for local AWS Step Functions workflow definitions.

Status: current Audience: extractor authors and maintainers Use when: you need to extract review-only workflow candidates from Amazon States Language files.

This extractor reads local Amazon States Language JSON or YAML files and returns review-only Topogram workflow candidates. It does not call AWS APIs, read cloud credentials, inspect execution history, mutate source files, or write canonical topo/** records.

Author Loop

npm install
npm test
npm run docs:rag:check
TOPOGRAM_CLI=/path/to/topogram/engine/src/cli.js npm run check
npm run release:preflight

npm run check runs:

• adapter unit tests;
• docs/RAG checks;
• topogram extractor check .;
• package-backed extraction against fixtures/basic-source;
• topogram extract plan;
• topogram query extract-plan;
• topogram adopt --list;
• fixture mutation guard.

Extracted Evidence

The extractor scans checked-in local files such as:

• *.asl.json
• *.asl.yaml
• *.asl.yml
• states.json
• states.yaml
• state-machine.json

It emits:

• workflow_definitions
• workflow_states
• workflow_transitions

State candidates come from States keys. Transition candidates come from Next, Default, Choices, Catch, and visible branch starts. State type metadata carries initial, terminal, and error where it can be inferred statically.

Boundaries

V1 is intentionally local and deterministic:

• no AWS SDK calls;
• no credential loading;
• no deployed state-machine discovery;
• no execution-history inspection;
• no IAM inference;
• no source mutation;
• no adoption semantics in the package.

CloudFormation, CDK, SAM, Serverless, Terraform, and deployed AWS discovery are future scope unless a package can recover the embedded ASL definition deterministically.

Topogram core owns normalization, persistence, reports, extract plans, adoption, and canonical workflow records.