{"id":23792470,"url":"https://github.com/se2p/litterbox","last_synced_at":"2025-07-20T08:05:00.825Z","repository":{"id":54505104,"uuid":"249758282","full_name":"se2p/LitterBox","owner":"se2p","description":"Static code analysis tool for detecting recurring patterns in Scratch projects.","archived":false,"fork":false,"pushed_at":"2025-02-10T11:54:51.000Z","size":14294,"stargazers_count":26,"open_issues_count":2,"forks_count":6,"subscribers_count":6,"default_branch":"1.9","last_synced_at":"2025-04-07T01:41:59.520Z","etag":null,"topics":["scratch"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/se2p.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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}},"created_at":"2020-03-24T16:23:42.000Z","updated_at":"2025-03-20T16:12:16.000Z","dependencies_parsed_at":"2025-02-10T12:39:56.486Z","dependency_job_id":null,"html_url":"https://github.com/se2p/LitterBox","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/se2p/LitterBox","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/se2p%2FLitterBox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/se2p%2FLitterBox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/se2p%2FLitterBox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/se2p%2FLitterBox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/se2p","download_url":"https://codeload.github.com/se2p/LitterBox/tar.gz/refs/heads/1.9","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/se2p%2FLitterBox/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266087790,"owners_count":23874519,"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","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":["scratch"],"created_at":"2025-01-01T18:35:12.330Z","updated_at":"2025-07-20T08:05:00.806Z","avatar_url":"https://github.com/se2p.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"![LitterBox Logo](src/main/resources/litterbox.png \"LitterBox Logo\")\n\n![License GPL v3](https://img.shields.io/github/license/se2p/LitterBox?color=blue\u0026style=flat-square)\n![Codecov](https://img.shields.io/codecov/c/github/se2p/LitterBox?style=flat-square)\n\nLitterBox is a static code analysis tool for detecting bugs in\n[Scratch](https://scratch.mit.edu/) projects.\n\nBugs in Scratch programs can spoil the fun and inhibit learning\nsuccess. Many common bugs are the result of recurring patterns of bad\ncode. LitterBox provides checks for a collection of common bug\npatterns. Given a Scratch project ID or a file, LitterBox retrieves\nand parses the source code of the project, and reports all instances\nof bug patterns identified. LitterBox can also check for code smells\nand provide metrics about selected Scratch projects.\n\nLitterBox is developed at the\n[Chair of Software Engineering II](https://www.fim.uni-passau.de/lehrstuhl-fuer-software-engineering-ii/)\nand the [Didactics of Informatics](https://ddi.fim.uni-passau.de/) of the [University of Passau](https://www.uni-passau.de).\n\n## Building LitterBox\n\nLitterBox is built using [Maven](https://maven.apache.org/). To\nproduce an executable jar-file, run the following command:\n\n```\nmvn package\n```\n\nThis will produce `target/Litterbox-1.9.2.full.jar`\n\n\n## Using LitterBox\n\nTo see an overview of the command line options available in LitterBox type:\n\n```bash\njava -jar Litterbox-1.9.2.full.jar --help\n```\n\n### Basic usage\n\nLitterBox parses the JSON file of a Scratch project, which contains\nits source code. Given such a JSON file, LitterBox is invoked as follows:\n\n```bash\njava -jar Litterbox-1.9.2.full.jar check --path \u003cpath/to/project.json\u003e\n```\n\nAs a result, LitterBox will report any occurrences of bug patterns or\ncode smells in the project on the console.\n\n\n### Downloading projects\n\nIf you want to check a specific project given its ID (which you can\nfind in the URL of the project), you can use the following command:\n\n```bash\njava -jar Litterbox-1.9.2.full.jar check --project-id \u003cproject-id\u003e --path \u003cpath/to/store/downloaded/project\u003e\n```\n\nWhen invoked this way, LitterBox will retrieve the JSON file\nautomatically from the Scratch-website, store it at the given path,\nand then run checks on it. Note that the Scratch project to be\nanalyzed has to be shared publicly for this.\n\n\n### Checking multiple projects\n\nIf you want to check several projects at once, you can put a list of\nproject IDs to check in a text file (one project ID per line) and\ninvoke LitterBox as follows:\n\n```bash\njava -jar Litterbox-1.9.2.full.jar check --project-list \u003cpath/to/projectidlist.txt\u003e --path \u003cpath/to/projects\u003e\n```\n\nLitterBox will check the given path for the projects.\nIf a project is not found at the given path, LitterBox\nwill download and store it at the given path, and then perform\nthe checks.\n\n\n### Output options\n\nIn addition to the console output, LitterBox can produce output in\ncomma separated value (CSV) or JSON format. LitterBox uses the\nfilename specified in order to decide whether to produce CSV or JSON\noutput:\n\n```bash\njava -jar Litterbox-1.9.2.full.jar check --path \u003cpath/to/project.json\u003e --output \u003cresult.csv\u003e\n```\n\nThe CSV file will contain a high-level summary of the number of\ndifferent bug patterns found in the project; the JSON file will\ncontain a detailed list of all instances of the bug\n\nFurthermore, LitterBox can produce an annotated version of the\nanalyzed Scratch-project, where all occurrences of bug patterns are\nhighlighted with comments.\n\n```bash\njava -jar Litterbox-1.9.2.full.jar check --path \u003cpath/to/project.json\u003e --annotate \u003cresults/\u003e\n```\n\n\nYou can choose the language used for hints and comments in the JSON\nand Scratch output with the `--lang` option.\n\n\n### Selecting bug finders\n\nUsing the `--detectors` command line parameter it is possible to\nspecify which bug patterns to check for. The option takes a\ncomma-separated list of bug patterns, e.g.:\n\n\n```bash\njava -jar Litterbox-1.9.2.full.jar \\\n    check \\\n    --path \u003cpath/to/project.json\u003e \\\n    --detectors endless_recursion,call_without_definition\n```\n\nA full list of available bug checkers can be retrieved using:\n\n```bash\njava -jar Litterbox-1.9.2.full.jar --help\n```\n\nTo select all bug patterns, you can also use the term `bugs` in the\nlist; to select all code smell checks use `smells`.\n\n\n\n### Reporting the bug patterns per script\n\nThe bug patterns can be reported per scripts and procedures instead of for the whole program. In this case, only the bug patterns that can be detected through intra-scripts and intra-procedures analysis are considered.\n\n```bash\njava -jar Litterbox-1.9.2.full.jar check \\\n    --path \u003cpath/to/project.json\u003e \\\n    --output \u003cresult.csv\u003e \\\n    --detectors script-bugs \\\n    --scripts\n```\n\n\n### Deactivating robot finders\n\nTo deactivate finders for the mBlock and Codey Rocky robots set the flag\nin the litterbox.properties file to false. This can reduce the run time of\nthe analysis and the size of a resulting CSV file.\n\n```properties\nissues.load_mblock=false\n```\n\n### Collecting statistics\n\nLitterBox can produce statistics on code metrics of a project (e.g.,\nnumber of blocks, number of sprites, weighted method count):\n\n```bash\njava -jar Litterbox-1.9.2.full.jar \\\n    stats \\\n    --path \u003cpath/to/project.json\u003e \\\n    --output \u003cstatsfile.csv\u003e\n```\n\n### Automatically refactoring projects\n\nSince version 1.7 Litterbox can automatically refactor a given Scratch project to improve its readability:\n\n```bash\njava -jar Litterbox-1.9.2.full.jar \\\n    refactoring \\\n    --path \u003cpath/to/project.json\u003e \\\n    --refactored-projects \u003cpath/to/output-dir\u003e\n```\n\nTo this end, Litterbox uses a multi-objective search-based approach to explore possible\nrefactorings that optimize code readability metrics such as size, complexity and entropy.\nThe resulting set of refactored versions of the original project will be placed in `path/to/output-dir`.\n\n\n## Adding new bug patterns or code smells\n\nTo implement your own bug patterns, extend the `AbstractIssueFinder`\nclass which implements an AST visitor. The `check` method is expected\nto return a set of all `Issue` instances encountered during the\ntraversal. Please use the `addIssue` method provided in the `AbstractIssueFinder`.\n\nTo enable the check, register it in the `IssueTool` class.\nAdd it to the `generateSmellFinders()` method via `registerSmellFinder(new NewFinder, smellFinders)` for smell finders or to the`generateBugFinders()` for bug finders via `registerBugFinder(new NewFinder, bugFinders)`.\n\nPlease also add the name of the finder to `IssueNames_de.properties` / `IssueNames_en.properties` and\nprovide hints in `IssueHints_de.properties` / `IssueHints_en.properties`, so that your finder helps programmers understand how to resolve the issue in their code to improve code quality.\n\n## Website\n\nWe provide a website in which users can check their projects with LitterBox directly by uploading the project file or entering the project ID: [https://scratch-litterbox.org/](https://scratch-litterbox.org/)\n\n## Publications\n\nTo learn more about LitterBox, see the following paper:\n\nG. Fraser, U. Heuer, N. Körber, E. Wasmeier, \"LitterBox: A Linter for Scratch Programs\", \nin Proceedings of the IEEE/ACM 43rd International Conference on Software Engineering: Software Engineering Education and Training (ICSE-SEET) (pp. 183-188). IEEE, 2021.\n[https://doi.org/10.1109/ICSE-SEET52601.2021.00028](https://doi.org/10.1109/ICSE-SEET52601.2021.00028)\n\nTo learn more about bug patterns, see the following paper:\n\nC. Frädrich, F. Obermüller, N. Körber, U. Heuer, and G. Fraser, “Common bugs in scratch programs,” in Proceedings of\nthe 25th Annual Conference on Innovation and Technology in Computer\nScience Education (ITiCSE), pages 89-95, ACM,\n2020. [https://doi.org/10.1145/3341525.3387389](https://doi.org/10.1145/3341525.3387389)\n\nTo learn more about code perfumes, see the following paper:\n\nF. Obermüller, L. Bloch, L. Greifenstein, U. Heuer, and G. Fraser, \"Code Perfumes: Reporting Good Code to Encourage\nLearners\", in Proceedings of the 16th Workshop in Primary and Secondary Computing Education (WiPSCE ’21). ACM,\n2021. [https://arxiv.org/abs/2108.06289](https://arxiv.org/abs/2108.06289)\n\nTo learn more about code patterns in mBlock robot programs, see the following paper:\n\nF. Obermüller, R. Pernerstorfer, L. Bailey, U. Heuer, and G. Fraser, \"Common Patterns in Block-Based Robot Programs\",\nin Proceedings of the 17th Workshop in Primary and Secondary Computing Education (WiPSCE ’22). ACM,\n2022. [https://doi.org/10.1145/3556787.3556859](https://doi.org/10.1145/3556787.3556859)\n\nTo learn if Scratch programmers fix issues and how we detect such fixes:\n\nF. Obermüller and Gordon Fraser, \"Do Scratchers Fix Their Bugs? Detecting Fixes of Scratch Static Analysis Warnings\",\nin Proceedings of the 19th Workshop in Primary and Secondary Computing Education (WIPSCE ’24). ACM,\n2024. [https://doi.org/10.1145/3677619.3678108](https://doi.org/10.1145/3677619.3678108)\n\n\n## Contributors\n\nLitterBox is developed at the\n[Chair of Software Engineering II](https://www.fim.uni-passau.de/lehrstuhl-fuer-software-engineering-ii/)\nand the [Didactics of Informatics](https://ddi.fim.uni-passau.de/) of\nthe [University of Passau](https://www.uni-passau.de).\n\nContributors:\n\nFelix Adler\\\nLisa Bailey\\\nFlorian Beck\\\nLena Bloch\\\nBenedikt Fein\\\nPatric Feldmeier\\\nChristoph Frädrich\\\nGordon Fraser\\\nLuisa Greifenstein\\\nEva Gründinger\\\nMichael Grüner\\\nUte Heuer\\\nAlaa Khalil\\\nNina Körber\\\nSimon Labrenz\\\nJonas Lerchenberger\\\nStephan Lukasczyk\\\nMiriam Münch\\\nFlorian Obermüller\\\nRobert Pernerstorfer\\\nGregorio Robles\\\nLisa-Marina Salvesen\\\nSebastian Schweikl\\\nAndreas Stahlbauer\\\nFlorian Sulzmeier\\\nEwald Wasmeier\n\nLitterBox is supported by the project FR 2955/3-1 funded by the\n\"Deutsche Forschungsgemeinschaft\" and BMBF project\n\"primary::programming\" as part of the Qualitätsoffensive\nLehrerbildung.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fse2p%2Flitterbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fse2p%2Flitterbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fse2p%2Flitterbox/lists"}