tb_lint.core package

Submodules

tb_lint.core.base_linter module

Base class for linters

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Abstract base class for implementing linters

class tb_lint.core.base_linter.LinterResult(linter_name: str, files_checked: int = 0, files_failed: int = 0, violations: ~typing.List[~tb_lint.core.base_rule.RuleViolation] = <factory>, errors: ~typing.Dict[str, str] = <factory>)[source]

Bases: object

Results from running a linter on files

linter_name

Name of the linter that produced these results

Type:

str

files_checked

Number of files successfully checked

Type:

int

files_failed

Number of files that failed to parse/check

Type:

int

violations

List of all violations found

Type:

List[tb_lint.core.base_rule.RuleViolation]

errors

Dictionary mapping file paths to error messages

Type:

Dict[str, str]

linter_name: str
files_checked: int = 0
files_failed: int = 0
violations: List[RuleViolation]
errors: Dict[str, str]
property error_count: int

Count violations with ERROR severity

property warning_count: int

Count violations with WARNING severity

property info_count: int

Count violations with INFO severity

add_violation(violation: RuleViolation)[source]

Add a violation to the results

add_error(file_path: str, error_msg: str)[source]

Add a file-level error (e.g., parse failure)

__init__(linter_name: str, files_checked: int = 0, files_failed: int = 0, violations: ~typing.List[~tb_lint.core.base_rule.RuleViolation] = <factory>, errors: ~typing.Dict[str, str] = <factory>) → None
class tb_lint.core.base_linter.BaseLinter(config: dict | None = None)[source]

Bases: ABC

Abstract base class for all linters

Each linter implementation should: - Register rules it supports - Implement file checking logic - Return structured results

__init__(config: dict | None = None)[source]

Initialize linter with configuration

Parameters:

config – Configuration dictionary for the linter

abstract property name: str

Name of this linter

Returns:

String name of the linter

abstract property supported_extensions: List[str]

File extensions this linter can handle

Returns:

List of file extensions (e.g., [‘.sv’, ‘.svh’])

abstract prepare_context(file_path: str, file_content: str) → any | None[source]

Prepare any context needed for rule checking

This might include: - Parsing the file into an AST - Building symbol tables - Extracting metadata

Parameters:

  • file_path – Path to file being checked

  • file_content – Content of the file

Returns:

Context object to pass to rules, or None if preparation fails

lint_file(file_path: str) → LinterResult[source]

Lint a single file using all registered rules

Parameters:

file_path – Path to file to lint

Returns:

LinterResult containing all violations found

lint_files(file_paths: List[str]) → LinterResult[source]

Lint multiple files

Parameters:

file_paths – List of file paths to lint

Returns:

Combined LinterResult for all files

add_rule(rule: BaseRule)[source]

Add a rule to this linter

Parameters:

rule – Rule instance to add

tb_lint.core.base_rule module

Base class for linting rules

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Abstract base class that all linting rules must inherit from

class tb_lint.core.base_rule.RuleSeverity(value)[source]

Bases: Enum

Severity level for rule violations

ERROR = 'ERROR'
WARNING = 'WARNING'
INFO = 'INFO'
class tb_lint.core.base_rule.RuleViolation(file: str, line: int, column: int, severity: RuleSeverity, message: str, rule_id: str, context: str | None = None)[source]

Bases: object

Represents a single rule violation

file

Path to the file containing the violation

Type:

str

line

Line number where violation occurs

Type:

int

column

Column number (optional, depends on linter)

Type:

int

severity

Severity level of the violation

Type:

tb_lint.core.base_rule.RuleSeverity

message

Human-readable description of the violation

Type:

str

rule_id

Unique identifier for the rule

Type:

str

context

Additional context information (optional)

Type:

str | None

file: str
line: int
column: int
severity: RuleSeverity
message: str
rule_id: str
context: str | None = None
__init__(file: str, line: int, column: int, severity: RuleSeverity, message: str, rule_id: str, context: str | None = None) → None
class tb_lint.core.base_rule.BaseRule(config: dict | None = None)[source]

Bases: ABC

Abstract base class for all linting rules

Each rule should: - Have a unique rule_id - Implement the check() method - Define its default severity level - Provide a clear description

__init__(config: dict | None = None)[source]

Initialize rule with optional configuration

Parameters:

config – Optional configuration dictionary for the rule

abstract property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

abstract property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

abstract default_severity() → RuleSeverity[source]

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

abstract check(file_path: str, file_content: str, context: Any) → List[RuleViolation][source]

Check file for violations of this rule

Parameters:

  • file_path – Path to the file being checked

  • file_content – Content of the file as a string

  • context – Additional context (e.g., AST, parsed data)

Returns:

List of RuleViolation objects found

property enabled: bool

Check if rule is enabled

property severity: RuleSeverity

Get configured severity level

create_violation(file_path: str, line: int, message: str, column: int = 0, context: str | None = None) → RuleViolation[source]

Helper method to create a RuleViolation with this rule’s configuration

Parameters:

  • file_path – Path to file with violation

  • line – Line number

  • message – Violation message

  • column – Column number (default: 0)

  • context – Additional context (default: None)

Returns:

Configured RuleViolation object

tb_lint.core.config_manager module

Configuration management for linters

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Handles loading and managing hierarchical configuration for linters and rules.

Supports linking individual linter configurations from a root configuration.

class tb_lint.core.config_manager.ConfigManager(config_file: str | None = None)[source]

Bases: object

Manages hierarchical configuration loading and access

Supports: - Root configuration with linter enable/disable flags - Linked individual linter configuration files - JSON configuration files - Default configurations - Per-linter configurations - Per-rule configurations

Hierarchical Structure:

root_config.json: {

“linters”: {
“naturaldocs”: {

“enabled”: true, “config_file”: “configs/naturaldocs.json”

}, “verible”: {

“enabled”: false, “config_file”: “configs/verible.json”

}

}

}

__init__(config_file: str | None = None)[source]

Initialize configuration manager with hierarchical support

Parameters:

config_file – Path to root configuration file (JSON)

get_linter_config(linter_name: str) → dict[source]

Get configuration for a specific linter

Parameters:

linter_name – Name of the linter

Returns:

Configuration dictionary for the linter (merged from linked configs if present)

is_linter_enabled(linter_name: str) → bool[source]

Check if a linter is enabled in the configuration

Parameters:

linter_name – Name of the linter

Returns:

True)

Return type:

True if linter is enabled (default

get_rule_config(linter_name: str, rule_id: str) → dict[source]

Get configuration for a specific rule

Parameters:

  • linter_name – Name of the linter

  • rule_id – ID of the rule

Returns:

Configuration dictionary for the rule

is_rule_enabled(linter_name: str, rule_id: str) → bool[source]

Check if a rule is enabled

Parameters:

  • linter_name – Name of the linter

  • rule_id – ID of the rule

Returns:

True)

Return type:

True if rule is enabled (default

get_rule_severity(linter_name: str, rule_id: str, default: str = 'ERROR') → str[source]

Get severity level for a rule

Checks both ‘rules’ and ‘severity_levels’ sections for compatibility

Parameters:

  • linter_name – Name of the linter

  • rule_id – ID of the rule

  • default – Default severity if not configured

Returns:

Severity string (“ERROR”, “WARNING”, or “INFO”)

get_global_setting(key: str, default: Any | None = None) → Any[source]

Get a global setting

Parameters:

  • key – Setting key

  • default – Default value if not found

Returns:

Setting value or default

get_project_info() → dict[source]

Get project information

Returns:

Project info dictionary

save_config(output_path: str)[source]

Save current configuration to file

Parameters:

output_path – Path to save configuration

tb_lint.core.linter_registry module

Registry for managing multiple linters

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

Description: Central registry for discovering and managing linters

class tb_lint.core.linter_registry.LinterRegistry[source]

Bases: object

Central registry for linters

Provides: - Registration of linter classes - Discovery of available linters - Creation of linter instances

__init__()[source]

Initialize empty registry

register(linter_class: Type[BaseLinter])[source]

Register a linter class

Parameters:

linter_class – Class (not instance) of a linter

get_linter(name: str, config: dict | None = None) → BaseLinter | None[source]

Get an instance of a registered linter

Parameters:

  • name – Name of the linter

  • config – Configuration to pass to linter

Returns:

Linter instance or None if not found

get_all_linters(config: dict | None = None) → List[BaseLinter][source]

Get instances of all registered linters

Parameters:

config – Configuration to pass to all linters

Returns:

List of linter instances

list_linters() → List[str][source]

List names of all registered linters

Returns:

List of linter names

is_registered(name: str) → bool[source]

Check if a linter is registered

Parameters:

name – Linter name to check

Returns:

True if linter is registered

tb_lint.core.linter_registry.register_linter(linter_class: Type[BaseLinter])[source]

Decorator to register a linter class

Usage:

@register_linter class MyLinter(BaseLinter):

…

Parameters:

linter_class – Linter class to register

Returns:

The same linter class (for use as decorator)

tb_lint.core.linter_registry.get_registry() → LinterRegistry[source]

Get the global linter registry

Returns:

Global LinterRegistry instance

Module contents

Core framework for modular linting system

Company: Copyright (c) 2025 BTA Design Services

Licensed under the MIT License.

class tb_lint.core.BaseLinter(config: dict | None = None)[source]

Bases: ABC

Abstract base class for all linters

Each linter implementation should: - Register rules it supports - Implement file checking logic - Return structured results

__init__(config: dict | None = None)[source]

Initialize linter with configuration

Parameters:

config – Configuration dictionary for the linter

abstract property name: str

Name of this linter

Returns:

String name of the linter

abstract property supported_extensions: List[str]

File extensions this linter can handle

Returns:

List of file extensions (e.g., [‘.sv’, ‘.svh’])

abstract prepare_context(file_path: str, file_content: str) → any | None[source]

Prepare any context needed for rule checking

This might include: - Parsing the file into an AST - Building symbol tables - Extracting metadata

Parameters:

  • file_path – Path to file being checked

  • file_content – Content of the file

Returns:

Context object to pass to rules, or None if preparation fails

lint_file(file_path: str) → LinterResult[source]

Lint a single file using all registered rules

Parameters:

file_path – Path to file to lint

Returns:

LinterResult containing all violations found

lint_files(file_paths: List[str]) → LinterResult[source]

Lint multiple files

Parameters:

file_paths – List of file paths to lint

Returns:

Combined LinterResult for all files

add_rule(rule: BaseRule)[source]

Add a rule to this linter

Parameters:

rule – Rule instance to add

class tb_lint.core.LinterResult(linter_name: str, files_checked: int = 0, files_failed: int = 0, violations: ~typing.List[~tb_lint.core.base_rule.RuleViolation] = <factory>, errors: ~typing.Dict[str, str] = <factory>)[source]

Bases: object

Results from running a linter on files

linter_name

Name of the linter that produced these results

Type:

str

files_checked

Number of files successfully checked

Type:

int

files_failed

Number of files that failed to parse/check

Type:

int

violations

List of all violations found

Type:

List[tb_lint.core.base_rule.RuleViolation]

errors

Dictionary mapping file paths to error messages

Type:

Dict[str, str]

linter_name: str
files_checked: int = 0
files_failed: int = 0
violations: List[RuleViolation]
errors: Dict[str, str]
property error_count: int

Count violations with ERROR severity

property warning_count: int

Count violations with WARNING severity

property info_count: int

Count violations with INFO severity

add_violation(violation: RuleViolation)[source]

Add a violation to the results

add_error(file_path: str, error_msg: str)[source]

Add a file-level error (e.g., parse failure)

__init__(linter_name: str, files_checked: int = 0, files_failed: int = 0, violations: ~typing.List[~tb_lint.core.base_rule.RuleViolation] = <factory>, errors: ~typing.Dict[str, str] = <factory>) → None
class tb_lint.core.BaseRule(config: dict | None = None)[source]

Bases: ABC

Abstract base class for all linting rules

Each rule should: - Have a unique rule_id - Implement the check() method - Define its default severity level - Provide a clear description

__init__(config: dict | None = None)[source]

Initialize rule with optional configuration

Parameters:

config – Optional configuration dictionary for the rule

abstract property rule_id: str

Unique identifier for this rule (e.g., ‘ND_FILE_HDR_MISS’)

Returns:

String identifier for the rule

abstract property description: str

Human-readable description of what this rule checks

Returns:

String description of the rule

abstract default_severity() → RuleSeverity[source]

Default severity level for violations of this rule

Returns:

RuleSeverity enum value

abstract check(file_path: str, file_content: str, context: Any) → List[RuleViolation][source]

Check file for violations of this rule

Parameters:

  • file_path – Path to the file being checked

  • file_content – Content of the file as a string

  • context – Additional context (e.g., AST, parsed data)

Returns:

List of RuleViolation objects found

property enabled: bool

Check if rule is enabled

property severity: RuleSeverity

Get configured severity level

create_violation(file_path: str, line: int, message: str, column: int = 0, context: str | None = None) → RuleViolation[source]

Helper method to create a RuleViolation with this rule’s configuration

Parameters:

  • file_path – Path to file with violation

  • line – Line number

  • message – Violation message

  • column – Column number (default: 0)

  • context – Additional context (default: None)

Returns:

Configured RuleViolation object

class tb_lint.core.RuleViolation(file: str, line: int, column: int, severity: RuleSeverity, message: str, rule_id: str, context: str | None = None)[source]

Bases: object

Represents a single rule violation

file

Path to the file containing the violation

Type:

str

line

Line number where violation occurs

Type:

int

column

Column number (optional, depends on linter)

Type:

int

severity

Severity level of the violation

Type:

tb_lint.core.base_rule.RuleSeverity

message

Human-readable description of the violation

Type:

str

rule_id

Unique identifier for the rule

Type:

str

context

Additional context information (optional)

Type:

str | None

file: str
line: int
column: int
severity: RuleSeverity
message: str
rule_id: str
context: str | None = None
__init__(file: str, line: int, column: int, severity: RuleSeverity, message: str, rule_id: str, context: str | None = None) → None
class tb_lint.core.RuleSeverity(value)[source]

Bases: Enum

Severity level for rule violations

ERROR = 'ERROR'
WARNING = 'WARNING'
INFO = 'INFO'
class tb_lint.core.LinterRegistry[source]

Bases: object

Central registry for linters

Provides: - Registration of linter classes - Discovery of available linters - Creation of linter instances

__init__()[source]

Initialize empty registry

register(linter_class: Type[BaseLinter])[source]

Register a linter class

Parameters:

linter_class – Class (not instance) of a linter

get_linter(name: str, config: dict | None = None) → BaseLinter | None[source]

Get an instance of a registered linter

Parameters:

  • name – Name of the linter

  • config – Configuration to pass to linter

Returns:

Linter instance or None if not found

get_all_linters(config: dict | None = None) → List[BaseLinter][source]

Get instances of all registered linters

Parameters:

config – Configuration to pass to all linters

Returns:

List of linter instances

list_linters() → List[str][source]

List names of all registered linters

Returns:

List of linter names

is_registered(name: str) → bool[source]

Check if a linter is registered

Parameters:

name – Linter name to check

Returns:

True if linter is registered

tb_lint.core.get_registry() → LinterRegistry[source]

Get the global linter registry

Returns:

Global LinterRegistry instance

tb_lint.core.register_linter(linter_class: Type[BaseLinter])[source]

Decorator to register a linter class

Usage:

@register_linter class MyLinter(BaseLinter):

…

Parameters:

linter_class – Linter class to register

Returns:

The same linter class (for use as decorator)

class tb_lint.core.ConfigManager(config_file: str | None = None)[source]

Bases: object

Manages hierarchical configuration loading and access

Supports: - Root configuration with linter enable/disable flags - Linked individual linter configuration files - JSON configuration files - Default configurations - Per-linter configurations - Per-rule configurations

Hierarchical Structure:

root_config.json: {

“linters”: {
“naturaldocs”: {

“enabled”: true, “config_file”: “configs/naturaldocs.json”

}, “verible”: {

“enabled”: false, “config_file”: “configs/verible.json”

}

}

}

__init__(config_file: str | None = None)[source]

Initialize configuration manager with hierarchical support

Parameters:

config_file – Path to root configuration file (JSON)

get_linter_config(linter_name: str) → dict[source]

Get configuration for a specific linter

Parameters:

linter_name – Name of the linter

Returns:

Configuration dictionary for the linter (merged from linked configs if present)

is_linter_enabled(linter_name: str) → bool[source]

Check if a linter is enabled in the configuration

Parameters:

linter_name – Name of the linter

Returns:

True)

Return type:

True if linter is enabled (default

get_rule_config(linter_name: str, rule_id: str) → dict[source]

Get configuration for a specific rule

Parameters:

  • linter_name – Name of the linter

  • rule_id – ID of the rule

Returns:

Configuration dictionary for the rule

is_rule_enabled(linter_name: str, rule_id: str) → bool[source]

Check if a rule is enabled

Parameters:

  • linter_name – Name of the linter

  • rule_id – ID of the rule

Returns:

True)

Return type:

True if rule is enabled (default

get_rule_severity(linter_name: str, rule_id: str, default: str = 'ERROR') → str[source]

Get severity level for a rule

Checks both ‘rules’ and ‘severity_levels’ sections for compatibility

Parameters:

  • linter_name – Name of the linter

  • rule_id – ID of the rule

  • default – Default severity if not configured

Returns:

Severity string (“ERROR”, “WARNING”, or “INFO”)

get_global_setting(key: str, default: Any | None = None) → Any[source]

Get a global setting

Parameters:

  • key – Setting key

  • default – Default value if not found

Returns:

Setting value or default

get_project_info() → dict[source]

Get project information

Returns:

Project info dictionary

save_config(output_path: str)[source]

Save current configuration to file

Parameters:

output_path – Path to save configuration