Skip to content

SPEC.md's list_explainers table row and docstring say it reads assets/explainers-data.json, contradicting the code #469

Description

@yakew7

Where: faircode/SPEC.md:391 (the list_explainers MCP tool table row) vs. faircode/mcp_server.py:60-61,243,249 (EXPLAINERS_DIR, _load_explainers_metadata, and _list_explainers_impl's own docstring).

The gap: the table says list_explainers wraps assets/explainers-data.json, and the tool's own docstring says it "reads the same assets/explainers-data.json the website's index page does." The code actually reads faircode/_explainers/data.json - a package-internal generated mirror built by scripts/build_explainers.py, specifically because assets/ isn't a file pyproject.toml ships (issue #388).

Repro:

$ grep -n "EXPLAINERS_DIR\|EXPLAINERS_DATA_JSON" faircode/mcp_server.py
60:EXPLAINERS_DIR = Path(__file__).resolve().parent / "_explainers"
61:EXPLAINERS_DATA_JSON = EXPLAINERS_DIR / "data.json"
$ grep -n "assets/explainers-data.json" faircode/SPEC.md faircode/mcp_server.py
faircode/SPEC.md:391:| `list_explainers` | `assets/explainers-data.json` | ...
faircode/mcp_server.py:249:    same assets/explainers-data.json the website's index page does, so it's

EXPLAINERS_DIR resolves to faircode/_explainers/, not assets/.

Why it matters: this is the exact same category of doc/code mismatch already fixed for get_benchmark_results in #434 - it contradicts the packaging story faircode/SPEC.md tells elsewhere (explaining why faircode/_explainers//faircode/_results_frozen/ exist as generated package-internal mirrors), giving a reader the wrong mental model of what a real pip install faircode[mcp] actually reads from.

Suggested fix: update the SPEC.md table cell to faircode/_explainers/data.json (mirrored from assets/explainers-data.json), and reword the docstring at mcp_server.py:249 to match.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationgood first issueGood for newcomershelp wantedExtra attention is needed

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions