Skip to content

Add evidence-backed maintainability analysis#17

Merged
dannote merged 38 commits into
masterfrom
evidence-maintainability-smells
May 21, 2026
Merged

Add evidence-backed maintainability analysis#17
dannote merged 38 commits into
masterfrom
evidence-maintainability-smells

Conversation

@dannote
Copy link
Copy Markdown
Collaborator

@dannote dannote commented May 21, 2026

Summary

  • move clone analysis under Reach.Evidence.* and add shared evidence provider discovery
  • add Reach.Evidence.Fact, AST helpers, and an ExAST-backed pattern runner for reusable evidence providers
  • add standard-library bypass evidence and smell checks for conservative Path/URI, Enum, and Map hand-rolls
  • add Jason plugin evidence and smell checks for hand-rolled JSON sanitizers and direct Jason.Encoder map projections
  • add implicit map-contract evidence with project-level return-shape linking, roles, key coverage, alias/escape tracking, and advisory contract candidates
  • add generic plugin evidence refinement with Jason escape-based map-contract refinement
  • group similar map-contract shapes and split guidance into struct, boundary, and typed-map contract candidates
  • add an evidence corpus scanner and document provider conventions, plugin refinement, corpus review notes, and the evidence-first promotion workflow
  • fix mix reach --help so it prints usage instead of generating the default report

Notes

  • Evidence providers emit reusable facts; smells, checks, and candidates own user-facing policy.
  • Plugin refinement annotates evidence without adding evidence-specific callbacks or moving policy into plugins.
  • Standard-library bypass checks were tuned against Hex package sources. List.flatten/1-based flat-map evidence is medium confidence because recursive flattening is not always equivalent to Enum.flat_map/2.
  • Reduce-based Enum.flat_map/2 evidence now avoids acc ++ [expr] shapes after corpus review showed those are usually map-style reducers.
  • Map-contract evidence remains broad for scanning, while candidate promotion filters noisy roles such as template assigns, accumulators, and low-signal escaped maps.
  • Jason evidence is dependency-gated and avoids treating normal stdlib :json wrappers or non-trivial to_map/1 encoders as hand-rolled direct projections.

Validation

  • mix format --check-formatted
  • MIX_ENV=test mix compile --warnings-as-errors
  • MIX_ENV=test mix test
  • MIX_ENV=test mix reach.check --smells --format json --path lib
  • Hex corpus scan across 6,882 packages in ../hex-playground/sources: 844 evidence hits after tuning, 0 scanner stderr
  • Local evidence scan against ../vibe, ../hologram, and ../analytics: 14 evidence hits, 0 scanner stderr

@dannote dannote force-pushed the evidence-maintainability-smells branch from 5205024 to 9474cf0 Compare May 21, 2026 22:29
@dannote dannote merged commit b1d7408 into master May 21, 2026
2 checks passed
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.

1 participant