AsciiDoc Linter Architecture Documentation

Introduction and Goals

Requirements Overview

The AsciiDoc Linter is a tool designed to ensure consistent formatting and structure in AsciiDoc documents. It helps teams maintain high-quality documentation by enforcing style rules and best practices.

Key requirements include:

  • Validate AsciiDoc heading structure

  • Ensure consistent formatting

  • Provide clear error messages

  • Easy integration into existing workflows

  • Extensible rule system

Quality Goals

Priority Quality Goal Motivation

1

Extensibility

The system must be easily extensible with new rules to accommodate different documentation standards and requirements.

2

Reliability

The linter must provide consistent and accurate results to maintain user trust.

3

Usability

Error messages must be clear and actionable, helping users fix documentation issues efficiently.

4

Performance

The linter should process documents quickly to maintain a smooth workflow.

5

Maintainability

The code must be well-structured and documented to facilitate future enhancements.

Stakeholders

Role/Name Contact Expectations

Documentation Writers

various

* Clear error messages * Consistent results * Quick feedback

Documentation Maintainers

various

* Configurable rules * Reliable validation * Integration with existing tools

Development Team

dev team

* Extensible architecture * Good test coverage * Clear documentation

Technical Writers

various

* Support for AsciiDoc best practices * Customizable rule sets * Batch processing capabilities

Architecture Constraints

Technical Constraints

Constraint Description Background

Python 3.8+

The system must run on Python 3.8 or higher

Need for modern language features and type hints

Platform Independence

Must run on Windows, Linux, and macOS

Support for all major development platforms

No External Dependencies

Core functionality should work without external libraries

Easy installation and deployment

Memory Footprint

Should process documents with minimal memory usage

Support for large documentation projects

Organizational Constraints

Constraint Description Background

Open Source

Project must be open source under MIT license

Community involvement and transparency

Documentation

All code must be documented with docstrings

Maintainability and community contribution

Test Coverage

Minimum 90% test coverage required

Quality assurance and reliability

Version Control

Git-based development with feature branches

Collaborative development process

Conventions

Convention Description Background

Code Style

Follow PEP 8 guidelines

Python community standards

Type Hints

Use type hints throughout the code

Code clarity and IDE support

Commit Messages

Follow conventional commits specification

Clear change history

Documentation Format

Use AsciiDoc for all documentation

Dogfooding our own tool

System Scope and Context

Business Context

Diagram

Technical Context

Diagram

Solution Strategy

Quality Goals and Architectural Approaches

Quality Goal Solution Approach Details

Extensibility

* Abstract base classes * Plugin architecture * Clear interfaces

* New rules can be added by extending base classes * Plugin system allows external rule packages * Well-defined interfaces for rule implementation

Reliability

* Comprehensive testing * Strong typing * Defensive programming

* High test coverage * Type hints throughout the code * Careful input validation

Usability

* Clear error messages * Context information * Configuration options

* Detailed error descriptions * Line and column information * Configurable rule severity

Performance

* Efficient algorithms * Lazy loading * Caching

* Line-by-line processing * Rules loaded on demand * Cache parsing results

Maintainability

* Clean architecture * SOLID principles * Documentation

* Clear separation of concerns * Single responsibility principle * Comprehensive documentation

Technology Decisions

Technology Decision Rationale

Python

Primary implementation language

* Strong standard library * Great text processing capabilities * Wide adoption in tooling

Regular Expressions

Pattern matching

* Built into Python * Efficient for text processing * Well understood by developers

YAML

Configuration format

* Human readable * Standard format * Good library support

unittest

Testing framework

* Part of Python standard library * Well known to developers * Good IDE support

Implementation Patterns

Diagram

Building Block View

Level 1 - System Overview

Diagram

Level 2 - Core Components

Diagram

Level 3 - Rule Implementation

Diagram

Runtime View

Document Processing Sequence

Diagram

Rule Loading Sequence

Diagram

Error Reporting Sequence

Diagram

Deployment View

Infrastructure Level 1

Diagram

Technical Infrastructure

Diagram

Security and Access

Diagram

Cross-cutting Concepts

Domain Concepts

Diagram

Security Concepts

Authentication and Authorization

  • Package distribution secured via PyPI authentication

  • Configuration files with restricted access

  • Signed releases with GPG keys

Input Validation

  • Strict content validation

  • Safe file handling

  • Memory usage limits

Output Sanitization

  • Escaped error messages

  • Safe file paths handling

  • Controlled error reporting

Development Concepts

Test Strategy

Diagram

Release Process

Diagram

Configuration Concepts

Rule Configuration

rules:
  heading_hierarchy:
    enabled: true
    severity: error
    options:
      max_level: 6

  heading_format:
    enabled: true
    severity: warning
    options:
      require_space: true
      require_capitalization: true

Plugin System

Diagram

Architecture Decisions

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

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

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

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 :jbake-status: published :jbake-order: 10 :jbake-type: page_toc :jbake-menu: arc42 :jbake-title: Quality Requirements

Quality Requirements

Quality Scenarios

Performance Scenarios

Scenario Stimulus Response Priority

Fast Document Processing

Process 1000-line document

Complete in < 1 second

High

Multiple File Processing

Process 100 documents

Complete in < 10 seconds

Medium

Memory Usage

Process large document (10MB)

Use < 100MB RAM

High

Startup Time

Launch linter

Ready in < 0.5 seconds

Medium

Reliability Scenarios

Scenario Stimulus Response Priority

Error Recovery

Invalid input file

Clear error message, continue with next file

High

Configuration Error

Invalid rule configuration

Detailed error message, use defaults

High

Plugin Failure

Plugin crashes

Isolate failure, continue with other rules

Medium

Resource Exhaustion

System low on memory

Graceful shutdown, save progress

Medium

Usability Scenarios

Scenario Stimulus Response Priority

Clear Error Messages

Rule violation found

Show file, line, and actionable message

High

Configuration

Change rule settings

Take effect without restart

Medium

Integration

Use in CI pipeline

Exit code reflects success/failure

High

Documentation

Look up rule details

Find explanation within 30 seconds

Medium

Quality Tree

Diagram

Technical Risks and Technical Debt

Risk Analysis

Risk Description Impact Probability Mitigation

Performance Degradation

Rule processing becomes slow with many rules

High

Medium

* Profile rule execution * Implement rule caching * Optimize core algorithms

Memory Leaks

Long-running processes accumulate memory

High

Low

* Regular memory profiling * Automated testing * Resource cleanup

False Positives

Rules report incorrect violations

Medium

High

* Extensive test cases * User feedback system * Rule configuration options

Plugin Conflicts

Custom rules interfere with core rules

Medium

Medium

* Plugin isolation * Version compatibility checks * Clear plugin API

Technical Debt

Current Technical Debt

Area Description Impact Priority

Test Coverage

Some edge cases not covered

Medium

High

Documentation

Some advanced features poorly documented

Medium

Medium

Error Handling

Some error cases not specifically handled

High

High

Configuration

Hard-coded values that should be configurable

Low

Low

Planned Improvements

Diagram

Risk Matrix

Diagram

Glossary

Term Definition Additional Information

AsciiDoc

Lightweight markup language for documentation

Similar to Markdown, but with more features for technical documentation

Linter

Tool that analyzes source code or text for potential errors

Focuses on style, format, and structure issues

Rule

Individual check that validates specific aspects

Can be enabled/disabled and configured

Finding

Result of a rule check indicating a potential issue

Contains message, severity, and location information

Severity

Importance level of a finding

ERROR, WARNING, or INFO

Position

Location in a document where an issue was found

Contains line and optional column information

Plugin

Extension that adds additional functionality

Can provide custom rules and configurations

CI/CD

Continuous Integration/Continuous Deployment

Automated build, test, and deployment process

PyPI

Python Package Index

Central repository for Python packages

Virtual Environment

Isolated Python runtime environment

Manages project-specific dependencies

Type Hints

Python type annotations

Helps with code understanding and static analysis

Unit Test

Test of individual components

Ensures correct behavior of specific functions

Integration Test

Test of component interactions

Verifies system behavior as a whole

Coverage

Measure of code tested by automated tests

Usually expressed as percentage

Technical Debt

Development shortcuts that need future attention

Balance between quick delivery and maintainability