{"id":30894354,"url":"https://github.com/kleinpanic/vtwebcatcli","last_synced_at":"2025-09-08T21:09:28.191Z","repository":{"id":305775413,"uuid":"1021123641","full_name":"kleinpanic/VTWebCatCLI","owner":"kleinpanic","description":"WebcatCLI is a Python-based WebCAT-style pre-submission checker for Java projects. It enforces coding and Javadoc rules, runs JUnit tests with configurable assertions, auto-generates a minimal Maven POM, and verifies 100% method and branch coverage—with an optional `--run-main` mode. This is all based on the Virginia Tech Universities web-CAT rules","archived":false,"fork":false,"pushed_at":"2025-07-29T19:23:30.000Z","size":2405,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-29T21:54:18.481Z","etag":null,"topics":["cli","python","webcat"],"latest_commit_sha":null,"homepage":"","language":"Python","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/kleinpanic.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"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":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-16T23:34:16.000Z","updated_at":"2025-07-29T19:23:34.000Z","dependencies_parsed_at":"2025-07-22T01:12:26.779Z","dependency_job_id":"0b67b964-90ae-423e-83af-76e08ae010f6","html_url":"https://github.com/kleinpanic/VTWebCatCLI","commit_stats":null,"previous_names":["kleinpanic/vtwebcatcli"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kleinpanic/VTWebCatCLI","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2FVTWebCatCLI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2FVTWebCatCLI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2FVTWebCatCLI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2FVTWebCatCLI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kleinpanic","download_url":"https://codeload.github.com/kleinpanic/VTWebCatCLI/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kleinpanic%2FVTWebCatCLI/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274231567,"owners_count":25245625,"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-08T02:00:09.813Z","response_time":121,"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":["cli","python","webcat"],"created_at":"2025-09-08T21:09:25.866Z","updated_at":"2025-09-08T21:09:28.171Z","avatar_url":"https://github.com/kleinpanic.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebcatCLI\n\n## Version : 1.1.4\n\n**WebcatCLI** is a self-contained Python tool that performs Web-CAT-style pre-submission checks on your Java projects:\n\n- **Style \u0026 Formatting**  \n- **Javadoc \u0026 Annotations**  \n- **Testing Conventions**  \n- **Build \u0026 Coverage**  \n- **Cleanup \u0026 Reporting**\n\n---\n\n## Table of Contents\n\n1. [Overview](#overview)  \n2. [Features](#features)  \n3. [Prerequisites](#prerequisites)  \n4. [Installation](#installation)  \n5. [Directory Layout](#directory-layout)  \n6. [Quick Start](#quick-start)  \n7. [CLI Options](#cli-options)  \n8. [Rule Matrix](#rule-matrix)  \n9. [Testing](#testing)  \n10. [Contributing](#contributing)  \n11. [License](#license)  \n\n---\n\n## Overview\n\nWebcatCLI automates style checks, Javadoc validation, test execution, and coverage enforcement **before** you submit your code to a grading/CI system. It:\n\n- Generates a minimal `pom.xml` (JUnit 4 \u0026 JaCoCo) on the fly  \n- Runs `mvn clean verify` (when `--run-tests` is used)  \n- Parses JUnit test XML into a friendly tree  \n- Enforces 100% JaCoCo method \u0026 branch coverage  \n- Tracks and cleans up all generated artifacts  \n\n---\n\n## Features\n\n- **Style \u0026 Formatting**  \n  - Indentation rules (spaces vs. tabs, width)  \n  - Line-length limits  \n  - Single public class per file  \n  - Static-field usage checks  \n  - Empty / unused-method detection  \n\n- **Javadoc \u0026 Annotations**  \n  - Require Javadoc on classes \u0026 methods  \n  - Enforce `@author` / `@version` tags  \n  - Require `@Override` on overridden methods  \n  - Validate `@param` / `@return` tags  \n\n- **Testing \u0026 Coverage**  \n  - `--run-tests` → `mvn clean verify`  \n  - Tree-view of JUnit results with ✅/❌/⏭️ icons  \n  - Coverage summary and gap-tree from JaCoCo XML  \n  - `--enable-cli-report` to regenerate XML via `jacococli.jar`  \n  - `--scan-impossible-branches`: scans Java source files to detect logically impossible branch conditions (predicates that always evaluate to true or false) via AST analysis.\n\n\n- **Cleanup \u0026 Reporting**  \n  - Automatic removal of `pom.xml`, `target/`, downloaded JARs  \n  - `--no-cleanup` to preserve everything  \n  - New `--cleanup` to force cleanup even in debug mode  \n  - Ctrl-C / SIGTERM handler prints a message and cleans up  \n\n---\n\n## Prerequisites\n\n- **Python 3.6+**  \n- **Testing \u0026 Coverage**  \n  - `--scan-impossible-branches`: scans Java source files to detect logically impossible branch conditions (predicates that always evaluate to true or false) via AST analysis.\n- **Java 8+** \u0026 **Maven** (only for `--run-tests`)  \n- Unix-style shell (for bundled `test_webcatcli.sh`)  \n    - Legacy - not needed.  \n\n---\n\n## Installation\n\n```bash\ngit clone https://github.com/your-org/WebcatCLI.git\ncd WebcatCLI\nchmod +x WebcatCLI.py\n# (optional) add to PATH:\nexport PATH=\"$PATH:$(pwd)\"\n```\n\n---\n\n## Directory Layout\n\n```txt\nWebcatCLI/\n├── WebcatCLI.py\n├── README.md\n├── CHANGELOG.md\n├── templates/\n│   ├── CS1114.rules.json\n│   └── CS2114.rules.json\n└── tests/                   ← (not included in pip (future) or GH releases currently (as of 1.1.2).)\n    └── test_webcatcli.sh    ← legacy test harness\n```\n\n\u003e **Note:** the `tests/` folder is **not** shipped in the packaged release; it lives in the repo for CI and local development.\n\n---\n\n## Quick Start\n\nRun style \u0026 test checks:\n\n```bash\n./WebcatCLI.py --run-tests /path/to/my-java-project\n```\n\nRead a single file from stdin:\n\n```bash\ncat Foo.java | ./WebcatCLI.py\n```\n\n---\n\n## CLI Options\n\n| Flag                    | Description                                                        |\n| ----------------------- | ------------------------------------------------------------------ |\n| `-p, --profile \u003cname\u003e`  | Choose `templates/\u003cname\u003e.rules.json` (default: CS2114)             |\n| `--max-line-length \u003cN\u003e` | Override maximum characters per line (`-1` to disable)             |\n| `--no-javadoc`          | Skip **all** Javadoc presence checks                               |\n| `--no-author`           | Skip `@author` tag check                                           |\n| `--no-version`          | Skip `@version` tag check                                          |\n| `--allow-globals`       | Skip static-field usage checks                                     |\n| `--allow-empty`         | Allow empty method bodies                                          |\n| `--allow-unused`        | Allow unused private methods                                       |\n| `--no-annotations`      | Skip checking for `@Test` annotations                              |\n| `--no-delta`            | Don’t require a delta in `assertEquals`                            |\n| `--no-method-cov`       | Disable 100% method coverage enforcement                           |\n| `--no-branch-cov`       | Disable 100% branch coverage enforcement                           |\n| `--no-override`         | Don’t enforce `@Override` on overridden methods                    |\n| `--run-tests`           | After style/test, run `mvn clean verify` and parse coverage        |\n| `--run-main`            | After tests (and coverage), detect \u0026 run any `main()` method       |\n| `--enable-cli-report`   | Download/run `jacococli.jar` to regenerate XML before parsing gaps |\n| `--no-cleanup`          | Preserve generated files \u0026 directories on exit                     |\n| `--cleanup`             | Force cleanup even in debug mode (overrides `--no-cleanup`)        |\n| `--delete-modules-info` | Recursivly finds + deletes modules.info files under project root   |\n| `-h, --help`            | Show usage and exit                                                |\n| `--version`             | Print version (`__version__`) and exit                             |\n\n---\n\n## Rule Matrix\n\n| Rule                                 |        Default        | Configurable | Change via                          |\n| ------------------------------------ | :-------------------: | :----------: | ----------------------------------- |\n| **Indentation: spaces per indent**   |        4 spaces       |      Yes     | JSON template / `--max-line-length` |\n| **Use spaces (no tabs)**             |           ✔️          |      Yes     | JSON template                       |\n| **Max line length**                  |        80 chars       |      Yes     | `--max-line-length`, JSON           |\n| **Javadoc required (class/method)**  |           ✔️          |      Yes     | `--no-javadoc`, JSON                |\n| **`@author` required**               |           ✔️          |      Yes     | `--no-author`, JSON                 |\n| **`@version` required**              |           ✔️          |      Yes     | `--no-version`, JSON                |\n| **One public class/file**            |          ✔️           |     Yes      | JSON                                |\n| **Static-field usage**               | ✔️ (abiity to change) |     Yes      | `--allow-globals`, JSON             |\n| **Empty-method detection**           |          ✔️           |     Yes      | `--allow-empty`, JSON               |\n| **Unused-private-method detection**  |           ✔️          |      Yes     | `--allow-unused`, JSON              |\n| **`@Override` enforcement**          |           ✔️          |      Yes     | `--no-override`, JSON               |\n| **Package Javadoc (`@package`)**     |           ✔️          |      Yes     | `--no-package-annotation`, JSON     |\n| **Require preceding `@package` tag** |           ❌           |      Yes     | `--no-package-javadoc`, JSON        |\n| **Test prefix**                      |         `test`        |      Yes     | JSON                                |\n| **`@Test` annotation required**      |           ❌           |      Yes     | `--no-annotations`, JSON            |\n| **Delta in `assertEquals`**          |           ✔️          |      Yes     | `--no-delta`, JSON                  |\n| **100% method coverage**             |           ✔️          |      Yes     | `--no-method-cov`, JSON             |\n| **100% branch coverage**             |           ✔️          |      Yes     | `--no-branch-cov`, JSON             |\n\n---\n\n## Testing\n\nI’ve moved the old `test_webcatcli.sh` into `tests/` for historical coverage. It:\n\n1. Creates minimal Java projects (good \u0026 bad cases).\n2. Verifies that every flag behaves as expected.\n3. Ensures legacy behavior never regresses.\n\n\u003e **Note:** the `tests/` folder is **not** part of the release tar—developers can clone the repo and run:\n\u003e **Note**: The Test Program Does Not Respect or Consider the JSON configurations when creating and applying these tests. Needs to be updated for next release.\n\n```bash\ncd tests\nchmod +x test_webcatcli.sh\n./test_webcatcli.sh\n```\n\n--- \n\n## License\n\n### WebcatCLI\nWebcatCLI itself is distributed under the [MIT License](LICENSE).\n\n### Bundled Dependencies\nThis repository distributes **student.jar** and **jacococli.jar** as part of the `--run-tests` workflow. You must comply with their licenses:\n\nFor the student.jar license file please unpackage the .jar file and find it yourself. \nOr open the licenses dir\n\n- **Student-Library** (`student.jar`)  \n  Licensed under the GNU Lesser General Public License v2.1.  \n\n- **JUnit** (via Maven dependencies bundled in the generated POM)  \n  Portions of JUnit are under the Eclipse Public License 1.0.  \n\n- **JaCoCo CLI** (`jacococli.jar`)  \n  Licensed under the Apache License 2.0.  \n\nBy distributing these JARs you agree to the terms of their respective licenses.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkleinpanic%2Fvtwebcatcli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkleinpanic%2Fvtwebcatcli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkleinpanic%2Fvtwebcatcli/lists"}