migrate_to_oc_diagnostics Namespace Reference

Functions
bool	_should_exclude (str dirpath)
bool	rewrite_file (str path, list replacements, bool dry_run)
list[str]	migrate_project (str root=".", bool dry_run=False)
str	handle_old_diagnostics (bool delete_original, bool dry_run)

Variables
dict	EXCLUDE_DIRS
list	PYTHON_REPLACEMENTS
list	MD_REPLACEMENTS
	parser
	action
	help
	args = parser.parse_args()
str	dry_prefix = "[DRY RUN] " if args.dry_run else ""
list[str]	modified_files = migrate_project(".", dry_run=args.dry_run)
str	result

Detailed Description

Migration Script: Migrate a project from embedded diagnostics to oc_diagnostics
================================================================================

Purpose
-------
Rewrite Python import paths and Markdown references in an existing project so
that all usage of the old embedded ``diagnostics/`` package is replaced by the
new standalone ``oc_diagnostics`` package.

Responsibilities
----------------
- Walk the project tree, skipping common non-project directories
  (``EXCLUDE_DIRS``).
- Rewrite Python import statements in ``.py`` files using a curated list of
  ``(pattern, replacement)`` pairs.
- Rewrite documentation references in ``.md`` files.
- Create a ``.bak`` file next to every modified file so changes are reversible.
- Handle the old ``diagnostics/`` directory in one of two ways:
    - **Default (backup):** rename ``diagnostics/`` to ``diagnostics.bak/``.
      The original content is preserved; the active project no longer uses it.
    - **``--delete-original``:** permanently delete ``diagnostics/`` with no
      backup copy.  Use only when a backup already exists.
- Support ``--dry-run`` to preview all actions without modifying the filesystem.

Diagnostics
-----------
Domain: MIGRATE
Levels:
    L2 — lifecycle
    L3 — semantic details
    L4 — deep tracing

Contracts
---------
- Must not modify files outside the target project root.
- Must skip directories in ``EXCLUDE_DIRS`` to avoid corrupting virtual
  environments, VCS metadata, caches, and third-party packages.
- In ``--dry-run`` mode no files must be written, renamed, or deleted.
- Every modified file must have a ``.bak`` copy written before the rewrite.
- The ``diagnostics/`` backup copy is created by default; ``--delete-original``
  skips the backup and deletes instead.

Run this script from the root of the project being migrated:

    python tools/migrate_to_oc_diagnostics.py [--dry-run] [--delete-original]

Function Documentation

_should_exclude()

bool migrate_to_oc_diagnostics._should_exclude ( str dirpath )

protected

Return True if this directory should be skipped during the tree walk.

Definition at line 147 of file migrate_to_oc_diagnostics.py.

Here is the caller graph for this function:

handle_old_diagnostics()

str migrate_to_oc_diagnostics.handle_old_diagnostics	(	bool	delete_original,
		bool	dry_run )

Handle the old ``diagnostics/`` directory.

Default (backup): rename ``diagnostics/`` → ``diagnostics.bak/``.
With ``--delete-original``: permanently delete ``diagnostics/``.

Returns a human-readable status string.

Definition at line 217 of file migrate_to_oc_diagnostics.py.

migrate_project()

list[str] migrate_to_oc_diagnostics.migrate_project	(	str	root = ".",
		bool	dry_run = False )

Walk *root* and rewrite all Python and Markdown files.

Returns the list of files that were (or would be) modified.

Definition at line 182 of file migrate_to_oc_diagnostics.py.

Here is the call graph for this function:

rewrite_file()

bool migrate_to_oc_diagnostics.rewrite_file	(	str	path,
		list	replacements,
		bool	dry_run )

Rewrite a file using a list of (pattern, replacement) pairs.

Returns True if the file would be (or was) modified.
Creates a ``.bak`` backup before writing when not in dry-run mode.

Definition at line 153 of file migrate_to_oc_diagnostics.py.

Here is the caller graph for this function:

Variable Documentation

action

migrate_to_oc_diagnostics.action

Definition at line 255 of file migrate_to_oc_diagnostics.py.

args

migrate_to_oc_diagnostics.args = parser.parse_args()

Definition at line 266 of file migrate_to_oc_diagnostics.py.

dry_prefix

str migrate_to_oc_diagnostics.dry_prefix = "[DRY RUN] " if args.dry_run else ""

Definition at line 268 of file migrate_to_oc_diagnostics.py.

EXCLUDE_DIRS

dict migrate_to_oc_diagnostics.EXCLUDE_DIRS

Initial value:

=  {
    ".git",
    "__pycache__",
    "venv",
    "env",
    ".venv",
    ".env",
    "node_modules",
    "diagnostics.bak",  # skip our own backup folder
    ".tox",
    ".mypy_cache",
    ".pytest_cache",
    "dist",
    "build",
    "*.egg-info",
}

Definition at line 63 of file migrate_to_oc_diagnostics.py.

help

migrate_to_oc_diagnostics.help

Definition at line 256 of file migrate_to_oc_diagnostics.py.

MD_REPLACEMENTS

list migrate_to_oc_diagnostics.MD_REPLACEMENTS

Initial value:

=  [
    (r"\bdiagnostics/", r"oc_diagnostics/"),
    (r"DIAGNOSTICS_README\.md", r"REFERENCE.md"),
    (r"DIAGNOSTICS_INTEGRATION_GUIDE_README\.md", r"INTEGRATION_GUIDE.md"),
    (r"from diagnostics\.", r"from oc_diagnostics."),
    (r"`diagnostics/`", r"`oc_diagnostics/`"),
]

Definition at line 134 of file migrate_to_oc_diagnostics.py.

modified_files

list[str] migrate_to_oc_diagnostics.modified_files = migrate_project(".", dry_run=args.dry_run)

Definition at line 274 of file migrate_to_oc_diagnostics.py.

parser

migrate_to_oc_diagnostics.parser

Initial value:

=  argparse.ArgumentParser(
        description="Migrate a project from embedded diagnostics/ to oc_diagnostics.",
    )

Definition at line 250 of file migrate_to_oc_diagnostics.py.

PYTHON_REPLACEMENTS

list migrate_to_oc_diagnostics.PYTHON_REPLACEMENTS

Definition at line 85 of file migrate_to_oc_diagnostics.py.

result

str migrate_to_oc_diagnostics.result

Initial value:

=  handle_old_diagnostics(
        delete_original=args.delete_original,
        dry_run=args.dry_run,
    )

Definition at line 286 of file migrate_to_oc_diagnostics.py.