feat: add structural Gherkin (.feature) document extraction

[hopstreax]

Summary

This PR adds support for Gherkin (.feature) files to Graphify's document extraction pipeline.

Previously, .feature files were not recognized by classify_file(), causing them to be skipped during detection and never reach extraction. As a result, BDD specification files produced no graph nodes.

This change classifies .feature files as documents and introduces a lightweight structural extractor that models the document hierarchy using Graphify's existing document schema.

Changes

• Add .feature to DOC_EXTENSIONS so Gherkin files are classified as DOCUMENT.

• Implement a lightweight line-by-line Gherkin extractor.

• Register the extractor in the extraction dispatch table.

• Extract structural document nodes for:

  • Feature
  • Background
  • Scenario
  • Scenario Outline
  • Examples

• Emit standard contains edges between structural elements.

• Ignore executable step lines (Given, When, Then, And, But, *) to keep the graph focused on document structure.

• Preserve the existing Graphify node and edge schema without introducing new graph concepts.

• Add regression tests covering:

  • document classification
  • extractor dispatch
  • structural hierarchy
  • duplicate title handling
  • comments
  • empty titles
  • Scenario Outline / Examples ownership
  • outline state regression

Design

The implementation follows the existing Markdown extractor philosophy:

• lightweight line-by-line parsing
• no parser generators
• no additional dependencies
• standard document nodes
• standard contains relationships

This keeps Gherkin support consistent with Graphify's existing document extraction architecture.

Verification

Automated

• uv run pytest tests/test_detect.py -k gherkin
• uv run pytest tests/test_extract.py -k gherkin
• uv run ruff check

Manual

Verified using the standard Graphify update pipeline:

uv run python -m graphify update repro-2349

The generated graph correctly contains:

login.feature
└── Feature: Login
    └── Scenario: Successful login

while correctly excluding step keywords (Given, When, Then, etc.).

Fixes

Closes #2349.

[graphify-labs]

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

Graphify reviewed this change.

Looks safe to merge — no coupling regressions and no blocking issues, checked against the code graph (not a self-assessment).

---

Graphify review — findings

This PR adds support for Gherkin .feature files to the extraction pipeline. It registers .feature as a document extension in detect.py, introduces a new graphify/extractors/gherkin.py extractor that parses Gherkin keywords (Feature, Background, Scenario, Scenario Outline, Examples) into structural nodes with contains edges reflecting their hierarchy, and wires this extractor into the dispatch table in extract.py. It also adds accompanying tests covering classification, dispatch, and various extraction scenarios. The surface area is the file-type detection extension set, the extract dispatcher/imports, one new extractor module, and additions to the detect and extract test suites.

Worth a look

• Duplicate-name Examples node collides and misattaches parent edge — graphify/extractors/gherkin.py:78 · Escalate · medium
  • agreed by 2 of 2 members but NOT verified (no proof, no reproducing execution) — consensus is not a verdict; needs human review

Analysis details — impact, health, verification

Impact & health

Graphify review

Impact — 1916 functions depend on the 909 functions this change touches.

Health — this change adds coupling hotspots:

• worse: _get_extractor() — 25 callers, 6 callees
• worse: classify_file() — 43 callers, 3 callees

Verification — 1916 functions in the blast radius were not formally verified this run (proofs are advisory here).

Gate & verification

graphify gate

PASS — objectively clean (no health regressions, tests not run — proofs not run this pass (advisory)). Grounded, not self-assessed.

Advisory (not blocking):

• verification_scope: 1750 function(s) in the blast radius were not formally verified this run

· 2 more finding(s) on lines outside this diff (see the check run).