# Documentation Rules
# ====================
# Ensures required documentation for audit trail and compliance.
# Critical for demonstrating controls and due diligence.

rules:
  # ===================
  # PROJECT DOCUMENTATION
  # ===================

  - id: DOC-PROJ-001
    name: "README file required"
    description: "Project must have a README with basic information"
    severity: high
    check:
      type: file_exists
      paths:
        - "README.md"
        - "README.rst"
        - "README.txt"
      message: "Project README required"

  - id: DOC-PROJ-002
    name: "Setup instructions"
    description: "README must include setup/installation instructions"
    severity: medium
    check:
      type: pattern_required
      paths:
        - "README.md"
      patterns:
        - "[Ii]nstall|[Ss]etup|[Gg]etting [Ss]tarted"
      message: "Setup instructions required in README"

  - id: DOC-PROJ-003
    name: "Contributing guidelines"
    description: "Project should have contribution guidelines"
    severity: low
    check:
      type: file_exists
      paths:
        - "CONTRIBUTING.md"
        - "docs/guides/contributing.md"
      message: "Consider adding contribution guidelines"

  # ===================
  # API DOCUMENTATION
  # ===================

  - id: DOC-API-001
    name: "OpenAPI documentation"
    description: "API must have OpenAPI/Swagger documentation"
    severity: high
    check:
      type: pattern_required
      paths:
        - "main.py"
      patterns:
        - "openapi|docs_url|redoc"
      message: "OpenAPI documentation required for APIs"

  - id: DOC-API-002
    name: "Endpoint documentation"
    description: "API endpoints must have docstrings"
    severity: medium
    check:
      type: pattern_required
      paths:
        - "app/api/v1/*.py"
      patterns:
        - '""".*"""'
      message: "API endpoints should have docstrings"

  - id: DOC-API-003
    name: "API versioning documented"
    description: "API versioning strategy must be documented"
    severity: medium
    check:
      type: file_exists
      paths:
        - "docs/api/*.md"
      message: "API documentation required"

  # ===================
  # SECURITY DOCUMENTATION
  # ===================

  - id: DOC-SEC-001
    name: "Security policy"
    description: "Project must have security policy"
    severity: high
    check:
      type: file_exists
      paths:
        - "SECURITY.md"
        - ".github/SECURITY.md"
        - ".gitea/SECURITY.md"
      message: "Security policy (SECURITY.md) required"

  - id: DOC-SEC-002
    name: "Authentication documentation"
    description: "Authentication mechanism must be documented"
    severity: high
    check:
      type: file_exists
      paths:
        - "docs/api/authentication.md"
        - "docs/**/auth*.md"
      message: "Authentication documentation required"

  - id: DOC-SEC-003
    name: "Security controls documentation"
    description: "Security controls must be documented"
    severity: medium
    check:
      type: pattern_required
      paths:
        - "docs/**/*.md"
      patterns:
        - "[Ss]ecurity|[Aa]uthentication|[Aa]uthorization"
      message: "Security controls should be documented"

  # ===================
  # OPERATIONAL DOCUMENTATION
  # ===================

  - id: DOC-OPS-001
    name: "Deployment documentation"
    description: "Deployment process must be documented"
    severity: high
    check:
      type: file_exists
      paths:
        - "docs/deployment/index.md"
        - "docs/**/deploy*.md"
      message: "Deployment documentation required"

  - id: DOC-OPS-002
    name: "Configuration documentation"
    description: "Configuration options must be documented"
    severity: medium
    check:
      type: file_exists
      paths:
        - "docs/getting-started/configuration.md"
        - ".env.example"
      message: "Configuration documentation required"

  - id: DOC-OPS-003
    name: "Monitoring documentation"
    description: "Monitoring and alerting should be documented"
    severity: low
    check:
      type: file_exists
      paths:
        - "docs/**/monitoring*.md"
        - "docs/**/observability*.md"
      message: "Consider documenting monitoring setup"

  # ===================
  # COMPLIANCE DOCUMENTATION
  # ===================

  - id: DOC-COMP-001
    name: "Data handling documentation"
    description: "Data handling practices must be documented"
    severity: high
    check:
      type: file_exists
      paths:
        - "docs/**/data*.md"
        - "docs/**/privacy*.md"
      message: "Data handling documentation recommended"

  - id: DOC-COMP-002
    name: "Audit controls documentation"
    description: "Audit controls must be documented"
    severity: medium
    check:
      type: pattern_required
      paths:
        - "docs/**/*.md"
      patterns:
        - "[Aa]udit|[Ll]ogging|[Tt]raceability"
      message: "Audit controls should be documented"

  - id: DOC-COMP-003
    name: "Compliance requirements documented"
    description: "Applicable compliance requirements must be listed"
    severity: medium
    check:
      type: documentation
      message: "Document applicable compliance requirements (GDPR, SOX, etc.)"

  # ===================
  # ARCHITECTURE DOCUMENTATION
  # ===================

  - id: DOC-ARCH-001
    name: "Architecture overview"
    description: "System architecture must be documented"
    severity: medium
    check:
      type: file_exists
      paths:
        - "docs/architecture/*.md"
      message: "Architecture documentation required"

  - id: DOC-ARCH-002
    name: "Component diagram"
    description: "System should have component/architecture diagram"
    severity: low
    check:
      type: pattern_recommended
      paths:
        - "docs/**/*.md"
        - "README.md"
      patterns:
        - "mermaid|diagram|architecture.*png|architecture.*svg"
      message: "Consider adding architecture diagrams"

  - id: DOC-ARCH-003
    name: "Decision records"
    description: "Major decisions should be documented (ADRs)"
    severity: low
    check:
      type: file_exists
      paths:
        - "docs/adr/*.md"
        - "docs/decisions/*.md"
      message: "Consider documenting architecture decisions (ADRs)"