eclipse-score / eclipse-score/communication

Bug: api_surface --check-docs crashes with KeyError: 'file' when undocumented symbols exist

Open Beginner friendly
#1,053 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.