fix(docs): the competitive table said a competitor's repo was gone; it is archived - #58
Merged
Merged
Conversation
…t is archived
docs/competitive-analysis.md carried the row
| Optic | — | — | — | — | repo gone (404) |
and the prose "Dredd/Optic — archived/gone". Optic's repository is not gone.
`opticdev/optic` is archived and public with 1,534 stars, last pushed
2026-01-08.
The 404 was ours. scripts/fetch_competitor_meta.py asked for
`useoptic/optic`, which does not exist. `gh_json` caught the resulting
CalledProcessError and returned None; the caller wrote
`{"error": "repo-not-found-or-error"}` into data/competitor-meta.json; and the
document transcribed that tool failure as a fact about a competitor. A typo in
a constant became a published claim that a project had disappeared.
It is worth being precise about why this one matters beyond accuracy. An
archived incumbent with 1,534 stars in exactly this project's domain is the
single most useful fact in the file -- it describes an opening. Recording it as
"gone" both stated something false and discarded the signal.
Fixed at the source rather than in the table: gh_json now raises FetchError
instead of returning None, so a failed lookup stops the run and a human decides
whether a project moved or genuinely went away. `allow_404` is threaded through
only for the releases endpoint, where absence is a real answer.
The landscape table is regenerated from a fetch run today (2026-09-09), so
every cell is traceable to data in this repository rather than typed by hand:
oasdiff 1,327 -> 1,356, Schemathesis 3,554 -> 3,590, k6 31,424, and Optic
correctly archived.
tests/unit/test_competitive_table_matches_data.py binds the prose to the data:
every table row must match competitor-meta.json, no entry may be a recorded
failed lookup, the heading date must be the data's fetch date, and Optic
specifically must read as archived rather than absent. Verified by drifting a
star count and watching it fail.
Verified: ruff, ruff format, mypy (90 files), 432 tests pass.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
API Verity — contract reviewOne comment per PR — updated on each push. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
docs/competitive-analysis.mdcarried this row:and the prose "Dredd/Optic — archived/gone".
Optic's repository is not gone.
opticdev/opticis archived and public, with 1,534 stars, last pushed 2026-01-08.The 404 was ours
scripts/fetch_competitor_meta.pyasked foruseoptic/optic, which does not exist.gh_jsoncaught the resultingCalledProcessErrorand returnedNone; the caller wrote{"error": "repo-not-found-or-error"}intodata/competitor-meta.json; and the document transcribed that tool failure as a fact about a competitor.A typo in a constant became a published claim that a project had disappeared.
Why this one matters beyond accuracy
An archived incumbent with 1,534 stars in exactly this project's domain is the most useful fact in the file — it describes an opening. Recording it as "gone" both stated something false and discarded the signal.
Fixed at the source, not in the table
gh_jsonnow raisesFetchErrorinstead of returningNone, so a failed lookup stops the run and a human decides whether a project moved or genuinely went away.allow_404is threaded through only for the releases endpoint, where absence is a real answer.The landscape table is regenerated from a fetch run today, so every cell is traceable to committed data rather than typed by hand:
What keeps it fixed
tests/unit/test_competitive_table_matches_data.pybinds the prose to the data:competitor-meta.json(license, stars, last push)Verified by drifting a star count and watching it fail.
Verification
ruff check/ruff format --checkmypypytest