{"id":30364903,"url":"https://github.com/jspecify/jspecify-reference-checker","last_synced_at":"2025-10-03T15:03:30.593Z","repository":{"id":156914725,"uuid":"632487960","full_name":"jspecify/jspecify-reference-checker","owner":"jspecify","description":"The reference implementation for the JSpecify nullness specification (and later, its other specifications as well)","archived":false,"fork":false,"pushed_at":"2025-08-12T16:37:08.000Z","size":1068,"stargazers_count":27,"open_issues_count":33,"forks_count":8,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-08-12T18:31:57.978Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://jspecify.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jspecify.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-25T14:05:00.000Z","updated_at":"2025-08-12T16:37:04.000Z","dependencies_parsed_at":"2024-03-05T18:45:44.386Z","dependency_job_id":"277b324b-131d-4b24-9689-3c0ac802eb4b","html_url":"https://github.com/jspecify/jspecify-reference-checker","commit_stats":null,"previous_names":["jspecify/nullness-checker-for-checker-framework"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jspecify/jspecify-reference-checker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jspecify%2Fjspecify-reference-checker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jspecify%2Fjspecify-reference-checker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jspecify%2Fjspecify-reference-checker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jspecify%2Fjspecify-reference-checker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jspecify","download_url":"https://codeload.github.com/jspecify/jspecify-reference-checker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jspecify%2Fjspecify-reference-checker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271215060,"owners_count":24720103,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-19T02:00:09.176Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-19T20:22:07.074Z","updated_at":"2025-10-03T15:03:24.394Z","avatar_url":"https://github.com/jspecify.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# The JSpecify Reference Checker\n\nThis project is **under development** to become the **reference implementation** for the [JSpecify](http://jspecify.org) nullness specification (and later, its other specifications as well). The current goal we're working toward is conformance with version `0.3` of that spec, but it's not there yet.\n\n## A \"reference\" checker\n\nThough it does *check your references* (to see if they're null), that's not the intended meaning!\n\nThis tool's purpose is to report nullness-related findings **correctly** according to the JSpecify standard for nullness annotation semantics. \n\nBut that's its *only* job. Notably, it is:\n\n* **not** expected to have good **performance** characteristics\n* **not** expected to have good **usability** characteristics\n\n... and there is no intention to make it competitive in these ways. Of course real tools by our partner organizations will be better.\n\n## Relationship to Checker Framework and EISOP\n\nThe [EISOP project](https://eisop.github.io/) maintains a fork of [Checker Framework](https://checkerframework.org/), and JSpecify conformance is one of its primary goals.\n\nThis tool happens to be built on top of another fork of these ([here](https://github.com/jspecify/checker-framework)). However, please view this relationship as **implementation detail** only. Building a reference checker from scratch would simply have been too difficult, so we needed to base it on some existing tool. The choice of which tool was made purely for expediency and is **subject to change**.\n\n## Usage\n\nBuilding and running this tool requires building code from several other repositories, but these instructions will take care of that automatically.\n\nThese instructions might require workarounds or fail outright. Please file an issue if you have any trouble!\n\n### Prework\n\nIdeally set `JAVA_HOME` to a JDK 11 or JDK 17 installation.\n\nMake sure you have Apache Maven installed and in your PATH, or the Gradle build will fail:\n\n```sh\nmvn\n```\n\nChoose a name for a brand new directory that doesn't already exist. It may be convenient to set `$root_dir` to that absolute path:\n\n```sh\nroot_dir=/absolute/pathname/for/fresh/new/directory\n```\n\n... because then you can paste the commands below exactly as they are.\n\n### Building\n\nNow get the code for this project. \n\n**Warning:** If you clone this project under a different name, watch out, as the later steps assume it to be named exactly `jspecify-reference-checker`.\n\n```sh\nmkdir $root_dir\ncd $root_dir\ngit clone https://github.com/jspecify/jspecify-reference-checker\ncd jspecify-reference-checker\n```\n\nNow build it, which will retrieve a lot of other code too, and will take 10-15\nminutes:\n\n```sh\n./gradlew assemble\n```\n\n### Demonstration\n\nRun the checker on the sample file:\n\n```sh\ncd $root_dir/jspecify-reference-checker\n./demo SimpleSample.java\n```\n\n(If you haven't [built the reference checker](#building) yet, this will build it\nthe first time you run it.)\n\nAfter that, you should see:\n\n```\nSimpleSample.java:7: error: [nullness] incompatible types in return.\n    return mightBeNull;\n           ^\n  type of expression: Object?\n  method return type: Object\n1 error\n```\n\nNote that the `demo` script is not complicated, and illustrates how you can enable checking for your own code as well.\n\n### Testing\n\nTo perform a minimal test, run:\n\n```sh\ncd $root_dir/jspecify-reference-checker\n./gradlew test\n```\n\nTo run the (incomplete) conformance test suite, check out the `main` branch of `jspecify` and run `conformanceTest`:\n\n```sh\ngit -C $root_dir/jspecify checkout main\ncd $root_dir/jspecify-reference-checker\n./gradlew conformanceTests\n```\n\nTo run the (legacy) \"samples\" test suite, check out the `samples-google-prototype` branch of `jspecify` and run `jspecifySamplesTest`:\n\n```sh\ngit -C $root_dir/jspecify checkout samples-google-prototype\ncd $root_dir/jspecify-reference-checker\n./gradlew jspecifySamplesTest\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjspecify%2Fjspecify-reference-checker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjspecify%2Fjspecify-reference-checker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjspecify%2Fjspecify-reference-checker/lists"}