Improve extract_cast_text: precise return type and explicit missing-version handling

[Copilot]

Identify the Bug

extract_cast_text declared a bare tuple return type and silently mishandled asciicast headers that lack a "version" key — event.get("version") returns None, which passes the not in (2, 3) check and produces the misleading error "Unsupported asciicast version (None)".

Description of the Change

• Return type annotation — tuple → tuple[str, str | None], matching the documented (text, warning) contract.
• Explicit None guard — Added a check before the version range test. A missing version key now short-circuits with a clear message rather than falling into the unsupported-version path:

version = event.get("version")
if version is None:
    logger.warning("Missing version key in asciicast header")
    return ("", "Missing version key in asciicast header. Only v2 and v3 are supported.")
if version not in (2, 3):
    logger.warning("Unsupported asciicast version: %s", version)
    return ("", f"Unsupported asciicast version ({version}). Only v2 and v3 are supported.")

Alternate Designs

Could have kept a single version not in (2, 3) check and special-cased None in the error string, but separating the branches yields clearer log messages and a more precise user-facing error.

Possible Drawbacks

None. Both paths were already early-return failure cases; behavior for valid v2/v3 files is unchanged.

Verification Process

Reviewed the patched function logic manually. Existing test suite passes. CodeQL scan reports zero alerts.

Release Notes

Fixed misleading error message when an asciicast recording file is missing the version key in its header; improved extract_cast_text return type annotation to tuple[str, str | None].

Original prompt

Please apply the following diffs and create a pull request.
Once the PR is ready, give it a title based on the messages of the fixes being applied.

[{"message":"The return type annotation `tuple` is too generic. Specify the tuple structure as `tuple[str, str | None]` to clarify that it returns a string and an optional warning string.","fixFiles":[{"filePath":"ghostwriter/oplog/utils.py","diff":"diff --git a/ghostwriter/oplog/utils.py b/ghostwriter/oplog/utils.py\n--- a/ghostwriter/oplog/utils.py\n+++ b/ghostwriter/oplog/utils.py\n@@ -88,7 +88,7 @@\n     return \"\".join(cleaned)\n \n \n-def extract_cast_text(file_data: bytes) -> tuple:\n+def extract_cast_text(file_data: bytes) -> tuple[str, str | None]:\n     \"\"\"\n     Parse an asciicast v2 or v3 file and return ``(text, warning)``.\n \n"}]},{"message":"When the header object contains no 'version' key, `version` is `None` and the condition `version not in (2, 3)` evaluates to `True`, triggering the unsupported version path. However, the f-string produces 'Unsupported asciicast version (None)' which is misleading. Consider explicitly checking for `None` and returning a more specific error message like 'Missing version key in asciicast header'.","fixFiles":[{"filePath":"ghostwriter/oplog/utils.py","diff":"diff --git a/ghostwriter/oplog/utils.py b/ghostwriter/oplog/utils.py\n--- a/ghostwriter/oplog/utils.py\n+++ b/ghostwriter/oplog/utils.py\n@@ -138,6 +138,12 @@\n             if isinstance(event, dict):\n                 # Header object — read version and move on to events\n                 version = event.get(\"version\")\n+                if version is None:\n+                    logger.warning(\"Missing asciicast version in header\")\n+                    return (\n+                        \"\",\n+                        \"Missing version key in asciicast header. Only v2 and v3 are supported.\",\n+                    )\n                 if version not in (2, 3):\n                     logger.warning(\"Unsupported asciicast version: %s\", version)\n                     return (\n"}]}]

[Copilot]

Pull request overview

This PR improves robustness and typing clarity for extract_cast_text, the utility used to extract searchable text from asciicast recordings in Oplog uploads.

Changes:

• Tightened the return type annotation from a generic tuple to tuple[str, str | None] to match the documented (text, warning) contract.
• Added explicit handling for missing version in the asciicast header, returning a clearer warning instead of the misleading “Unsupported asciicast version (None)” path.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 92.21%. Comparing base (8b34509) to head (18b70c4).
⚠️ Report is 4 commits behind head on master.

Additional details and impacted files

@@           Coverage Diff           @@
##           master     #869   +/-   ##
=======================================
  Coverage   92.21%   92.21%           
=======================================
  Files         384      384           
  Lines       23987    23990    +3     
=======================================
+ Hits        22120    22123    +3     
  Misses       1867     1867           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.