{"id":49109942,"url":"https://github.com/jpipe-mcscert/jpipe-compiler","last_synced_at":"2026-05-08T03:20:29.775Z","repository":{"id":191005547,"uuid":"654361141","full_name":"jpipe-mcscert/jpipe-compiler","owner":"jpipe-mcscert","description":"Justification diagrams made easier!","archived":false,"fork":false,"pushed_at":"2026-04-21T03:20:11.000Z","size":43085,"stargazers_count":23,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-04-21T04:43:15.552Z","etag":null,"topics":["compiler","continuous-deployment","continuous-integration","justification","language","modelling","pipeline"],"latest_commit_sha":null,"homepage":"https://www.jpipe.org/","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jpipe-mcscert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-06-16T01:02:08.000Z","updated_at":"2026-04-21T03:18:39.000Z","dependencies_parsed_at":"2023-08-27T17:26:44.772Z","dependency_job_id":"3af67732-a409-4da8-ac7b-6c4a1849892b","html_url":"https://github.com/jpipe-mcscert/jpipe-compiler","commit_stats":null,"previous_names":["ace-design/jpipe","jpipe-mcscert/jpipe-compiler"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/jpipe-mcscert/jpipe-compiler","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpipe-mcscert%2Fjpipe-compiler","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpipe-mcscert%2Fjpipe-compiler/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpipe-mcscert%2Fjpipe-compiler/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpipe-mcscert%2Fjpipe-compiler/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jpipe-mcscert","download_url":"https://codeload.github.com/jpipe-mcscert/jpipe-compiler/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jpipe-mcscert%2Fjpipe-compiler/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32764944,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-08T02:36:36.067Z","status":"ssl_error","status_checked_at":"2026-05-08T02:36:07.210Z","response_time":54,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["compiler","continuous-deployment","continuous-integration","justification","language","modelling","pipeline"],"created_at":"2026-04-21T04:06:03.626Z","updated_at":"2026-05-08T03:20:29.769Z","avatar_url":"https://github.com/jpipe-mcscert.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# jPipe - Justified Pipelines\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"jPipe logo\" src=\"./docs/logo.svg\" height=\"100\" style=\"vertical-align:middle\"\u003e\n  \u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;\n  \u003cimg alt=\"McSCert logo\" src=\"./docs/sponsors/mcscert.svg\" height=\"100\" style=\"vertical-align:middle\"\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\nThe jPipe environment supports the definition of justification to support software maintenance activities. The name comes from \"justified pipelines\", as the key idea is to design an environment supporting the justification of CI/CD pipelines by design.\n\n## General Information\n\n- Principal Investigator:\n  - [Sébastien Mosser](https://mosser.github.io/), McSCert, McMaster University.\n- Active Contributors:\n  - [Kalvin Thuan-Phong Khuu](https://kalvinkhuu.github.io/), McSCert, McMaster University. PhD Student.\n- Contributors:\n  - [Nirmal Chaudhari](https://www.linkedin.com/in/nirmal2003/), McSCert, McMaster University. Undergraduate Research Assistant.\n  - [Aaron Loh](https://www.linkedin.com/in/aaron-loh26/), McSCert, McMaster University. Undergraduate Research Assistant.\n  - [Deesha Patel](https://www.linkedin.com/in/deeshupatel/), McSCert, McMaster University. Master Student.\n  - [Corinne Pulgar](https://www.linkedin.com/in/corinne-pulgar-12a58190/), École de Technologie Supérieure (ETS). Master Student.\n\n### Repository organization\n\n- `jpipe-lang`: ANTLR4 grammar and generated lexer/parser\n- `jpipe-model`: domain model (justification elements, symbol table)\n- `jpipe-operators`: composition operator extension point and built-in operators\n- `jpipe-compiler`: compiler pipeline (parsing, model building, validation, export)\n- `jpipe-cli`: command-line interface and fat JAR entry point\n- `docs`: technical documentation and architecture decision records\n- `homebrew`: launcher script template for the Homebrew formula\n- `debian`: Debian source packaging metadata for the Ubuntu PPA\n\n### Developer Setup\n\n#### Required tools\n\n| Tool | Version | Purpose |\n|---|---|---|\n| [JDK](https://adoptium.net/) | 25 | Compilation and runtime |\n| [Maven](https://maven.apache.org/) | 3.x | Build tool |\n| [adr-tools](https://github.com/npryce/adr-tools) | latest | Browsing and creating architecture decision records |\n\n#### Optional tools\n\n| Tool | Version | Purpose |\n|---|---|---|\n| [MkDocs Material](https://squidfunk.github.io/mkdocs-material/) | latest | Previewing the documentation site locally (`mkdocs serve`) |\n\n#### Building\n\n```bash\nmvn package\n```\n\nThe fat JAR is produced in `jpipe-cli/target/`.\n\n#### Releasing a new version\n\nReleases are triggered by pushing a `v*.*.*` tag to `main`. The pipeline\ncreates a GitHub Release, updates the Homebrew formula, and uploads a Debian\nsource package to the Ubuntu PPA.\n\n**Prerequisites:** The following secrets must be configured in the GitHub\nrepository settings:\n\n| Secret | Purpose |\n|--------|---------|\n| `HOMEBREW_TAP_TOKEN` | PAT with write access to `jpipe-mcscert/homebrew-mcscert` |\n| `GPG_PRIVATE_KEY` | ASCII-armored GPG key registered on Launchpad |\n| `GPG_KEY_ID` | Fingerprint of the signing key |\n| `GPG_PASSPHRASE` | Passphrase for the signing key |\n\n**Steps:**\n\n```bash\n# 1. Verify the base version in pom.xml matches what you plan to tag.\n#    pom.xml should be X.Y.Z-SNAPSHOT; the pipeline strips -SNAPSHOT automatically.\nmvn verify   # confirm the build is green locally\n\n# 2. Tag and push — the pipeline fires automatically.\ngit tag vX.Y.Z          # or vX.Y.Z-rcN for a pre-release\ngit push origin main --tags\n\n# 3. After the pipeline completes, bump to the next development version.\nmvn -B versions:set -DnewVersion=X.Y+1.0-SNAPSHOT -DgenerateBackupPoms=false\ngit commit -am \"chore: bump to X.Y+1.0-SNAPSHOT\"\ngit push origin main\n```\n\n**What happens automatically:**\n\n1. The pipeline validates that the tag version matches the base version in `pom.xml`\n   (e.g. tag `v2.1.0` is accepted when `pom.xml` declares `2.1.0-SNAPSHOT`).\n2. `mvn versions:set` is run inside the pipeline to stamp the exact release version\n   into the fat JAR manifest (`Implementation-Version: X.Y.Z`).\n3. A GitHub Release is created with the fat JAR and a Homebrew tarball.\n   Tags containing `-` (e.g. `-rc1`) are automatically marked as pre-releases.\n4. `jpipe.rb` in the Homebrew tap is updated with the new URL and SHA256\n   (stable releases only — skipped for pre-releases).\n5. A signed Debian source package is uploaded to `ppa:mcscert/ppa`\n   (stable releases only — skipped for pre-releases).\n\n**Verifying the release** (~30 min after the pipeline completes):\n\n```bash\n# macOS\nbrew tap jpipe-mcscert/mcscert\nbrew install jpipe\n\n# Ubuntu\nsudo add-apt-repository ppa:mcscert/ppa\nsudo apt update \u0026\u0026 sudo apt install jpipe\n```\n\n#### Code style\n\nFormatting is enforced by Spotless (Google Java Format) and Checkstyle. To auto-format before committing:\n\n```bash\nmvn spotless:apply\n```\n\n#### Build output / shade warnings\n\nThe fat JAR build (`jpipe-cli`) merges many dependencies and would normally emit overlap warnings from the Maven Shade plugin. These are suppressed by default via `.mvn/jvm.config`. To re-enable them for a single run:\n\n```bash\nmvn package -Dorg.slf4j.simpleLogger.log.org.apache.maven.plugins.shade.DefaultShader=warn\n```\n\n## Usage\n\n### Running the compiler\n\nAfter building, the fat JAR is at `jpipe-cli/target/jpipe-cli-*.jar`. The\n`process` subcommand is the default, so these two invocations are equivalent:\n\n```bash\njava -jar jpipe-cli/target/jpipe-cli-*.jar -i my.jd -d MyModel -f dot\njava -jar jpipe-cli/target/jpipe-cli-*.jar process -i my.jd -d MyModel -f dot\n```\n\n### Common flags\n\n| Flag | Short | Description |\n|------|-------|-------------|\n| `--input FILE` | `-i` | Input `.jd` source file (default: stdin) |\n| `--output FILE` | `-o` | Output file (default: stdout) |\n| `--diagram NAME` | `-d` | Name of the model to export (required) |\n| `--format FORMAT` | `-f` | Output format — see table below (default: `JPIPE`) |\n| `--headless` | | Suppress the logo banner |\n| `--log-level LEVEL` | | Log verbosity: `OFF` `ERROR` `WARN` `INFO` `DEBUG` `TRACE` |\n\n### Output formats\n\n| Format | Description | Requires Graphviz |\n|--------|-------------|:-----------------:|\n| `JPIPE` | Canonical jPipe source (round-trip) | No |\n| `DOT` | Graphviz DOT source | No |\n| `PNG` | Rendered PNG image | Yes |\n| `JPEG` | Rendered JPEG image | Yes |\n| `SVG` | Rendered SVG image | Yes |\n| `JSON` | JSON model dump | No |\n| `PYTHON` | Python object model | No |\n\nInstall [Graphviz](https://graphviz.org/) and run `jpipe doctor` to verify that\nthe `dot` binary is on your `PATH` before using image formats.\n\n### Other subcommands\n\n```bash\n# Parse and validate without exporting — prints diagnostics, statistics, and the symbol table\njava -jar jpipe-cli/target/jpipe-cli-*.jar diagnostic -i my.jd\n\n# Check runtime dependencies (Graphviz)\njava -jar jpipe-cli/target/jpipe-cli-*.jar doctor\n```\n\n### Minimal `.jd` example\n\n```\njustification MyModel {\n    conclusion  c  is \"Our claim\"\n    strategy    s  is \"Argument\"\n    evidence    e1 is \"Evidence A\"\n    evidence    e2 is \"Evidence B\"\n\n    s  supports c\n    e1 supports s\n    e2 supports s\n}\n```\n\nCompile it to a DOT diagram:\n\n```bash\njava -jar jpipe-cli/target/jpipe-cli-*.jar -i my.jd -d MyModel -f dot -o my.dot\ndot -Tpng my.dot -o my.png\n```\n\nMore examples are in the [`examples/`](examples/) directory.\n\n## How to cite?\n\n```bibtex\n@software{mcscert:jpipe,\n  author = {Mosser, Sébastien and Khuu, Kalvin Thuan-Phong and Chaudhari, Nirmal and Loh, Aaron and Patel, Deesha and Pulgar, Corinne},\n  license = {MIT},\n  title = {{jPipe}},\n  url = {https://github.com/jpipe-mcscert/jpipe-compiler}\n}\n```\n\n## How to contribute?\n\nFound a bug, or want to add a cool feature? Feel free to fork this repository and send a pull request.\n\nIf you're interested in contributing to the research effort related to jPipe, feel free to contact the PI: [Dr. Sébastien Mosser](mailto:mossers@mcmaster.ca).\n\n**We do have undergrad summer internships available to contribute to the compiler, as\nwell as MASc and PhD positions in Software Engineering at Mac.**\n\n### AI assistance policy\n\nParts of this codebase were developed with the assistance of [Claude](https://claude.ai) (Anthropic), an AI coding assistant. We are transparent about this use and welcome AI-assisted contributions, subject to the following conditions:\n\n- Pull requests must not be 100% AI-generated. Every contribution must reflect the understanding and judgement of a human author.\n- Human authors are fully responsible for the correctness, quality, and appropriateness of their contributions, regardless of whether AI tools were used in their preparation.\n- Reviewers may ask contributors to explain any part of their submission.\n\n## Sponsors\n\nWe acknowledge the support of the _Natural Sciences and Engineering Research Council of Canada_\n(NSERC), as well as McMaster _Excellence in Research Award_ (EREA) from the Faculty of Engineering.\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg alt=\"NSERC logo\" src=\"./docs/sponsors/nserc.svg\" width=\"300\"\u003e\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpipe-mcscert%2Fjpipe-compiler","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjpipe-mcscert%2Fjpipe-compiler","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjpipe-mcscert%2Fjpipe-compiler/lists"}