{"id":31029972,"url":"https://github.com/cowwoc/requirements.java","last_synced_at":"2025-09-13T22:57:26.103Z","repository":{"id":37739559,"uuid":"249211342","full_name":"cowwoc/requirements.java","owner":"cowwoc","description":"Fluent Design Contracts for Java Projects","archived":false,"fork":false,"pushed_at":"2025-08-28T03:48:56.000Z","size":10259,"stargazers_count":27,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-28T10:32:47.167Z","etag":null,"topics":["design-by-contract","invariants","java","postconditions","preconditions","requirements"],"latest_commit_sha":null,"homepage":"","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/cowwoc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"docs/supported_libraries.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"cowwoc"}},"created_at":"2020-03-22T15:21:23.000Z","updated_at":"2025-08-28T03:48:59.000Z","dependencies_parsed_at":"2024-04-11T16:45:00.664Z","dependency_job_id":"03bb3f8d-0447-4330-931d-9e4741242cd0","html_url":"https://github.com/cowwoc/requirements.java","commit_stats":null,"previous_names":[],"tags_count":105,"template":false,"template_full_name":null,"purl":"pkg:github/cowwoc/requirements.java","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowwoc%2Frequirements.java","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowwoc%2Frequirements.java/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowwoc%2Frequirements.java/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowwoc%2Frequirements.java/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cowwoc","download_url":"https://codeload.github.com/cowwoc/requirements.java/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowwoc%2Frequirements.java/sbom","scorecard":{"id":306321,"data":{"date":"2025-08-11","repo":{"name":"github.com/cowwoc/requirements.java","commit":"b8dcbe2405eb6bf8bacc31cb2c7f5439b6080f75"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":4.4,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Maintained","score":10,"reason":"16 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 10","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Dangerous-Workflow","score":10,"reason":"no dangerous workflow patterns detected","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Token-Permissions","score":0,"reason":"detected GitHub workflow tokens with excessive permissions","details":["Info: jobLevel 'contents' permission set to 'read': .github/workflows/build-on-push.yml:13","Info: jobLevel 'actions' permission set to 'read': .github/workflows/build-on-push.yml:14","Warn: jobLevel 'checks' permission set to 'write': .github/workflows/build-on-push.yml:15","Info: jobLevel 'contents' permission set to 'read': .github/workflows/deploy_to_maven_central.yml:72","Info: jobLevel 'actions' permission set to 'read': .github/workflows/deploy_to_maven_central.yml:73","Warn: jobLevel 'checks' permission set to 'write': .github/workflows/deploy_to_maven_central.yml:74","Warn: jobLevel 'packages' permission set to 'write': .github/workflows/deploy_to_maven_central.yml:75","Warn: no topLevel permission defined: .github/workflows/build-on-push.yml:1","Warn: topLevel 'actions' permission set to 'write': .github/workflows/cla.yml:10","Warn: topLevel 'contents' permission set to 'write': .github/workflows/cla.yml:11","Warn: topLevel 'statuses' permission set to 'write': .github/workflows/cla.yml:13","Warn: topLevel 'contents' permission set to 'write': .github/workflows/deploy_to_maven_central.yml:7","Warn: no topLevel permission defined: .github/workflows/reusable-build.yml:1"],"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: Apache License 2.0: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'main'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Info: Possibly incomplete results: error parsing shell code: a command can only contain words and redirects; encountered ): .github/workflows/deploy_to_maven_central.yml:276","Warn: third-party GitHubAction not pinned by hash: .github/workflows/cla.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/cla.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy_to_maven_central.yml:22: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/deploy_to_maven_central.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy_to_maven_central.yml:25: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/deploy_to_maven_central.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy_to_maven_central.yml:31: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/deploy_to_maven_central.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy_to_maven_central.yml:87: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/deploy_to_maven_central.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy_to_maven_central.yml:97: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/deploy_to_maven_central.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy_to_maven_central.yml:261: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/deploy_to_maven_central.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/deploy_to_maven_central.yml:266: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/deploy_to_maven_central.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/reusable-build.yml:21: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/reusable-build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/reusable-build.yml:26: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/reusable-build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/reusable-build.yml:32: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/reusable-build.yml/main?enable=pin","Warn: GitHub-owned GitHubAction not pinned by hash: .github/workflows/reusable-build.yml:66: update your workflow using https://app.stepsecurity.io/secureworkflow/cowwoc/requirements.java/reusable-build.yml/main?enable=pin","Info:   0 out of  11 GitHub-owned GitHubAction dependencies pinned","Info:   0 out of   1 third-party GitHubAction dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-17T22:08:39.465Z","repository_id":37739559,"created_at":"2025-08-17T22:08:39.465Z","updated_at":"2025-08-17T22:08:39.465Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":275038261,"owners_count":25394640,"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-09-13T02:00:10.085Z","response_time":70,"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":["design-by-contract","invariants","java","postconditions","preconditions","requirements"],"created_at":"2025-09-13T22:57:13.784Z","updated_at":"2025-09-13T22:57:26.094Z","avatar_url":"https://github.com/cowwoc.png","language":"Java","funding_links":["https://github.com/sponsors/cowwoc"],"categories":[],"sub_categories":[],"readme":"# \u003cimg src=\"docs/logo.svg\" width=64 height=64 alt=\"checklist\"\u003e Requirements API\n[![build-status](../../workflows/Build/badge.svg)](../../actions?query=workflow%3ABuild)\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.cowwoc.requirements/requirements/badge.svg)](https://central.sonatype.com/search?q=g:io.github.cowwoc.requirements)\n\u003cbr\u003e\n[![API](https://img.shields.io/badge/api_docs-5B45D5.svg)](https://cowwoc.github.io/requirements.java/12.0/)\n[![Changelog](https://img.shields.io/badge/changelog-A345D5.svg)](docs/changelog.md)\n[![javascript, typescript](https://img.shields.io/badge/other%20languages-javascript,%20typescript-457FD5.svg)](../../../requirements.js)\n\nA [fluent API](https://en.wikipedia.org/wiki/Fluent_interface) for\nenforcing [design contracts](https://en.wikipedia.org/docs/Design_by_contract) with\n[automatic message generation](docs/features.md#automatic-message-generation):\n\n✔️ Easy to use\u003cbr\u003e\n✔️ Fast\u003cbr\u003e\n✔️ Production-ready\u003cbr\u003e\n\nTo get started, add this Maven dependency:\n\n```xml\n\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.cowwoc.requirements\u003c/groupId\u003e\n  \u003cartifactId\u003erequirements-java\u003c/artifactId\u003e\n  \u003cversion\u003e12.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n## Usage Example\n\n```java\nimport java.util.List;\nimport java.util.StringJoiner;\n\nimport static io.github.cowwoc.requirements12.java.DefaultJavaValidators.checkIf;\nimport static io.github.cowwoc.requirements12.java.DefaultJavaValidators.requireThat;\nimport static io.github.cowwoc.requirements12.java.DefaultJavaValidators.that;\n\npublic final class Cake\n{\n  private byte bitesTaken = 0;\n  private int piecesLeft;\n\n  public Cake(int piecesLeft)\n  {\n    requireThat(piecesLeft, \"piecesLeft\").isPositive();\n    this.piecesLeft = piecesLeft;\n  }\n\n  public int eat()\n  {\n    ++bitesTaken;\n    assert that(bitesTaken, \"bitesTaken\").isNotNegative().elseThrow();\n\n    piecesLeft -= ThreadLocalRandom.current().nextInt(5);\n\n    assert that(piecesLeft, \"piecesLeft\").isNotNegative().elseThrow();\n    return piecesLeft;\n  }\n\n  public List\u003cString\u003e getFailures()\n  {\n    return checkIf(bitesTaken, \"bitesTaken\").isNotNegative().\n      and(checkIf(piecesLeft, \"piecesLeft\").isGreaterThan(3)).\n      elseGetFailures();\n  }\n}\n```\n\nIf you violate a **precondition**:\n\n```java\nCake cake = new Cake(-1000);\n```\n\nYou'll get:\n\n```\njava.lang.IllegalArgumentException: \"piecesLeft\" must be positive.\nactual: -1000\n```\n\nIf you violate a **class invariant**:\n\n```java\nCake cake = new Cake(1_000_000);\nwhile (true)\n  cake.eat();\n```\n\nYou'll get:\n\n```\njava.lang.AssertionError: \"bitesTaken\" may not be negative.\nactual: -128\n```\n\nIf you violate a **postcondition**:\n\n```java\nCake cake = new Cake(100);\nwhile (true)\n  cake.eat();\n```\n\nYou'll get:\n\n```\njava.lang.AssertionError: \"piecesLeft\" may not be negative.\nactual: -4\n```\n\nIf you violate **multiple** conditions at once:\n\n```java\nCake cake = new Cake(1);\ncake.bitesTaken = -1;\ncake.piecesLeft = 2;\nStringJoiner failures = new StringJoiner(\"\\n\\n\");\nfor (String failure : cake.getFailures())\n    failures.add(failure);\nSystem.out.println(failures);\n```\n\nYou'll get:\n\n```\n\"bitesTaken\" may not be negative.\nactual: -1\n\n\"piecesLeft\" must be greater than 3.\nactual: 2\n```\n\n## Features\n\nThis library offers the following features:\n\n* [Automatic message generation](docs/features.md#automatic-message-generation) for validation failures\n* [Diffs provided whenever possible](docs/features.md#diffs-provided-whenever-possible) to highlight the\n  differences between expected and actual values\n* [Clean stack-traces](docs/features.md#clean-stack-traces) that remove unnecessary frames\n* [Zero overhead when assertions are disabled](docs/features.md#assertion-support) for better performance\n* [Multiple validation failures](docs/features.md#multiple-validation-failures) that report all the errors at\n  once\n* [Nested validations](docs/features.md#nested-validations) that allow you to validate complex objects\n* [String diff](docs/features.md#string-diff) that shows the differences between two strings\n* [Performant and robust](docs/performance.md)\n\n## Entry Points\n\nDesigned for discovery using your favorite IDE's auto-complete feature.\nThe main entry points are:\n\n* [requireThat(value, name)](https://cowwoc.github.io/requirements.java/12.0/io.github.cowwoc.requirements.java/com/github/cowwoc/requirements12/java/DefaultJavaValidators.html#requireThat(T,java.lang.String))\n  for method preconditions.\n* [that(value, name)](https://cowwoc.github.io/requirements.java/12.0/io.github.cowwoc.requirements.java/com/github/cowwoc/requirements12/java/DefaultJavaValidators.html#that(T,java.lang.String))\n  for [class invariants, method postconditions and private methods](docs/features.md#assertion-support).\n* [checkIf(value, name)](https://cowwoc.github.io/requirements.java/12.0/io.github.cowwoc.requirements.java/com/github/cowwoc/requirements12/java/DefaultJavaValidators.html#checkIf(T,java.lang.String))\n  for multiple failures and customized error handling.\n\nSee the [API documentation](https://cowwoc.github.io/requirements.java/12.0/) for more details.\n\n## Best practices\n\n* Use `checkIf().elseGetFailures()` to return failure messages without throwing an exception.\n  This is the fastest validation approach, ideal for web services.\n* To enhance the clarity of failure messages, you should provide parameter names, even when they are optional.\n  In other words, favor `assert that(value, name)` over `assert that(value)`.\n\n## Third-party libraries and tools\n\nThis library supports the following third-party libraries and tools:\n\n* [guava](docs/supported_libraries.md)\n* [IntelliJ IDEA](docs/supported_tools.md)\n\n## Licenses\n\n* This library is licensed under the [Apache License, Version 2.0](LICENSE)\n* See [Third party licenses](LICENSE-3RD-PARTY.md) for the licenses of the dependencies\n* Icons made by Flat Icons from www.flaticon.com are licensed by CC 3.0 BY\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcowwoc%2Frequirements.java","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcowwoc%2Frequirements.java","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcowwoc%2Frequirements.java/lists"}