Add structured logging and error context to runtime layer

[coderabbitai]

Background

PR #6 (#6) introduced GitHub API mutations, TOML config loading, and network I/O in create_labels/github.py, create_labels/config.py, create_labels/sync.py, and create_labels/cli.py. None of these modules emit log output, making it difficult to diagnose failures in production or CI without attaching a debugger.

Required work

Add a logging call hierarchy across the runtime layer:

• create_labels.github: DEBUG log at token/repo resolution; INFO log before and after each GitHub API call; ERROR log (with HTTP status when available) on GitHubError.
• create_labels.sync: DEBUG log per label indicating the determined action (created/updated/unchanged); WARNING on unexpected RuntimeError from GitHub.
• create_labels.config: DEBUG log when a config file is loaded; ERROR log on ConfigError.
• create_labels.cli: configure a root logging.basicConfig at WARNING level by default; expose a --verbose / -v flag that sets the level to DEBUG.

Use logging.getLogger(__name__) in each module. Do not use f-strings inside log calls; use %-style formatting to comply with the project's ruff logging rules (logging-fstring-interpolation is already listed as a linting rule in pyproject.toml).

Acceptance criteria

• Each runtime module uses a module-level logger = logging.getLogger(__name__).
• Key decision points (token resolution, API calls, label actions) emit DEBUG or INFO entries.
• --verbose flag enables DEBUG output.
• make lint and make test pass with logging added.
• docs/developers-guide.md is updated to document the logging strategy.

Raised by @leynos following review of PR #6.

[coderabbitai]

🔗 Related PRs

leynos/episodic#95 - Clarify user logging API docs (#74) [merged]
leynos/prosidy-darn#10 - Add PyPy-backed Pylint lint tier [merged]
leynos/dev-env-rocky#26 - Add standalone Python lint configuration [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[leynos]

@CodeRabbit plan

[coderabbitai]

Coding Plan

Summary

• Establish module-level loggers in all four runtime modules and configure logging.basicConfig in the CLI entrypoint with a --verbose/-v flag to toggle DEBUG output.
• Instrument key decision points: token/repository resolution and API calls in github.py, per-label actions in sync.py, and configuration loading in config.py.
• Use %-style interpolation throughout to satisfy LOG004 and related linting rules.
• Document the logging conventions in developers-guide.md to guide future contributors.

Design Choices

Design Choice 1: Where to configure `logging.basicConfig`

Options Considered:

1. In run() before calling app(), with a subsequent level change in main() if verbose is set.
2. In main() at the start, setting level based on the already-parsed verbose flag.

Chosen Option: 2

Rationale: Configure in main() after cyclopts parses arguments, allowing immediate correct level selection without reconfiguration.

Design Choice 2: Scope of ERROR logging for exceptions

Options Considered:

1. Log ERROR at every raise ConfigError/raise GitHubError statement.
2. Log ERROR only when wrapping lower-level exceptions (e.g., OSError → ConfigError), letting validation errors bubble without logging.
3. Log ERROR at the CLI boundary when catching domain errors.

Chosen Option: 2

Rationale: Log ERROR when converting caught exceptions into domain errors (preserving "log once at boundary" for wrapped exceptions), not for direct validation failures which will surface via cyclopts error handling.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Logging Infrastructure

Establish the foundational logging configuration across all runtime modules, including module-level loggers and the CLI verbose flag.

Task 1: Add Module-Level Loggers

Introduce a standardised logger to each runtime module following the project's LOG015 rule.

• Add import logging and logger = logging.getLogger(__name__) to create_labels/github.py, create_labels/sync.py, create_labels/config.py, and create_labels/cli.py
• Place the logger declaration after existing imports and before any function/class definitions
• Use this single logger instance for all log calls within each module

Task 2: Configure Root Logging in CLI

Set up logging.basicConfig in the CLI entrypoint with a sensible default level.

• Update create_labels/cli.py main() to call logging.basicConfig() at the start of the function body
• Set level=logging.DEBUG if the verbose flag is truthy, otherwise level=logging.WARNING
• Use a simple format string including level and message (e.g., "%(levelname)s: %(message)s")

Task 3: Add --verbose/-v Flag

Expose a boolean flag enabling DEBUG output for diagnostic purposes.

• Add from typing import Annotated and from cyclopts import Parameter to the imports in create_labels/cli.py
• Add parameter verbose: Annotated[bool, Parameter(aliases=["-v"])] = False to the main() signature
• Reference the verbose value when calling logging.basicConfig() per Task 1.2

🤖 Prompt for AI agents

Establish the foundational logging infrastructure across all four runtime
modules and the CLI entrypoint. The goal is to wire up module-level loggers and
a `--verbose/-v` flag before any log statements are added.

**Add module-level loggers to all four runtime modules:**
- In each of `create_labels/github.py`, `create_labels/sync.py`,
`create_labels/config.py`, and `create_labels/cli.py`, add `import logging` and
declare `logger = logging.getLogger(__name__)`
- Place the logger declaration after existing imports and before any function or
class definitions
- Use this single logger instance for all log calls within each respective
module

**Configure root logging in `create_labels/cli.py`:**
- Update the `main()` function to call `logging.basicConfig()` at the start of
its body
- Set `level=logging.DEBUG` if the `verbose` flag is truthy, otherwise set
`level=logging.WARNING`
- Use a format string of `"%(levelname)s: %(message)s"`

**Add the `--verbose/-v` flag to `create_labels/cli.py`:**
- Add `from typing import Annotated` and `from cyclopts import Parameter` to the
imports
- Add `verbose: Annotated[bool, Parameter(aliases=["-v"])] = False` to the
`main()` function signature
- Pass the `verbose` value to the `logging.basicConfig()` call as described
above

Phase 2: Logging Instrumentation

Add log statements at key decision points throughout the runtime modules, adhering to %-style interpolation.

Task 1: Instrument github.py

Add DEBUG, INFO, and ERROR logging around authentication, repository resolution, and API interactions.

• In _login(): DEBUG log the token source ("environment" vs "argument") and the resolved API URL
• In _repository_from_env(): DEBUG log successful parsing of GITHUB_REPOSITORY as %s/%s
• In sync_repository_labels():
  • DEBUG log the repository resolution source (argument, config, or environment)
  • DEBUG log before calling github.repository() with owner/name
  • INFO log after successful repository fetch
  • ERROR log with owner/name before raising GitHubError when repository is None
  • DEBUG log label count and whether defaults are used
  • INFO log summary counts (created/updated/unchanged) after sync_labels() returns
• In _GitHubRepositoryAdapter.label(): DEBUG log when NotFoundError is caught, including the label name

Task 2: Instrument sync.py

Add DEBUG logging for per-label actions and WARNING logging for unexpected failures.

• In _sync_label():
  • DEBUG log the determined action (created, updated, unchanged) for each label using %s interpolation
  • WARNING log before raising RuntimeError when create_label() returns None
  • WARNING log before raising RuntimeError when update() returns a falsy value

Task 3: Instrument config.py

Add DEBUG logging for configuration loading and ERROR logging for caught exceptions.

• In load_config():
  • DEBUG log at function entry with the path being loaded
  • ERROR log in the except OSError block before re-raising as ConfigError
  • ERROR log in the except tomllib.TOMLDecodeError block before re-raising as ConfigError

🤖 Prompt for AI agents

Instrument all three runtime modules with log statements at key decision points.
The goal is comprehensive observability at appropriate levels, using `%`-style
interpolation throughout to satisfy LOG004 and related linting rules.

**Instrument `create_labels/github.py`:**
- In `_login()`: add a DEBUG log for the token source ("environment" vs
"argument") and the resolved API URL
- In `_repository_from_env()`: add a DEBUG log for successful parsing of
`GITHUB_REPOSITORY`, using `%s/%s` interpolation for owner and name
- In `sync_repository_labels()`:
- DEBUG log the repository resolution source (argument, config, or environment)
  - DEBUG log before calling `github.repository()` with owner and name
  - INFO log after a successful repository fetch
- ERROR log with owner/name before raising `GitHubError` when the repository is
`None`
  - DEBUG log the label count and whether defaults are used
- INFO log the summary counts (created/updated/unchanged) after `sync_labels()`
returns
- In `_GitHubRepositoryAdapter.label()`: add a DEBUG log when `NotFoundError` is
caught, including the label name

**Instrument `create_labels/sync.py`:**
- In `_sync_label()`:
- DEBUG log the determined action (`created`, `updated`, or `unchanged`) for
each label using `%s` interpolation
- WARNING log before raising `RuntimeError` when `create_label()` returns `None`
- WARNING log before raising `RuntimeError` when `update()` returns a falsy
value

**Instrument `create_labels/config.py`:**
- In `load_config()`:
  - DEBUG log at function entry with the path being loaded
  - ERROR log in the `except OSError` block before re-raising as `ConfigError`
- ERROR log in the `except tomllib.TOMLDecodeError` block before re-raising as
`ConfigError`

Phase 3: Documentation

Document the logging strategy for maintainers.

Update Developer Guide with Logging Strategy

Add a dedicated section to docs/developers-guide.md explaining the logging conventions.

• Add a new "Logging strategy" section after the existing "Testing strategy" section
• Document the module-level logger convention (logging.getLogger(__name__))
• Explain the %-style formatting requirement and reference the Ruff LOG rules
• Describe the log level semantics: DEBUG for internal state/decisions, INFO for successful operations, WARNING for recoverable issues, ERROR for failures before raising exceptions
• Document the --verbose/-v flag and its effect on output
• Cross-reference .rules/python-exception-design-raising-handling-and-logging.md for the full rule set

🤖 Prompt for AI agents

Add a dedicated logging strategy section to the developer guide. The goal is to
give future contributors clear, unambiguous conventions to follow.

**In `docs/developers-guide.md`:**
- Insert a new "Logging strategy" section immediately after the existing
"Testing strategy" section
- Document the module-level logger convention: `logger =
logging.getLogger(__name__)`
- Explain the `%`-style formatting requirement and reference the Ruff LOG rules
that enforce it
- Describe log level semantics as follows:
  - DEBUG: internal state and decisions
  - INFO: successful operations
  - WARNING: recoverable issues
  - ERROR: failures immediately before raising exceptions
- Document the `--verbose/-v` CLI flag and its effect on output level
- Cross-reference
`.rules/python-exception-design-raising-handling-and-logging.md` for the full
rule set

Research

The create_labels/ package comprises four runtime modules: config.py (TOML parsing and validation, raises ConfigError), sync.py (vendor-neutral label synchronisation logic using protocols), github.py (github3.py adapter, raises GitHubError), and cli.py (cyclopts entrypoint). None of these modules currently import or use logging. The project enforces Ruff LOG rules and pylint logging rules in pyproject.toml, mandating %-style interpolation and module-level getLogger(__name__). The cyclopts Parameter pattern with Annotated types is documented in docs/scripting-standards.md but not yet used in cli.py.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Establish the foundational logging infrastructure across all four runtime
modules and the CLI entrypoint. The goal is to wire up module-level loggers and
a `--verbose/-v` flag before any log statements are added.

**Add module-level loggers to all four runtime modules:**
- In each of `create_labels/github.py`, `create_labels/sync.py`,
`create_labels/config.py`, and `create_labels/cli.py`, add `import logging` and
declare `logger = logging.getLogger(__name__)`
- Place the logger declaration after existing imports and before any function or
class definitions
- Use this single logger instance for all log calls within each respective
module

**Configure root logging in `create_labels/cli.py`:**
- Update the `main()` function to call `logging.basicConfig()` at the start of
its body
- Set `level=logging.DEBUG` if the `verbose` flag is truthy, otherwise set
`level=logging.WARNING`
- Use a format string of `"%(levelname)s: %(message)s"`

**Add the `--verbose/-v` flag to `create_labels/cli.py`:**
- Add `from typing import Annotated` and `from cyclopts import Parameter` to the
imports
- Add `verbose: Annotated[bool, Parameter(aliases=["-v"])] = False` to the
`main()` function signature
- Pass the `verbose` value to the `logging.basicConfig()` call as described
above
===============================================================================

Task: 2

Instrument all three runtime modules with log statements at key decision points.
The goal is comprehensive observability at appropriate levels, using `%`-style
interpolation throughout to satisfy LOG004 and related linting rules.

**Instrument `create_labels/github.py`:**
- In `_login()`: add a DEBUG log for the token source ("environment" vs
"argument") and the resolved API URL
- In `_repository_from_env()`: add a DEBUG log for successful parsing of
`GITHUB_REPOSITORY`, using `%s/%s` interpolation for owner and name
- In `sync_repository_labels()`:
- DEBUG log the repository resolution source (argument, config, or environment)
  - DEBUG log before calling `github.repository()` with owner and name
  - INFO log after a successful repository fetch
- ERROR log with owner/name before raising `GitHubError` when the repository is
`None`
  - DEBUG log the label count and whether defaults are used
- INFO log the summary counts (created/updated/unchanged) after `sync_labels()`
returns
- In `_GitHubRepositoryAdapter.label()`: add a DEBUG log when `NotFoundError` is
caught, including the label name

**Instrument `create_labels/sync.py`:**
- In `_sync_label()`:
- DEBUG log the determined action (`created`, `updated`, or `unchanged`) for
each label using `%s` interpolation
- WARNING log before raising `RuntimeError` when `create_label()` returns `None`
- WARNING log before raising `RuntimeError` when `update()` returns a falsy
value

**Instrument `create_labels/config.py`:**
- In `load_config()`:
  - DEBUG log at function entry with the path being loaded
  - ERROR log in the `except OSError` block before re-raising as `ConfigError`
- ERROR log in the `except tomllib.TOMLDecodeError` block before re-raising as
`ConfigError`
===============================================================================

Task: 3

Add a dedicated logging strategy section to the developer guide. The goal is to
give future contributors clear, unambiguous conventions to follow.

**In `docs/developers-guide.md`:**
- Insert a new "Logging strategy" section immediately after the existing
"Testing strategy" section
- Document the module-level logger convention: `logger =
logging.getLogger(__name__)`
- Explain the `%`-style formatting requirement and reference the Ruff LOG rules
that enforce it
- Describe log level semantics as follows:
  - DEBUG: internal state and decisions
  - INFO: successful operations
  - WARNING: recoverable issues
  - ERROR: failures immediately before raising exceptions
- Document the `--verbose/-v` CLI flag and its effect on output level
- Cross-reference
`.rules/python-exception-design-raising-handling-and-logging.md` for the full
rule set

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!