okflint.scanner module

Shared Markdown file scanning primitives for OKF.

class okflint.scanner.Header(level, text, line)

Bases: object

Represents an H1 or H2 heading in a file.

level: int

line: int

text: str

class okflint.scanner.MarkdownLink(text, target, is_external, broken)

Bases: object

Represents a markdown link [text](url) in a file.

broken: bool

is_external: bool

target: str

text: str

class okflint.scanner.WikiLink(raw, target, alias, section, resolved_path, broken, ambiguous)

Bases: object

Represents an Obsidian wikilink [[…]] in a file.

alias: str | None

ambiguous: bool

broken: bool

raw: str

resolved_path: str | None

section: str | None

target: str

okflint.scanner.blank_code_spans(content)

Blank out fenced code blocks and inline code spans.

Allows link extraction without false positives inside code zones. Replaces code zone content with spaces while preserving character positions (line numbers unchanged). An unclosed fence at end of file is treated as open until EOF.

Parameters:

content (str) – Raw file body (after frontmatter).

Return type:

str

Returns:

Content with code blocks masked by spaces.

okflint.scanner.build_file_index(roots, exclude_patterns=None)

Index all .md files under a list of roots for wikilink resolution.

Parameters:

• roots (list[Path]) – List of roots to index.

• exclude_patterns (dict[Path, list[str]] | None) – Optional per-root exclusion globs. Files matching any pattern for their root are omitted from the index.

Return type:

dict[str, list[str]]

Returns:

Dictionary stem → list of paths relative to the first root.

okflint.scanner.extract_headers(content)

Extract H1 and H2 headings with their line number in the body.

Must receive content pre-blanked via blank_code_spans to ignore # characters inside code blocks.

Parameters:

content (str) – File body with code blocks masked.

Return type:

list[Header]

Returns:

List of Header (levels 1 and 2 only).

okflint.scanner.extract_markdown_links(content, file_path, bundle_path, other_roots=None)

Extract [text](target) markdown links and verify internal links.

Targets carrying a URI scheme (RFC 3986), e.g. http://, mailto:, tel:, obsidian://, are absolute URIs and are not checked.

Parameters:

• content (str) – Markdown file body.

• file_path (Path) – Absolute path of the current file.

• bundle_path (Path) – Root owning the current file (tried first for absolute paths).

• other_roots (list[Path] | None) – Remaining roots of a multi-root base. An absolute path not found under bundle_path is tried against each of these, in order, before being reported broken.

Return type:

list[MarkdownLink]

Returns:

List of MarkdownLink.

okflint.scanner.extract_wikilinks(content, vault_index)

Extract and resolve [[…]] wikilinks in the content.

Parameters:

• content (str) – Markdown file body.

• vault_index (dict[str, list[str]]) – Vault index (stem → relative paths).

Return type:

list[WikiLink]

Returns:

List of WikiLink with broken/ambiguous status.

okflint.scanner.parse_frontmatter(content)

Extract the YAML frontmatter from a markdown file.

Parameters:

content (str) – Full file content.

Return type:

tuple[dict[str, Any] | None, str]

Returns:

Tuple (frontmatter_dict, body) or (None, content) if absent or invalid.