No description, website, or topics provided.
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
.circleci Build with CircleCI 2.0 Sep 18, 2018
src/spectrum Missing protocol methods Nov 11, 2018
test/spectrum Test fix Nov 11, 2018
CHANGELOG.md Actual 0.1.4 changelog Jun 17, 2017
README.md bug fixes Feb 21, 2018
project.clj Bug fixes: Mar 10, 2018

README.md

CircleCI Clojars Project

spectrum

A library for doing static analysis of Clojure code, catching clojure.spec conform errors at compile time.

Wait what?

It's like core.typed, but it relies on clojure.spec annotations.

So it's an optional static type system?

Kind-of. It finds errors at compile time, and predicates kind of look like types. So sure.

Proving contracts ahead of time

Current Status

Developer Preview, not yet ready for production use.

Current development is working towards making spectrum self-check.

Goals

  • usable
  • pragmatic
  • readable implementation
  • fast
  • configurable strictness levels
  • incremental checking

Non-goals

  • perfection
  • correctness
  • requiring 100% spec coverage.

In particular, spectrum aims to be fast and usable, and catching bugs. It aims to have low false positives, at the expense of potentially not catching 100% of type errors.

A tool that catches 80% of bugs that you use every day is better than a 100% tool that you don't use. Spectrum will converge on 100% correct, but won't guarantee correctness for a while.

Usage

Use clojure.spec as normal. Then, at the repl or during tests:

(require '[spectrum.check :as check])

(check/check 'your.namespace)

Returns a seq of Error defrecords.

There is also

(check/type-of '(map inc (range 5)))

which is useful when you want to debug the signature of a form.

type-of can optionally also take a map of keywordized variables to spects

(check/type-of '(string? x) {:x (c/pred-spec #'string?)})
#Value[true]

(check/type-of '(string? x) {:x (c/value 3)})
#Value[false]

Limitations

  • It's still very early. Contributions welcome.

Justification

  • because I could
  • working example of types = proofs = predicates
  • this is extra checking on top of spec, not a replacement for it
  • to get HN to shut up about how adding a static type system to a dynamic language is impossible
  • why not just use spec by itself?
  • instrument doesn't check return values
  • check works best on pure functions with good generators.
  • Not all clojure code is pure
  • Not always easy to write a good generator for all functions (hello, any fn that takes a DB connection)
  • Not always easy to write a generator w/ 100% coverage
  • you can't spec non-defn functions
  • you can't spec higher order functions
  • generative testing with side-effects doesn't work well
  • generative testing gives false negatives in unlikely bugs
  • spec doesn't deal with non-fn vars at all (binding, alter-var-root, set!, etc)
  • generative testing can be slow

Downsides

  • spectrum is 'viral'. Once you start checking, it encourages you to write specs for everything

Plan

Spectrum is still very early, and not ready for production use. Current development is focused on making spectrum self-check.

License

Copyright © 2016 Allen Rohner

Distributed under the Eclipse Public License either version 1.0 or (at your option) any later version.