- Generated by
1.15.0
|
oct
|
Classes | |
| class | OctGroup |
Functions | |
| click.Command|None | _resolve_leaf_command (click.Group group, list[str] args) |
| list[str] | _expand_windows_args (click.Group group, list[str] args) |
| None | _start_diagnostics () |
| None | cli (click.Context ctx, str|None root_dir, bool allow_outside_project, bool strict_config, bool log_output) |
| None | lint (click.Context ctx, tuple[str,...] args) |
| None | format (click.Context ctx, tuple[str,...] args) |
| None | agent (tuple[str,...] args) |
| None | new (click.Context ctx, str path, bool force, bool test, bool dry_run, bool verbose) |
| None | scaffold (str name, bool dry_run, bool no_venv, bool with_claude) |
| str|None | _workspace_subproject_name (Path project_root) |
| None | docs (click.Context ctx, bool sphinx_mode, bool doxygen_mode, bool typedoc_mode, bool all_mode, bool clean_mode, bool dry_run, bool no_workspace, bool init_doxygen, bool force, str|None callgraph, int|None depth, bool trace_mode, tuple[str,...] trace_args) |
| bool | _pytest_missing (str combined_output) |
| None | _run_pytest (Path project_root, tuple args, bool json_mode=False) |
| Path|None | _map_source_to_test (Path source, Path project_root) |
| tuple[str,...] | _cache_args (bool cached, bool cache_clear) |
| None | _record_cached_run (click.Context ctx, Path project_root) |
| None | test (click.Context ctx, bool json_mode, bool changed, bool cached, bool cache_clear, tuple[str,...] args) |
| None | export_source (click.Context ctx, bool verbose, bool clean, bool single_dir, bool allow_outside_project, bool warn_secrets, bool block_secrets, str|None diff_ref, str|None path) |
| None | export_skeleton (click.Context ctx, bool json_mode, bool verbose, bool single_dir, bool no_diagnostics, bool clean, bool allow_outside_project, str|None path) |
| None | clean (click.Context ctx, str|None path, bool dry_run, bool allow_outside_project) |
| None | health (click.Context ctx, bool json_mode, bool verbose, bool run_tests, int|None test_timeout, bool timing, int timing_last, bool write_baseline, bool force_host, Path|None session) |
| None | deps (click.Context ctx, tuple[str,...] args) |
| None | install_hooks_cmd (click.Context ctx, bool force) |
| None | typecheck (click.Context ctx, bool json_mode, tuple[str,...] args) |
| None | diag (click.Context ctx) |
| None | diag_validate_config (click.Context ctx, bool strict) |
| None | diag_list_domains (click.Context ctx) |
| None | diag_set_level (click.Context ctx, str domain, int level, bool dry_run) |
| None | diag_restore (click.Context ctx) |
| None | diag_migrate_config (click.Context ctx, Path|None config_path, bool dry_run) |
| None | install_mcp (click.Context ctx, str host, bool dry_run) |
Variables | |
| dict | _COMMAND_FLAGS |
| str | TIMING_SAMPLE_KEY = "oct.timing.sample" |
| str | NO_GLOB_EXPANSION_ATTR = "no_glob_expansion" |
| tuple | _PYTEST_INSTALL_HINT |
| _git_group | |
| name | |
| _migrate_group | |
| _audit_cmd | |
| _oct_install_cmd | |
Purpose
-------
Provide the main command-line interface for the OCT (Option C Tools) ecosystem.
Responsibilities
----------------
- Define top-level commands: oct lint, oct format, oct new, oct scaffold, oct docs,
oct test, oct export-source, oct clean, oct health.
- Delegate work to the appropriate OCT modules.
- Scaffold new Option C projects with a correct ``oc_diagnostics/debug_config.json``
pre-configured for use with ``oc_diagnostics``.
- Set up Sphinx documentation templates in ``docs/``.
- Ensure consistent behavior across all projects.
Diagnostics
-----------
Domain: OCT-CLI
Levels:
L2 - lifecycle
L3 - semantic details
L4 - deep tracing
Contracts
---------
- Must be installed as the console entry point for the OCT package.
- Must not contain business logic; only dispatching.
- Scaffolded ``debug_config.json`` must be a valid ``oc_diagnostics`` configuration.
Dependencies
------------
- oct (package version)
- oct.core.project_root (project root detection)
- oct.linter.oct_lint (linter command implementation)
- oct.formatter.oct_format (formatter command implementation)
- oct.health.oct_health (health dashboard command)
- oct.generator.new_python_file (new file scaffolding)
- oct.diag.oct_diag (diagnostics config commands)
- oct.deps.oct_deps (dependency graph command)
- oct.hooks.oct_hooks (pre-commit hooks generator)
- oct.typecheck.oct_typecheck (type-checking wrapper)
- click (CLI framework)
- oct.complexity.command (complexity command)
- oct.mutation.command (mutate command)
- oct.git (git_group - the git command group)
- oct.migrate (migrate_group - the migrate command group)
- oct.audit (audit_group - the audit command)
- oct.install.oct_install (oct_install_cmd - the install command)
- oct.core.diagnostics (_dbg structured logger)
- oc_diagnostics (lazy; init with file-only output before each command)
- oct.timing.ledger (lazy; the timing stage around each command)
- oct.core.compat (lazy; oc_diagnostics compatibility warning for scaffold)
- oct.scaffold (lazy; run_scaffold for the scaffold command)
- oct.scaffold.oct_scaffold (lazy; Claude Code skills copy for scaffold --with-claude)
- oct.core.workspace (lazy; manifest subproject name for the Doxyfile PROJECT_NAME)
- oct.docs.callgraph_command (lazy; docs --callgraph)
- oct.docs.doxyfile_init (lazy; Doxyfile writer for docs --init-doxygen)
- oct.docs.oct_docs (lazy; Sphinx, Doxygen, all-tier and clean docs runs, project name fallback)
- oct.docs.typedoc (lazy; docs --typedoc)
- oct.testing.cache (lazy; pytest cache plugin flags and the cached run's file count)
- oct.core.git (lazy; changed-file discovery for test --changed)
- oct.tools.source_exporter (lazy; export-source, and source export and pycache removal for clean)
- oct.tools.skeleton_exporter (lazy; export-skeleton, and skeleton export removal for clean)
- oct.tools.build_artifacts (lazy; build and dist tree removal for clean)
- oct.git.oct_git (lazy; enhanced hooks template for the deprecated install-hooks)
- oct.tools.install_mcp (lazy; install-mcp command)
- oc_chat.registry (not imported; run as python -m oc_chat.registry by the agent command)
- pytest (not imported; run as python -m pytest by the test command)
|
protected |
Pytest arguments that drive the Plan 249 content-hashed cache. ``-p oct.testing.cache`` loads the plugin for ANY project, so the flags work whether or not the project's root conftest wires the seams itself; the plugin registers its options at most once.
Definition at line 988 of file cli.py.
|
protected |
Apply Click's Windows shell-expansion unless the target opts out. Click's ``Command.main`` runs ``_expand_args`` over the whole argv on Windows - ``~``, ``$VAR`` and globs - because cmd and PowerShell do none of that themselves, and ``oct lint oct/*.py`` relies on it. But the expansion cannot tell a path from a pattern: ``oct git ignore "**/docs/html/"`` had its one argument replaced by the fourteen directories it happened to match, every one of which the pattern validator then rejected (2026-09-27). A command that takes patterns sets :data:`NO_GLOB_EXPANSION_ATTR` and receives its argv verbatim; every other command keeps the expansion it always had.
Definition at line 395 of file cli.py.
|
protected |
|
protected |
|
protected |
Put the cached run's file count in the timing ledger (P5). ``files`` is the number of files that actually RAN, so the saving a cache produced is visible in ``oct health --timing`` beside the uncached runs of the same stage.
Definition at line 1007 of file cli.py.
|
protected |
Return the command *args* would dispatch to, parsing nothing else. Walks the group tree with ``resilient_parsing`` contexts, so option callbacks never run and a malformed command line resolves to ``None`` rather than raising - the real parse that follows reports the error properly. Used before Click's Windows argument expansion to find out whether the target command wants that expansion at all.
Definition at line 360 of file cli.py.
|
protected |
Run pytest in *project_root* and exit on failure.
When *json_mode* is True, captures pytest output, parses the summary
line, and emits a machine-readable JSON object to stdout:
``{"tool": "test", "passed": N, "failed": N, "errors": N,
"warnings": N, "output": "...", "exit_code": N}``
OI-511: pytest is now declared in the ``[project.optional-dependencies].test``
extra rather than as a runtime dependency; if ``python -m pytest`` reports
it is not importable, emit the install hint above and exit 1.
Definition at line 860 of file cli.py.
|
protected |
Start oc_diagnostics for this process: exception hook, no stream capture. Output goes to the log file only, so oct's terminal output stays its own. The file's FORMAT is left to the config's ``log_format`` (text, or ``jsonl`` for machine reading; oc_diagnostics >= 2.2.0 keeps the two independent). Idempotent; a no-op without oc_diagnostics.
Definition at line 415 of file cli.py.
|
protected |
| None oct.cli.agent | ( | tuple[str, ...] | args | ) |
Delegate to the OC Chat registry agent CLI. A thin subprocess facade over ``python -m oc_chat.registry`` (Plan 151 T6). oct NEVER imports oc_chat - the CLI-boundary rule; all arguments, stdin/stdout/stderr, the JSON envelope, and the exit-code contract (0 ok, 1 source-validation, 2 build/refusal/scope, 3 not-byte-stable, 5 stale schema) are preserved verbatim by delegating to the child process. Requires oc_chat to be importable on the interpreter running the facade (the monorepo workspace install).
| None oct.cli.clean | ( | click.Context | ctx, |
| str | None | path, | ||
| bool | dry_run, | ||
| bool | allow_outside_project ) |
Remove _source_code-*, _skeleton_code-* export dirs, __pycache__ dirs and packaging build/ and dist/ trees. A build/ or dist/ directory is only removed when it sits beside a pyproject.toml / setup.py / setup.cfg AND contains nothing but packaging output. One that fails either test is kept and the reason printed, because both are ordinary words and a project is entitled to a source directory called either.
| None oct.cli.cli | ( | click.Context | ctx, |
| str | None | root_dir, | ||
| bool | allow_outside_project, | ||
| bool | strict_config, | ||
| bool | log_output ) |
| None oct.cli.deps | ( | click.Context | ctx, |
| tuple[str, ...] | args ) |
| None oct.cli.diag | ( | click.Context | ctx | ) |
| None oct.cli.diag_list_domains | ( | click.Context | ctx | ) |
| None oct.cli.diag_migrate_config | ( | click.Context | ctx, |
| Path | None | config_path, | ||
| bool | dry_run ) |
| None oct.cli.diag_restore | ( | click.Context | ctx | ) |
| None oct.cli.diag_set_level | ( | click.Context | ctx, |
| str | domain, | ||
| int | level, | ||
| bool | dry_run ) |
| None oct.cli.diag_validate_config | ( | click.Context | ctx, |
| bool | strict ) |
| None oct.cli.docs | ( | click.Context | ctx, |
| bool | sphinx_mode, | ||
| bool | doxygen_mode, | ||
| bool | typedoc_mode, | ||
| bool | all_mode, | ||
| bool | clean_mode, | ||
| bool | dry_run, | ||
| bool | no_workspace, | ||
| bool | init_doxygen, | ||
| bool | force, | ||
| str | None | callgraph, | ||
| int | None | depth, | ||
| bool | trace_mode, | ||
| tuple[str, ...] | trace_args ) |
| None oct.cli.export_skeleton | ( | click.Context | ctx, |
| bool | json_mode, | ||
| bool | verbose, | ||
| bool | single_dir, | ||
| bool | no_diagnostics, | ||
| bool | clean, | ||
| bool | allow_outside_project, | ||
| str | None | path ) |
| None oct.cli.export_source | ( | click.Context | ctx, |
| bool | verbose, | ||
| bool | clean, | ||
| bool | single_dir, | ||
| bool | allow_outside_project, | ||
| bool | warn_secrets, | ||
| bool | block_secrets, | ||
| str | None | diff_ref, | ||
| str | None | path ) |
| None oct.cli.format | ( | click.Context | ctx, |
| tuple[str, ...] | args ) |
| None oct.cli.health | ( | click.Context | ctx, |
| bool | json_mode, | ||
| bool | verbose, | ||
| bool | run_tests, | ||
| int | None | test_timeout, | ||
| bool | timing, | ||
| int | timing_last, | ||
| bool | write_baseline, | ||
| bool | force_host, | ||
| Path | None | session ) |
| None oct.cli.install_hooks_cmd | ( | click.Context | ctx, |
| bool | force ) |
| None oct.cli.install_mcp | ( | click.Context | ctx, |
| str | host, | ||
| bool | dry_run ) |
| None oct.cli.lint | ( | click.Context | ctx, |
| tuple[str, ...] | args ) |
| None oct.cli.new | ( | click.Context | ctx, |
| str | path, | ||
| bool | force, | ||
| bool | test, | ||
| bool | dry_run, | ||
| bool | verbose ) |
| None oct.cli.scaffold | ( | str | name, |
| bool | dry_run, | ||
| bool | no_venv, | ||
| bool | with_claude ) |
| None oct.cli.test | ( | click.Context | ctx, |
| bool | json_mode, | ||
| bool | changed, | ||
| bool | cached, | ||
| bool | cache_clear, | ||
| tuple[str, ...] | args ) |
| None oct.cli.typecheck | ( | click.Context | ctx, |
| bool | json_mode, | ||
| tuple[str, ...] | args ) |
|
protected |
1.15.0