Skip to content

docs: Write 'writing a custom detector' contributor guide (#3) - #17

Open
IronLad123 wants to merge 4 commits into
bamdadd:mainfrom
IronLad123:docs/add-custom-detector-contributor-guide
Open

docs: Write 'writing a custom detector' contributor guide (#3)#17
IronLad123 wants to merge 4 commits into
bamdadd:mainfrom
IronLad123:docs/add-custom-detector-contributor-guide

Conversation

@IronLad123

Copy link
Copy Markdown
Contributor

Closes #3

Summary

Adds a comprehensive contributor guide docs/writing-a-detector.md detailing how to design, implement, register, and test a custom deterministic detector in taintline.

What's Included

  • Detector Protocol & Purity Contract: Explains the Detector protocol (name + run(trace) -> list[Finding]) and zero-LLM / zero-I/O / deterministic constraints (no network, no system clock, no RNG, no un-sorted set iteration).
  • Core Types Explained: Documented Span, Trace (tree navigation helpers root(), in_order(), children()), Finding, and Verdict.
  • Copy-Pasteable Worked Example: Complete step-by-step walkthrough creating an ErrorStatusDetector class, registering it in ALL (src/taintline/detectors/__init__.py), creating a seeded JSON fixture (tests/fixtures/seeded/), and writing unit/acceptance tests.
  • CI Exit Code Gating: Clear explanation of how --fail-on gates the CLI exit code (0 vs 1) independently of finding reporting.
  • Cross-Linked: Linked cleanly from README.md under Detectors and CONTRIBUTING.md.

Verification

  • Markdown rendered cleanly; links validated.
  • pytest: 49/49 passed (1.10s).
  • ruff check: clean (0 issues).

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Write a 'writing a custom detector' contributor guide

1 participant