# Options

The primary tuning surface is `excelminer.AnalysisOptions`.

## Feature flags

- `include_vba` (default: `True`)
  - Detect embedded VBA projects in macro-enabled OOXML workbooks (`.xlsm/.xltm/.xlam`).
  - Emits `vba_project` nodes with module text when available.

- `include_connections` (default: `True`)
  - Extract workbook connections (OOXML; and via COM when enabled).

- `include_powerquery` (default: `True`)
  - Extract Power Query query definitions from `xl/queries/*.xml` when present.
  - Emits `powerquery` nodes and `uses_source` edges when sources are detected in M.

- `include_pivots` (default: `True`)
  - Extract pivot tables + caches (best-effort) from OOXML parts.
  - Emits `pivot_table` and `pivot_cache` nodes.

- `include_defined_names` (default: `True`)
  - Extract defined names (OOXML; and via COM when enabled).

- `include_formulas` (default: `False`)
  - Extract formula text into `formula_cell` nodes.
  - Formula evaluation is not performed.

- `include_cells` (default: `False`)
  - Enables “value block / used-range” extraction via the calamine backend (if installed).
  - This flag does not create formula nodes; formulas are controlled by `include_formulas`.

## Formula scanning controls

These options only apply when `include_formulas=True`.

- `formula_sheet_names: list[str] | None`
  - Restrict formula scanning to specific worksheet names.
  - Mutually exclusive with `formula_sheet_indexes`.

- `formula_sheet_indexes: list[int] | None`
  - Restrict formula scanning by workbook order (1-based indexes).
  - Mutually exclusive with `formula_sheet_names`.

- `formula_scan_mode: "auto" | "xml" | "openpyxl"` (default: `"auto"`)
  - `auto`: use XML formula-only scanning for large sheets, openpyxl scanning for smaller ones.
  - `xml`: always scan formulas directly from worksheet XML (skips non-formula cells).
  - `openpyxl`: always use openpyxl scanning.

- `formula_large_sheet_cells: int | None` (default: `10_000`)
  - When `formula_scan_mode="auto"`, sheets with more than this many cells in the used range
    switch to XML formula-only scanning.

- `formula_skip_pivot_cells: bool` (default: `True`)
  - Skip formulas that fall inside pivot table ranges (when pivot metadata is available).

- `include_com` (default: `False`)
  - Explicit opt-in for the Excel COM backend.
  - Intended for Windows environments with Microsoft Excel installed.
  - For `.xlsx/.xlsm/.xltx/.xltm`, COM requires `include_com=True`.
  - For legacy formats (`.xls/.xlsb/.xlt`), the COM backend can run without `include_com=True` because OOXML parsing may not apply.
    (You still need Windows + Excel + `excelminer[com]` installed.)

- `post_analysis_distillation` (default: `False`)
  - Optional post-analysis step that can condense/refine extracted artifacts.
  - Current distillations are best-effort and may add summary nodes (e.g., `formula_group`) and prune unused artifacts (e.g., unused defined names).
  - Use `distillation_workers` to control parallelism for this step.

## Limits

These options exist to keep extraction bounded for very large workbooks:

- `max_sheets: int | None`
  - Limits the number of worksheets scanned by backends that iterate sheets.

- `max_cells_per_sheet: int | None`
  - Used by formula scanners and used-range scanning as a cap.

- `max_rows_per_sheet: int | None`
  - Hard cap on rows scanned per worksheet by formula extraction.

- `max_cols_per_sheet: int | None`
  - Hard cap on columns scanned per worksheet by formula extraction.

- `row_chunk_size` / `column_chunk_size`
  - Chunk sizing for formula scanning loops in the openpyxl backend.

- `sample_rows_per_block` / `sample_cols_per_block`
  - Used by the calamine backend to keep `cell_block.sample` small.

## Parallelism and logging

- `formula_decomposition_workers: int | None`
  - Controls parallelism for formula dependency extraction (openpyxl backend).

- `distillation_workers: int | None`
  - Controls parallelism for the post-analysis distillation step.

- `log_callback: Callable[[str], None] | None`
  - Optional callback for progress/issues from the analysis orchestrator.
