exclusions.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/exclusions.py
 
"""
Purpose
-------
Provide shared default directory exclusion lists for linter and exporter.
 
Responsibilities
----------------
- Define common exclusion directories used by both the linter and the source exporter.
- Provide tool-specific supersets for each consumer.
- Centralise wildcard (substring) exclusion patterns.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    L2 - lifecycle
    L3 - semantic details
    L4 - deep tracing
 
Contracts
---------
- All sets are frozen at module level; consumers copy before mutating.
- Linter and exporter import from here instead of defining their own constants.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger; imported but never called, the module holds constants only)
"""
 
# OCT-LINT: disable-file=dbg_usage reason="Plan 263: a constants-only module with no function or method, so there is no seam to observe; a module-level call would emit before init() on every import"
 
from oct.core.diagnostics import _dbg
 
# Directories excluded by exact name match - shared between linter and exporter.
COMMON_EXCLUDE_DIRS = {
    ".git",
    "__pycache__",
    "Old",
    "old",
    ".linter_archive",
    "copied_python_files",
    "data",
    "data_raw",
    "raw_data",
    "data.bk",
    "flow_charts",
    "dot_files",
    "dev-tools",
    # Virtual environment directories - must be excluded to avoid scanning
    # thousands of third-party library files on every lint or export run.
    ".venv",
    "venv",
    "env",
}
 
# Linter-specific exclusions (adds Code Reviews and fixtures to the common set).
# "fixtures" is excluded globally because test fixtures are intentionally
# non-compliant (missing headers, broken docstrings, etc.) - they exist to
# exercise the linter itself (OI-420).
LINTER_EXCLUDE_DIRS = COMMON_EXCLUDE_DIRS | {
    "Code Reviews",
    "fixtures",
}
 
# Exporter-specific exclusions (adds dataset, doxygen, backup dirs to the common set).
EXPORTER_EXCLUDE_DIRS = COMMON_EXCLUDE_DIRS | {
    "Code Reviews",
    "dataset_library",
    "doxygen_work_dir",
    "doxygen_output",
    "logs",
    "cache",
    "_backup",
    "old_backup",
}
 
# Wildcard (substring) patterns - shared between linter and exporter.
# The venv/ suffix entries here act as a belt-and-suspenders guard for
# non-standard venv names (e.g. .venv-dev, venv38) that might not match
# the exact-name set above.
WILDCARD_EXCLUDE_DIRS = ["cache", "_source", "_skeleton", "logs", "_exports", "_build", ".venv", "venv"]
 
# File patterns excluded from export and documentation output.
# These files contain environment-specific runtime configuration
# and must never appear in exported source or generated docs.
# See §6b Secret Hygiene in the Master Coding Style Specification.
NEVER_EXPORT_FILE_PATTERNS = [
    ".env", ".env.*",           # Environment variable files
    "*.pem", "*.key",           # Private key files
    "credentials.json",         # Service account credentials
    "secrets.json",             # Application secrets
    "secrets.yaml",             # Application secrets (YAML)
    "secrets.yml",              # Application secrets (YAML)
]
 
# Default .gitignore entries written by ``oct git init`` (Phase 4C).
# Phase 4A defines this constant only - no code reads it yet. The
# format is a tuple of strings, one per .gitignore line, with blank
# strings representing literal blank separators between sections. The
# patterns intentionally cover:
#
# - Python bytecode, caches, and build artefacts
# - Virtualenv conventions (.venv, venv, env)
# - Distribution / packaging output
# - OCT's own internal backup and archive directories
# - Sphinx / docs build output
# - Test / coverage artefacts
# - Common IDE and OS metadata files
# - Secrets (.env, *.pem, *.key) - mirrors NEVER_EXPORT_FILE_PATTERNS
GIT_IGNORE_DEFAULTS: tuple[str, ...] = (
    "# Python",
    "__pycache__/",
    "*.py[cod]",
    "*$py.class",
    "*.so",
    ".Python",
    "",
    "# Virtualenvs",
    ".venv/",
    "venv/",
    "env/",
    "",
    "# Distribution / packaging",
    "build/",
    "dist/",
    "*.egg-info/",
    "",
    "# OCT internal",
    ".formatter_archive/",
    ".linter_archive/",
    ".octrc.json.bak",
    "",
    "# Sphinx / docs build",
    "docs/_build/",
    "docs/_api/",
    "docs/_autosummary/",
    "docs/doctrees/",
    "",
    "# Testing / coverage",
    ".pytest_cache/",
    ".coverage",
    "htmlcov/",
    ".tox/",
    "",
    "# IDE",
    ".vscode/",
    ".idea/",
    "*.swp",
    "",
    "# OS",
    ".DS_Store",
    "Thumbs.db",
    "",
    "# Secrets",
    ".env",
    ".env.*",
    "*.pem",
    "*.key",
)