{"id":19359907,"url":"https://github.com/codacy/codacy-example-tool","last_synced_at":"2025-02-24T12:17:21.773Z","repository":{"id":45878169,"uuid":"225879648","full_name":"codacy/codacy-example-tool","owner":"codacy","description":"Docker engine example for a codacy tool","archived":false,"fork":false,"pushed_at":"2023-07-26T09:54:04.000Z","size":49,"stargazers_count":0,"open_issues_count":0,"forks_count":2,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-02-16T11:28:00.408Z","etag":null,"topics":["codacy","docker","engine","example","tool"],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/codacy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-04T13:56:39.000Z","updated_at":"2021-11-05T15:41:52.000Z","dependencies_parsed_at":"2025-01-06T18:50:07.879Z","dependency_job_id":"941ebfc2-76cb-44f4-9e7f-f9040a447d85","html_url":"https://github.com/codacy/codacy-example-tool","commit_stats":null,"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codacy%2Fcodacy-example-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codacy%2Fcodacy-example-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codacy%2Fcodacy-example-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/codacy%2Fcodacy-example-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/codacy","download_url":"https://codeload.github.com/codacy/codacy-example-tool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240475237,"owners_count":19807292,"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":["codacy","docker","engine","example","tool"],"created_at":"2024-11-10T07:16:29.972Z","updated_at":"2025-02-24T12:17:21.754Z","avatar_url":"https://github.com/codacy.png","language":"Shell","readme":"# Codacy Example Tool [![Codacy Badge](https://api.codacy.com/project/badge/Grade/7622fdf861c34d69971a8b04aca65fef)](https://www.codacy.com/gh/codacy/codacy-example-tool?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=codacy/codacy-example-tool\u0026amp;utm_campaign=Badge_Grade) [![Build Status](https://circleci.com/gh/codacy/codacy-example-tool.svg?style=shield\u0026circle-token=:circle-token)](https://circleci.com/gh/codacy/codacy-example-tool)\n\nDocker engine example for a Codacy tool.\n\nThis repository is an example of a tool and has the instructions to develop and \ntest a [Codacy Tool](#what-is-a-codacy-tool).\n\n## Documentation\n\n### What is a Codacy tool\n\nA Codacy Tool is a Docker-based container that wraps linters or tools, ingesting \ntheir result and outputting a standardised json document that can be ingested by \nCodacy. \nThe accepted output format can be found at [Output format](#output-format) section.\n\nAs input the tool accepts a configuration file, [.codacyrc](#structure).\n\n### How to integrate an external analysis tool on Codacy\n\nBy creating a docker and writing code to handle the tool invocation and output,\nyou can integrate the tool of your choice on Codacy!\n\n\u003e To know more about dockers, and how to write a docker file please refer to\n\u003e [https://docs.docker.com/reference/builder/](https://docs.docker.com/reference/builder/)\n\nYou can check the code of an already implemented tool and, if you wish, fork it\nto start your own. You are free to modify and use it for your own tools.\n\n#### Structure\n\n* In order to run the tool, it's necessary to include a configuration file \n[`/.codacyrc`](#structure-of-the-codacyrc-file), containing information about the language and potential additional parameters.\n* The source code to be analysed will be located in `/src`, meaning that when\n  provided in the configuration, the file paths are relative to `/src`.\n\n##### Structure of the .codacyrc file\n\nThis file has:\n\n* **files:** Files to be analysed (their path is relative to `/src`)\n* **tools:** Array of tools\n  * **name:** Unique identifier of the tool. This will be provided by the tool\n    in patterns.json file.\n  * **patterns:** Array of patterns that must be checked\n    * **patternId:** Unique identifier of the pattern\n    * **parameters:** Parameters of the pattern\n      * **name:** Unique identifier of the parameter\n      * **value:** Value to be used as parameter value\n\n```json\n{\n  \"files\" : [\"foo/bar/baz.js\", \"foo2/bar/baz.php\"],\n  \"tools\":[\n    {\n      \"name\":\"jshint\",\n      \"patterns\":[\n        {\n          \"patternId\":\"latedef\",\n          \"parameters\":[\n            {\n              \"name\":\"latedef\",\n              \"value\":\"vars\"\n            }\n          ]\n        }\n      ]\n    }\n  ]\n}\n```\n\n##### Behavior of the configuration file \n\nThe tool parses the configuration file provided and uses it to define its own behaviour. \nThis configuration file is the way to specify which source files to analyse and \nwhich patterns to include in that analysis.\n\nDepending on the configuration, the tool should have different behaviours for\nthe following situations:\n\n* If `/.codacyrc` exists:\n\n  * Files defined -\u003e run tool on the source files passed (an empty array is still defined).\n\n  * Files undefined -\u003e run tool for all source files inside `/src`.\n\n  * Patterns defined -\u003e run tool with the defined patterns (an empty array is still defined).\n\n  * Patterns undefined -\u003e run tool with the native configuration file if present, otherwise use the tool default patterns.\n\n* If `/.codacyrc` does not exist, run the tool for all source files on `/src` using the tool's native configuration or with the default patterns (if native configuration does not exist).\n\n* If `/.codacyrc` fails to be parsed, throw an error.\n\n##### General tool behavior\n\n**Exit codes**:\n\n* The exit codes are different, depending on the tool invocation is successful or not:\n  * **0**: The tool executed successfully :tada:\n  * **1**: An unknown error occurred while running the tool :cold_sweat:\n  * **2**: Execution timeout :alarm_clock:\n\n**Environment variables**:\n\n* To run the tool in debug mode, so you can have more detailed logs, you need to\n  set the environment variable `DEBUG` to `true` when invoking the docker.\n* To configure a different timeout for the tool, you have to set the environment\n  variable `TIMEOUT_SECONDS` when you run the docker image, setting it with values\n  like `10` or `1800` (30 minutes).\n\n#### Output format\n\nAfter you have your results from the tool, you should print them \nto the standard output, one per line:\n\n- filename: file where the issue was found\n- message: issue message returned by the linter\n- patternId: pattern the issue corresponds to\n- line: line where the issue was found\n\n```\n{\n    \"filename\":\"codacy/core/test.js\",\n    \"message\":\"found this in your code\",\n    \"patternId\":\"latedef\",\n    \"line\":2\n}\n```\n\n\u003e The filename should not be the absolute path (not include the `/src/`)\n\u003e `/src/codacy/core/test.js` should be returned as `codacy/core/test.js`\n\n#### Setup\n\n##### Requirements\n\n* [Docker](https://docs.docker.com/v17.09/engine/installation/)\n\n1. Write the docker file that will run the tool.\n    * It must have a binary entry point without any parameters.\n\n2. Write a patterns.json ([schema](schemas/patterns_json_schema.json)) with the configuration of your tool.\n    * This file must be located on /docs/patterns.json.\n      * **name:** Unique identifier of the tool (lower-case letters without\n        spaces)\n      * **version:** Tool version to display in the Codacy UI\n      * **patterns:** The patterns that the tool provides\n          * **patternId:** Unique identifier of the pattern (lower-case letters\n            without spaces)\n          * **level:** Severity level of the issue\n          * **category:** Category of the issue\n          * **parameters:** Parameters received by the pattern\n            * **name:** Unique identifier of the parameter (lower-case letters\n              without spaces)\n            * **default:** Default value of the parameter. \n              **The tool must ensure the default value is used when it is not sent on the configuration file.**\n\n    ```json\n    {\n        \"name\":\"jshint\",\n        \"version\": \"1.2.3\",\n        \"patterns\":[\n        {\n            \"patternId\": \"latedef\",\n            \"category\": \"ErrorProne\",\n            \"parameters\": [\n            {\n                \"name\": \"latedef\",\n                \"default\": \"nofunc\"\n            }\n            ],\n            \"level\": \"Warning\"\n        }\n        ]\n    }\n    ```\n\n3. Write the code to run the tool\n\n  You can write the code in any language you want but, you have to invoke the\n  tool according to the configuration. After you have your results from the\n  tool, you should print them to the standard output in our Result format ([schema](schemas/output_schema.json)), one\n  result per line.\n\n* The filename should **not** include the prefix \"/src/\". Example:\n  * absolute path: /src/folder/file.js\n  * filename path: folder/file.js\n\n  ```json\n  {\n      \"filename\":\"codacy/core/test.js\",\n      \"message\":\"found this in your code\",\n      \"patternId\":\"latedef\",\n      \"line\":2\n  }\n  ```\n\n* If you are not able to run the analysis for any of the files requested you\n  should return an error for each one of them to the standard output in our\n  Error format.\n\n   ```json\n   {\n     \"filename\":\"codacy/core/test.js\",\n     \"message\":\"could not parse the file\"\n   }\n   ```\n\n* When an unknown error occurred while running the tool, it should send the\n  error information through the standard error and exit with error code 1. See\n  exit codes section.\n\n#### Tool Documentation\n\nAt Codacy we strive to provide the best value to our users and, to accomplish\nthat, we document our patterns so that the user can better understand the\nproblem and fix it.\n\nAt this point, your tool has everything it needs to run, but there is one other\nreally important thing that you should do before submitting your docker: the\ndocumentation for your tool.\n\nYour files for this section should be placed in /docs/description/.\n\nIn order to provide more details you can create:\n\n* A single /docs/description/description.json file.\n* A /docs/description/`\u003cPATTERN-ID\u003e.md` file for each pattern.\n\n##### Levels and Categories\n\nFor level types we have:\n\n* Error - High priority issues. These issues show the code that is very susceptible to problems.\n* Warning - You should be careful abou these issues as they are based on code standards and conventions.\n* Info - The least critical issue type.\n\nFor category types we have:\n\n* ErrorProne - Code that may hide bugs.\n* CodeStyle - Code formatting and syntax problems.\n* Complexity - Code that is highly complex and that should be refactored.\n* UnusedCode - Code that is never used\n* Security - Code that may have security issues\n* Compatibility - Compatibility problems across different versions (mainly for frontend code)\n* Performance - Code that has performance problems\n* Documentation - Methods and classes that do not have the correct comment annotations\n* BestPractice\n\n##### Description structure\n\nThe documentation description is optional but must be added as much as possible.\n\nIn the `description.json` ([schema](schemas/description_json_schema.json)) you define the title for the pattern, brief description,\ntime to fix (in minutes), and also a description of the parameters in the\nfollowing format:\n\n```json\n[\n  {\n    \"patternId\": \"latedef\",\n    \"title\": \"Enforce variable def before use\",\n    \"description\": \"Prohibits the use of a variable before it was defined.\",\n    \"parameters\": [\n      {\n        \"name\": \"latedef\",\n        \"description\": \"Declaration order verification. Check all [true] | Do not check functions [nofunc]\"\n      }\n    ],\n    \"timeToFix\": 10\n  }\n]\n```\n\nTo give a more detailed explanation about the issue, you should define the\n`\u003cPATTERN-ID\u003e.md`. Example:\n\n```markdown\nFields in interfaces are automatically public static final, and methods are\npublic abstract.\nClasses or interfaces nested in an interface are automatically public and static\n(all nested interfaces are automatically static).\n\nFor historical reasons, modifiers which are implied by the context are accepted\nby the compiler, but are superfluous.\n\nEx:\n\n    public interface Foo {\n        public abstract void bar();         // both abstract and public are ignored by the compiler\n        public static final int X = 0;         // public, static, and final all ignored\n        public static class Bar {}             // public, static ignored\n        public static interface Baz {}         // ditto\n\n        void foo();                            //this is correct\n    }\n\n    public class Bar {\n        public static interface Baz {} // static ignored\n    }\n\n[Source](http://pmd.sourceforge.net/pmd-5.3.2/pmd-java/rules/java/unusedcode.html#UnusedModifier)\n```\n\nYou should explain the what and why of the issue. Adding an example is always a\nnice way to help other people understand the problem. For a more thorough\nexplanation you can also add a link at the end referring a more complete source.\n\n**Notes:**\n\n* Documentation Generator: This documentation should also be generated\n  automatically to avoid having to go through all of the files each time it\n  needs to be updated.\n\n#### Test\n\nFollow the instructions at\n[codacy-plugins-test](https://github.com/codacy/codacy-plugins-test/blob/master/README.md#test-definition).\n\n#### Submit the docker\n\n**Running the docker**:\n\n```bash\ndocker run -t \\\n--net=none \\\n--privileged=false \\\n--cap-drop=ALL \\\n--user=docker \\\n--rm=true \\\n-v \u003cPATH-TO-FOLDER-WITH-FILES-TO-CHECK\u003e:/src:ro \\\n\u003cYOUR-DOCKER-NAME\u003e:\u003cYOUR-DOCKER-VERSION\u003e\n```\n\n**Docker restrictions**:\n\n* Docker image size should not exceed 500MB\n* Docker should contain a non-root user named docker with UID/GID 2004, associated with a docker group\n* All the source code of the docker must be public\n* The docker base must officially be supported on DockerHub\n* Your docker must be provided in a repository through a public git host (ex:\n  GitHub, Bitbucket, ...)\n\n**Docker submission**:\n\n* To submit the docker you should send an email to support@codacy.com with the\n  link to the git repository with your docker definition.\n* The docker will then be subjected to a review by our team and we will then\n  contact you with more details.\n\nIf you have any question or suggestion regarding this guide please contact us at\nsupport@codacy.com.\n\n## What is Codacy\n\n[Codacy](https://www.codacy.com/) is an Automated Code Review Tool that monitors\nyour technical debt, helps you improve your code quality, teaches best practices\nto your developers, and helps you save time in Code Reviews.\n\n### Among Codacy’s features\n\n* Identify new Static Analysis issues\n* Commit and Pull Request Analysis with GitHub, BitBucket/Stash, GitLab (and\n  also direct git repositories)\n* Auto-comments on Commits and Pull Requests\n* Integrations with Slack, HipChat, Jira, YouTrack\n* Track issues in Code Style, Security, Error Proneness, Performance, Unused\n  Code and other categories\n\nCodacy also helps keep track of Code Coverage, Code Duplication, and Code\nComplexity.\n\nCodacy supports PHP, Python, Ruby, Java, JavaScript, and Scala, among others.\n\n### Free for Open Source\n\nCodacy is free for Open Source projects.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodacy%2Fcodacy-example-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcodacy%2Fcodacy-example-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcodacy%2Fcodacy-example-tool/lists"}