eclipse-score / eclipse-score/communication
Bug: api_surface --check-docs crashes with KeyError: 'file' when undocumented symbols exist
- Dominant language
- C++
- Stars
- 62
- Forks
- 97
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 72
Description
### Description
`api_surface_test(check_docs = True)` crashes with `KeyError: 'file'` as soon as the target has at least one undocumented public symbol, instead of printing the "missing \api documentation" report.
`_format_undocumented_symbols()` (`quality/api_surface/diff_api.py`, line 58) reads `symbol['file']` / `symbol['line']`, but lock entries only carry `name`, `qualified_name`, `kind`, `signature` (see `to_lock_entry()` in `extract_api.py`).
`//score/mw/com:api_surface_docs_test` is tagged `manual`, so this is not caught in CI. The committed lock file currently has 106 undocumented symbols, so the test crashes deterministically.
### Error Occurrence Rate
Reproducible
### How to reproduce
```
bazel test //score/mw/com:api_surface_docs_test --test_output=errors
```
```
File ".../quality/api_surface/diff_api.py", line 75, in compare
undocumented = _format_undocumented_symbols(current_data)
File ".../quality/api_surface/diff_api.py", line 58, in _format_undocumented_symbols
lines.append(f" at {symbol['file']}:{symbol['line']}")
~~~~~~^^^^^^^^
KeyError: 'file'
```
### Supporting Information
Reproduced on `main` @ 8a9a452 (Ubuntu 24.04, Bazel 8.7.0, hermetic toolchain). The affected code in `diff_api.py` is unchanged since v0.3.0. `//score/mw/com:api_surface_test` (`check_docs = False`) passes on the same tree.
### Classification
minor
### Affected Version
v0.3.0
### Category
- [ ] Safety Related
- [ ] Security Related
Contributor guide
Research direction
Read quality/api_surface/diff_api.py, especially _format_undocumented_symbols(), and compare its expected fields with to_lock_entry() in extract_api.py. Run bazel test //score/mw/com:api_surface_docs_test --test_output=errors; done means undocumented symbols produce the missing API documentation report without a KeyError and the test passes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- cpp, python
- Domain
- build-system, testing, tooling
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 88/100