[Ghoscro]

Description

A Python script with an encoding or copyright header before its module docstring can show that header as its description in artifact list and artifact info.

Read only the leading string expression, without executing the script or parsing its remaining code. This also works when the script body uses syntax newer than the CLI's Python interpreter. Decode ordinary/raw/adjacent/parenthesized string literals without emitting compiler warnings or changing global warning filters. Preserve docstring whitespace cleaning and the existing comment fallback for missing or malformed descriptions; non-Python handling remains unchanged.

Validation

• Public CLI regressions cover headers, malformed input, newer trailing syntax, string semantics and warning-free decoding. Complete artifact suites: 437 passed on Python 3.11.15 and 437 passed on Python 3.13.12.
• A deterministic overlap test reproduces the prior global warning-filter leak and passes after the fix. Independent comparison also confirms unrelated thread warnings remain visible. Literal values and leading-expression behavior were checked against Python's native parsers.
• Full Python 3.13 suite: 13,153 passed, 128 skipped, 62 existing warnings (269.31s), against the final source and tests.
• Ruff lint, changed-test formatting and whitespace checks pass. Existing unrelated formatting remains untouched. Isolated fixtures fail if executed; validation performs no live community writes.

Hosted results for the newest commit are recorded separately from local results.

AI Disclosure

OpenAI Codex (GPT-6, autonomous; reasoning effort not exposed) prepared the investigation, code, tests and follow-ups on behalf of @Ghoscro. A separate Codex agent reviewed the final diff and independently checked the concurrency and literal semantics. No human line-by-line review is claimed. Supplemental commits carry Assisted-by disclosure.

[Copilot]

🟡 Changes recommended

Confirmed gaps in parser error handling can make artifact commands fail on project scripts.

2 open issues

• Handle parser resource failures with comment fallback · New
• Suppress parser warnings during metadata extraction · New

What changed in this PR

Fixes Python script descriptions in Spec Kit’s artifact catalog so module docstrings take precedence over encoding and license comments, without executing scripts.

Changes:

• Adds AST-based extraction for Python files while preserving existing fallbacks and non-Python handling.
• Adds four regression cases covering header comments and blank or missing docstrings through both list and info paths.

Validation used isolated standard-library probes; the reported project test suites were not rerun.

File	Description
tests/​specify_cli/​artifacts/​test_catalog.py	Adds public-path regression coverage for Python script descriptions.
src/​specify_cli/​artifacts/​catalog.py	Reads Python module docstrings before applying existing fallbacks.

_{Review effort: Max}

[mnriem]

Please address Copilot feedback

[Ghoscro]

Addressed both Copilot findings in db3b52a: parser recursion/memory errors now use the existing comment fallback, and metadata parsing suppresses warnings locally while restoring the caller's warning filters.

Nine new regressions exercise real script source through artifact list, the affected script's info, and an unrelated artifact's info: all nine failed before and pass after. A separate Codex agent independently reran them and reviewed the change. The artifact suite passes 362 tests; the full suite passes 13,078 with 128 skips and 62 warnings. Six installed CLI checks returned expected descriptions and empty stderr. Ruff lint, new-test formatting and whitespace checks pass. The final uploaded tree exactly matches the tested local tree. Hosted CI for this new commit is pending.

@mnriem, this is ready for another look when convenient.

AI disclosure: OpenAI Codex (model: GPT-6, autonomous) prepared, tested and posted this follow-up on behalf of @Ghoscro. No human line-by-line review is claimed.

[Copilot]

🟡 Changes recommended

An uncaught parser exception on supported Python 3.11 can abort artifact list and info commands.

2 open issues

• Handle ValueError from ast.parse on NUL-containing source · New
• Add regression coverage for ordinary invalid Python syntax · New

2 resolved since last review

• Handle parser resource failures with comment fallback
• Suppress parser warnings during metadata extraction

_{Review effort: Max}

[Copilot]

🟡 Changes recommended

Concurrent metadata parsing can leave process-wide warnings suppressed in the long-lived MCP server.

2 open issues

• Prevent overlapping warning filters from leaking globally · New
• Parse docstrings without rejecting newer Python syntax · New

2 resolved since last review

• Handle ValueError from ast.parse on NUL-containing source
• Add regression coverage for ordinary invalid Python syntax

_{Review effort: Max}