v0.4.0 — Plugin API

v0.4.0 — Plugin API: third-party audit checks via entry-points

TLDR. Third-party packages can now register audit checks via [tool.tmaudit.plugins] in pyproject.toml. tmaudit discovers them via importlib.metadata.entry_points, runs them via audit-all per paper, and caches per (paper, plugin, tex) fingerprint.

218 unit tests pass, 14/14 meta-test bugs caught, 44/44 community-files checks pass.

---

🎉 What's new

Finding + @check + entry-points

A user-side plugin is now just:

from tmaudit import Finding, check

@check(name='no-todo', severity='LOW',
       help_text='Flag TODO markers', version='0.1.0')
def flag_todos(tex, config=None):
    return [
        Finding(category='TODO', severity='LOW',
                message=f'TODO at line {i+1}', line=i+1)
        for i, line in enumerate(tex.splitlines())
        if 'TODO' in line
    ]

declared in your pyproject.toml:

[project.entry-points."tmaudit.plugins"]
no-todo = "my_plugin.checks:flag_todos"

Discovered automatically:

$ pip install -e ./my_plugin
$ tmaudit plugins list        # shows 'no-todo'
$ tmaudit plugins info no-todo
$ tmaudit plugins run no-todo --paper 5

audit-all + cache integration

Plugins run automatically when you tmaudit audit-all. Each plugin's findings are cached by (paper_n, plugin_name, plugin_version, tex_hash) so plugin updates and paper edits both invalidate.

Per-paper disable

'c11_plugins_disabled': ['no-todo'],   # in PAPER_CONFIGS

Example plugin ships in-tree

tmaudit_example_plugin/ (sibling directory) registers three demo checks:

• flag-todo-markers (MEDIUM): flags TODO / FIXME markers.
• flag-xxx-markers (LOW): flags XXX debug markers.
• flag-long-abstract (MEDIUM, configurable): flags abstracts > N words.

Install with pip install -e ./tmaudit_example_plugin and copy as a starting point.

Bug 13 + Bug 14 (meta-test)

• Bug 13: Plugin loader raises on a malformed entry-point.
• Bug 14: Per-paper c11_plugins_disabled is ignored.

Both caught by _check_all_regressions.py (now 14/14).

§14 engineering notes

~415 lines, 14 sub-sections documenting the design rationale: motivation, protocol, pyproject schema, discovery, lifecycle, CLI, per-paper override, cache integration, test plan, limitations, roadmap to v1.0, alternative designs, and implementation milestones.

---

📋 Highlights

1. Plugin API (the headline feature of v0.4.0).
2. tmaudit plugins list / info / run subcommands.
3. Per-paper c11_plugins_disabled config.
4. Plugin-fingerprint cache keys (plugin_cache_key).
5. Example plugin ships in-tree (tmaudit_example_plugin/).
6. Bug 13 + Bug 14 meta-tests (regression-injection discipline).
7. §14 engineering notes (415 lines, 14 sub-sections).
8. Paper 5 Bug 6 fix (multi-branch c2_section_pattern).

---

📦 Upgrade from v0.3.0

git pull
pip install -e .[dev]
# Try the example plugin:
pip install -e ./tmaudit_example_plugin
tmaudit plugins list
tmaudit audit-all
python _check_all_regressions.py   # expect 14/14 caught

See RELEASE_NOTES_v0.4.0.md for the full release notes and CHANGELOG.md for commit-by-commit history.