fix: insider Binder error on default --prefer auto (#42)

[joce]

Summary

Fixes #42: uv run edgarq insider AAPL --form 4 --no-cache crashed with Binder Error: Referenced column "ISSUERCIK" not found on the default --prefer auto path.

Two tangled root causes addressed:

1. View DDL vs parquet schema drift. The _run_sql_path query assumed all columns lived on insider_transactions_nonderiv, but the real SEC form345 schema is normalised across three tables joined on ACCESSION_NUMBER:

   • insider_submissions — ISSUERCIK (BIGINT), FILING_DATE (VARCHAR DD-MON-YYYY), DOCUMENT_TYPE
   • insider_transactions_nonderiv — SECURITY_TITLE, TRANS_DATE, TRANS_CODE, TRANS_SHARES, TRANS_PRICEPERSHARE, TRANS_ACQUIRED_DISP_CD, SHRS_OWND_FOLWNG_TRANS
   • reporting_owners — RPTOWNERNAME, RPTOWNER_RELATIONSHIP (free text like Director,Officer,TenPercentOwner), RPTOWNER_TITLE

   Rewrote the SQL to select+filter via insider_submissions and join transactions/owners, with date conversion via strptime/strftime and a replace-based relationship label builder.

2. Auto-path crash on schema drift. Added a defensive fallback so --prefer auto warns and falls back to the HTTP path on any EdgarqError from _run_sql_path (Binder, Catalog, etc.). --prefer local still exits 2 with the bulk-extract hint.

The pre-existing test_insider_hybrid.py fixture used fabricated column names (ISSUERCIK on NONDERIV_TRANS, ISOFFICER flags on REPORTINGOWNER, etc.) which masked this bug. Fixture updated to match real SEC schema; new test_insider_real_schema.py adds regression coverage.

Test plan

• TDD: new failing test reproduced the exact Binder error before any production-code change
• tests/commands_impl/test_insider_real_schema.py — 3 new tests for schema/fallback/error-surface
• All 46 insider tests pass
• uv run tox matrix py3.10–3.14 — green (one unrelated flaky parallel test, test_companyfacts_shard_distribution_hash_mod_64, passes in isolation)
• Live smoke: uv run edgarq insider AAPL --form 4 --limit 3 --no-cache --since 2024-01-01 returns real transaction rows; --prefer auto without bulk extract falls back to HTTP cleanly

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a733fd0a3b

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.

📢 Thoughts on this report? Let us know!