Task: Implement codegen.py CLI scaffold

Table of Contents

This page documents a task in the Refactor ores.codegen SQL generation story. It captures the goal, current status, acceptance, and any notes or results.

Goal

Create codegen.py as the idiomatic Python entry point for ores.codegen. Implement the complete argparse subcommand structure, package layout, and logging configuration as specified in the survey task. Wire generate and regenerate through to the existing generator.py; stub diff with an informative "not yet available" message. The result is a working CLI that can replace generate_refdata_schema.sh for day-to-day use.

Status

Field Value
State DONE
Parent story Refactor ores.codegen SQL generation
Now Nothing.
Waiting on Nothing.
Next Implement unified SQL template.
Last touched 2026-05-29

Acceptance

  • codegen.py exists at projects/ores.codegen/codegen.py and is executable.
  • Package src/codegen/ exists with cli.py, generate.py, list_cmd.py, diff_cmd.py, manifest.py, logging_config.py.
  • codegen.py --help shows all four subcommands.
  • codegen.py generate --model PATH --profile sql --dry-run prints the output path without writing.
  • codegen.py regenerate --component refdata --profile sql --dry-run prints all 10 output paths without writing.
  • codegen.py list components lists known components.
  • codegen.py list models --component refdata lists all _entity.json files.
  • codegen.py diff --component refdata prints a clear "not yet available" message.
  • --profile all on an _entity.json model is rejected with an error.
  • Venv is bootstrapped automatically on first run.
  • Site builds cleanly.

PRs

PR Title
#938 [codegen] Retire generate_refdata_schema.sh

Review

# Comment summary File Decision Notes
1 Hardcoded venv/bin/python3 not cross-platform; suggest dynamic resolution codegen.py Fixed Moved all venv logic out of Python into codegen.sh wrapper (compass.sh pattern); codegen.py is now a pure entry point with no platform-specific paths. PR #934 round 1
2 Use python -m pip instead of invoking pip binary directly codegen.py Fixed Moved to codegen.sh; no longer relevant in Python. PR #934 round 1

Result

Implemented. Package layout:

projects/ores.codegen/
  codegen.sh                  shell wrapper; bootstraps venv, activates it, cds to repo root
  codegen.py                  pure Python entry point; no venv logic
  src/
    codegen/
      __init__.py
      cli.py                  argparse setup + dispatch
      generate.py             generate and regenerate command implementations
      list_cmd.py             list command implementation
      diff_cmd.py             diff stub (requires unified template)
      manifest.py             component → model directory mappings
      logging_config.py       logging setup

Key behaviours:

  • generate and regenerate call through to generator.py functions directly (no subprocess).
  • --profile all is rejected for _entity.json (schema) models to prevent the footgun.
  • --dry-run resolves and prints output paths without writing.
  • diff returns a clear error referencing the unified template task.
  • Venv managed by codegen.sh (following compass.sh pattern); codegen.py contains no platform-specific paths.

Emacs 29.1 (Org mode 9.6.6)