09_architecture_decisions.adoc - Architecture Decisions

Architecture Decisions

This chapter contains all architecture decisions for the AsciiDoc Linter project. Each decision is documented in a separate file and included here.

ADR 1: Rule Base Class Design

ADR-001-rule-base-class.adoc - Rule Base Class Design Decision

ADR 1: Rule Base Class Design

Status

Accepted

Context

We need a flexible and extensible way to implement different linting rules for AsciiDoc documents.

Decision

We will use an abstract base class Rule with a defined interface that all concrete rules must implement.

Consequences

  • Positive

    • Consistent interface for all rules

    • Easy to add new rules

    • Clear separation of concerns

    • Simplified testing through common interface

  • Negative

    • Additional abstraction layer

    • Slight performance overhead

ADR 2: Finding Data Structure

ADR-002-finding-data-structure.adoc - Finding Data Structure Decision

ADR 2: Finding Data Structure

Status

Accepted

Context

Rule violations need to be reported in a consistent and informative way.

Decision

We will use a Finding data class with fields for message, severity, position, rule ID, and context.

Consequences

  • Positive

    • Structured error reporting

    • Rich context for violations

    • Consistent error format

  • Negative

    • More complex than simple string messages

    • Requires more memory for storing findings

ADR 3: Rule Implementation Strategy

ADR-003-rule-implementation-strategy.adoc - Rule Implementation Strategy Decision

ADR 3: Rule Implementation Strategy

Status

Accepted

Context

Rules need to process AsciiDoc content and identify violations efficiently.

Decision

Each rule will process the content line by line, using regular expressions for pattern matching.

Consequences

  • Positive

    • Simple implementation

    • Good performance for most cases

    • Easy to understand and maintain

  • Negative

    • Limited context awareness

    • May miss some complex patterns

    • Regular expressions can become complex

ADR 4: Test Strategy

ADR-004-test-strategy.adoc - Test Strategy Decision

ADR 4: Test Strategy

Status

Accepted

Context

Rules need to be thoroughly tested to ensure reliable operation.

Decision

Each rule will have its own test class with multiple test methods covering various scenarios.

Consequences

  • Positive

    • High test coverage

    • Clear test organization

    • Easy to add new test cases

  • Negative

    • More maintenance effort

    • Longer test execution time

ADR 5: Table Processing Strategy

ADR-005-table-processing-strategy.adoc - Table Processing Strategy Decision

ADR 5: Table Processing Strategy

Status

Proposed

Context

Table processing in AsciiDoc documents requires complex parsing and validation: * Tables can contain various content types (text, lists, blocks) * Cell extraction needs to handle multi-line content * Column counting must be reliable * List detection in cells must be accurate

Current implementation has issues: * Cell extraction produces incorrect results * List detection generates false positives * Column counting is unreliable

Decision

We will implement a new table processing strategy:

  1. Two-Pass Parsing

    • First pass: Identify table boundaries and structure

    • Second pass: Extract and validate cell content

  2. Cell Content Model

    • Create a dedicated TableCell class

    • Track content type (text, list, block)

    • Maintain line number information

  3. List Detection

    • Use state machine for list recognition

    • Track list context across cell boundaries

    • Validate list markers against AsciiDoc spec

  4. Column Management

    • Count columns based on header row

    • Validate all rows against header

    • Handle empty cells explicitly

Technical Details
class TableCell:
    def __init__(self):
        self.content = []
        self.content_type = None
        self.start_line = None
        self.end_line = None
        self.has_list = False
        self.list_level = 0

class TableRow:
    def __init__(self):
        self.cells = []
        self.line_number = None
        self.is_header = False

class TableProcessor:
    def first_pass(self, lines):
        # Identify table structure
        pass

    def second_pass(self, table_lines):
        # Extract cell content
        pass

    def detect_lists(self, cell):
        # Use state machine for list detection
        pass
Consequences

  • Positive

    • More accurate cell extraction

    • Reliable list detection

    • Better error reporting

    • Maintainable code structure

    • Clear separation of concerns

  • Negative

    • More complex implementation

    • Slightly higher memory usage

    • Additional processing overhead

    • More code to maintain

Implementation Plan

  1. Phase 1: Core Structure

    • Implement TableCell and TableRow classes

    • Basic two-pass parsing

    • Unit tests for basic functionality

  2. Phase 2: Content Processing

    • List detection state machine

    • Content type recognition

    • Error context collection

  3. Phase 3: Validation

    • Column counting

    • Structure validation

    • Comprehensive test suite

Validation

Success criteria: * All current table-related tests pass * Cell extraction matches expected results * List detection has no false positives * Column counting is accurate * Memory usage remains within limits

Related Diagrams
Table Processing Class Diagram
Table Processing Sequence

ADR 6: Severity Standardization

ADR-006-severity-standardization.adoc - Severity Standardization Decision

ADR 6: Severity Standardization

Status

Proposed

Context

Current implementation has inconsistent severity level handling: * Mixed case usage (ERROR vs error) * Inconsistent severity levels across rules * No clear guidelines for severity assignment

Decision

We will standardize severity handling:

  1. Severity Levels

    • ERROR: Issues that must be fixed

    • WARNING: Issues that should be reviewed

    • INFO: Suggestions for improvement

  2. Implementation

    • Use lowercase for internal representation

    • Provide case-sensitive display methods

    • Add severity level documentation

  3. Migration

    • Update all existing rules

    • Add validation in base class

    • Update tests to use new standard

Consequences

  • Positive

    • Consistent severity handling

    • Clear guidelines for new rules

    • Better user experience

  • Negative

    • Need to update existing code

    • Potential backward compatibility issues

Related Diagrams
Severity State Diagram

ADR 7: Rule Registry Enhancement

ADR-007-rule-registry-enhancement.adoc - Rule Registry Enhancement Decision

ADR 7: Rule Registry Enhancement

Status

Proposed

Context

Current rule registry implementation lacks: * Test coverage * Clear registration mechanism * Version handling * Rule dependency management

Decision

We will enhance the rule registry:

  1. Registration

    • Add explicit registration decorator

    • Support rule dependencies

    • Add version information

  2. Management

    • Add rule enabling/disabling

    • Support rule groups

    • Add configuration validation

  3. Testing

    • Add comprehensive test suite

    • Test all registration scenarios

    • Test configuration handling

Consequences

  • Positive

    • Better rule management

    • Clear registration process

    • Improved testability

  • Negative

    • More complex implementation

    • Additional maintenance overhead

Related Diagrams
Rule Registry Components
Rule Registration Flow