firecrown.fctools.symbol_reference_checker

Validate Firecrown symbol references in Quarto (.qmd) files.

This tool extracts all inline code spans (backticks) from tutorial files and validates that any Firecrown symbol references actually exist in the codebase. It checks: - Fully-qualified names (e.g., firecrown.likelihood.SourceSystematic) - Partial module paths (e.g., firecrown.likelihood) - Unqualified class/function names (e.g., Updatable)

Attributes

app

Functions

extract_code_spans(content)

Extract all inline code spans from markdown content.

check_qmd_file(file_path, symbol_map[, ...])

Check a .qmd file for invalid Firecrown symbol references.

main([directory, symbol_map_file, exclude_pattern, ...])

Validate Firecrown symbol references in Quarto (.qmd) files.

Module Contents

firecrown.fctools.symbol_reference_checker.app
firecrown.fctools.symbol_reference_checker.extract_code_spans(content)[source]

Extract all inline code spans from markdown content.

Parameters:

content (str) – The markdown content to parse

Returns:

List of (line_number, code_text) tuples

Return type:

list[tuple[int, str]]

firecrown.fctools.symbol_reference_checker.check_qmd_file(file_path, symbol_map, external_symbols=None, exclude_pattern=None)[source]

Check a .qmd file for invalid Firecrown symbol references.

Parameters:

  • file_path (pathlib.Path) – Path to the Quarto (.qmd) file to check

  • symbol_map (dict[str, str]) – Dictionary mapping valid symbols to their URLs

  • external_symbols (set[str] | None) – Set of allowed external symbols

  • exclude_pattern (str | None) – Optional regex pattern for symbols to exclude from checking

Returns:

List of error messages for invalid symbol references

Return type:

list[str]

firecrown.fctools.symbol_reference_checker.main(directory=typer.Argument(..., help='The directory containing .qmd files to check', exists=True), symbol_map_file=typer.Argument(..., help='Path to the JSON file containing the symbol map', exists=True), exclude_pattern=typer.Option(None, help='Regex pattern for symbols to exclude from checking'), external_symbols_file=typer.Option(None, help='Path to text file containing allowed external symbols (one per line)'))[source]

Validate Firecrown symbol references in Quarto (.qmd) files.

Extracts all inline code spans (backticks) from tutorial files and validates that any Firecrown symbol references actually exist in the codebase.

Checks: - Fully-qualified names (e.g., firecrown.likelihood.SourceSystematic) - Partial module paths (e.g., firecrown.likelihood) - Unqualified class/function names (e.g., Updatable)

Exit codes:

0: No invalid symbol references found 1: Invalid symbols found or input error

Parameters:

  • directory (pathlib.Path)

  • symbol_map_file (pathlib.Path)

  • exclude_pattern (str | None)

  • external_symbols_file (pathlib.Path | None)

Return type:

None