├── static ├── .nojekyll ├── CNAME ├── img │ ├── logo.png │ ├── favicon.ico │ ├── docusaurus.png │ ├── icon_black.png │ ├── icon_color.png │ ├── icon_white.png │ ├── pixee-logo.png │ ├── CodemodderDM.png │ ├── CodemodderLM.png │ ├── linkedin-icon-dark.svg │ ├── linkedin-icon-light.svg │ ├── slack-icon-dark.svg │ ├── slack-icon-light.svg │ ├── twitter-icon-dark.svg │ ├── twitter-icon-light.svg │ ├── github-icon-dark.svg │ ├── github-icon-light.svg │ ├── logo.svg │ ├── undraw_docusaurus_tree.svg │ ├── undraw_docusaurus_mountain.svg │ └── undraw_docusaurus_react.svg ├── fonts │ ├── Poppins-Bold.woff │ ├── Poppins-Bold.woff2 │ ├── Poppins-Light.woff │ ├── Poppins-Light.woff2 │ ├── Poppins-Regular.woff │ └── Poppins-Regular.woff2 └── js │ ├── handle_double_slash.js │ └── loadtags.js ├── babel.config.js ├── docs ├── languages │ ├── javascript │ │ ├── overview.md │ │ └── _category_.json │ ├── _category_.json │ ├── java │ │ ├── _category_.json │ │ ├── fork_sample.md │ │ ├── overview.md │ │ ├── testing.md │ │ ├── project_setup.md │ │ ├── building_codemod.md │ │ └── write_codemod.md │ └── python │ │ ├── _category_.json │ │ └── overview.md ├── spec.md ├── license.md ├── provided.md ├── faqs.md └── intro.md ├── src ├── pages │ ├── welcome.md │ ├── markdown-page.md │ └── index.module.css ├── components │ └── HomepageFeatures │ │ ├── styles.module.css │ │ └── index.js └── css │ └── custom.css ├── .gitignore ├── README.md ├── sidebars.js ├── package.json ├── .github └── workflows │ └── deploy.yml ├── docusaurus.config.js └── LICENSE.md /static/.nojekyll: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /static/CNAME: -------------------------------------------------------------------------------- 1 | codemodder.io -------------------------------------------------------------------------------- /static/img/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/img/logo.png -------------------------------------------------------------------------------- /static/img/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/img/favicon.ico -------------------------------------------------------------------------------- /static/img/docusaurus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/img/docusaurus.png -------------------------------------------------------------------------------- /static/img/icon_black.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/img/icon_black.png -------------------------------------------------------------------------------- /static/img/icon_color.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/img/icon_color.png -------------------------------------------------------------------------------- /static/img/icon_white.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/img/icon_white.png -------------------------------------------------------------------------------- /static/img/pixee-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/img/pixee-logo.png -------------------------------------------------------------------------------- /static/img/CodemodderDM.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/img/CodemodderDM.png -------------------------------------------------------------------------------- /static/img/CodemodderLM.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/img/CodemodderLM.png -------------------------------------------------------------------------------- /babel.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | presets: [require.resolve('@docusaurus/core/lib/babel/preset')], 3 | }; 4 | -------------------------------------------------------------------------------- /static/fonts/Poppins-Bold.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/fonts/Poppins-Bold.woff -------------------------------------------------------------------------------- /docs/languages/javascript/overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 2 3 | --- 4 | 5 | # JavaScript 6 | 7 | Stay tuned! 8 | -------------------------------------------------------------------------------- /static/fonts/Poppins-Bold.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/fonts/Poppins-Bold.woff2 -------------------------------------------------------------------------------- /static/fonts/Poppins-Light.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/fonts/Poppins-Light.woff -------------------------------------------------------------------------------- /static/fonts/Poppins-Light.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/fonts/Poppins-Light.woff2 -------------------------------------------------------------------------------- /static/fonts/Poppins-Regular.woff: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/fonts/Poppins-Regular.woff -------------------------------------------------------------------------------- /static/fonts/Poppins-Regular.woff2: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/pixee/codemodder-docs/HEAD/static/fonts/Poppins-Regular.woff2 -------------------------------------------------------------------------------- /src/pages/welcome.md: -------------------------------------------------------------------------------- 1 |

2 | 3 |

4 | 5 | 6 | welcome to codemodder -------------------------------------------------------------------------------- /docs/languages/_category_.json: -------------------------------------------------------------------------------- 1 | { 2 | "label": "Languages", 3 | "position": 1, 4 | "link": { 5 | "type": "generated-index" 6 | } 7 | } 8 | -------------------------------------------------------------------------------- /src/pages/markdown-page.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Markdown page example 3 | --- 4 | 5 | # Markdown page example 6 | 7 | You don't need React to write simple standalone pages. 8 | -------------------------------------------------------------------------------- /docs/languages/java/_category_.json: -------------------------------------------------------------------------------- 1 | { 2 | "label": "Java", 3 | "position": 1, 4 | "link": { 5 | "type": "doc", 6 | "id": "languages/java/overview" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /docs/languages/python/_category_.json: -------------------------------------------------------------------------------- 1 | { 2 | "label": "Python", 3 | "position": 2, 4 | "link": { 5 | "type": "doc", 6 | "id": "languages/python/overview" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /docs/languages/javascript/_category_.json: -------------------------------------------------------------------------------- 1 | { 2 | "label": "JavaScript (coming soon)", 3 | "position": 3, 4 | "link": { 5 | "type": "doc", 6 | "id": "languages/javascript/overview" 7 | } 8 | } 9 | -------------------------------------------------------------------------------- /static/js/handle_double_slash.js: -------------------------------------------------------------------------------- 1 | // HN is for some reason sending users to our site with double slash 2 | 3 | !function() { 4 | if(document.location.pathname === '//') { 5 | document.location = '/' 6 | } 7 | }() -------------------------------------------------------------------------------- /src/components/HomepageFeatures/styles.module.css: -------------------------------------------------------------------------------- 1 | .features { 2 | display: flex; 3 | align-items: center; 4 | padding: 2rem 0; 5 | width: 100%; 6 | } 7 | 8 | .featureSvg { 9 | height: 200px; 10 | width: 200px; 11 | } 12 | -------------------------------------------------------------------------------- /docs/languages/python/overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 1 3 | title: Python Codemodder 4 | --- 5 | 6 | ## Quick Links 7 | 8 | Repository: [https://github.com/pixee/codemodder-python/](https://github.com/pixee/codemodder-python/) 9 | 10 | PyPI: [https://pypi.org/project/codemodder/](https://pypi.org/project/codemodder/) 11 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Dependencies 2 | /node_modules 3 | 4 | # Production 5 | /build 6 | 7 | # Generated files 8 | .docusaurus 9 | .cache-loader 10 | 11 | # Misc 12 | .DS_Store 13 | .env.local 14 | .env.development.local 15 | .env.test.local 16 | .env.production.local 17 | 18 | .idea 19 | 20 | npm-debug.log* 21 | yarn-debug.log* 22 | yarn-error.log* 23 | -------------------------------------------------------------------------------- /docs/languages/java/fork_sample.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 1 3 | title: Fork a Sample Project And Get Started 4 | --- 5 | 6 | The easiest way to get started is to fork our [sample project](https://github.com/pixee/simple-gradle-codemod-tutorial/) and start hacking away! If you want to follow along with the tutorial and create a barebones codemod the old-fashioned way, please keep reading on! -------------------------------------------------------------------------------- /docs/spec.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 3 3 | --- 4 | 5 | # Specifications 6 | 7 | The codemodder project includes a collection language-specific libraries for building codemods that meet the [codemodder specifications](https://github.com/pixee/codemodder-specs). These specifications describe things like the inputs (like the CLI parameters to codemods) and the outputs (the file format that describes the changes to make.) 8 | 9 | -------------------------------------------------------------------------------- /docs/languages/java/overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 0 3 | title: Java Codemodder 4 | --- 5 | 6 | ## Quick Links 7 | 8 | Repository: [https://github.com/pixee/codemodder-java](https://github.com/pixee/codemodder-java) 9 | 10 | JavaDoc: [https://www.javadoc.io/doc/io.codemodder](https://www.javadoc.io/doc/io.codemodder) 11 | 12 | ## Tutorial 13 | 14 | This section contains a tutorial on how to build your own Java codemods. -------------------------------------------------------------------------------- /src/pages/index.module.css: -------------------------------------------------------------------------------- 1 | /** 2 | * CSS files with the .module.css suffix will be treated as CSS modules 3 | * and scoped locally. 4 | */ 5 | 6 | .heroBanner { 7 | padding: 4rem 0; 8 | text-align: center; 9 | position: relative; 10 | overflow: hidden; 11 | } 12 | 13 | @media screen and (max-width: 996px) { 14 | .heroBanner { 15 | padding: 2rem; 16 | } 17 | } 18 | 19 | .buttons { 20 | display: flex; 21 | align-items: center; 22 | justify-content: center; 23 | } 24 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Codemodder Documentation 2 | 3 | This repository holds the documentation site at [codemodder.io](https://codemodder.io). It covers information related to building, testing, running and operationalizing codemods built with the codemodder framework across all supported languages. 4 | 5 | ## Building and Running 6 | 7 | ```bash 8 | $ git clone https://github.com/pixee/codemodder-docs.git 9 | $ cd codemodder-docs 10 | $ yarn # only needed the first time 11 | $ yarn start 12 | ``` 13 | 14 | ## Contributing 15 | 16 | We love PRs! 17 | -------------------------------------------------------------------------------- /static/js/loadtags.js: -------------------------------------------------------------------------------- 1 | !function(){var e=window.rudderanalytics=window.rudderanalytics||[];e.methods=["load","page","track","identify","alias","group","ready","reset","getAnonymousId","setAnonymousId","getUserId","getUserTraits","getGroupId","getGroupTraits","startSession","endSession"],e.factory=function(t){return function(){e.push([t].concat(Array.prototype.slice.call(arguments)))}};for(var t=0;t -------------------------------------------------------------------------------- /static/img/linkedin-icon-light.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/license.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 5 3 | --- 4 | 5 | # Licensing 6 | 7 | Our licensing philosophy is quite simple. We provide an open source license, enabling users to create and use their own codemods for internal needs, or even share them publicly if they wish. This approach also enables us to *work in public*. However, we aim to prevent competitors, adjacent players, or cloud providers from leveraging our continued investment for their own commercial gain without benefiting all users. 8 | 9 | ## Codemodder Frameworks 10 | All of our codemodder frameworks, the libraries for each language that are used by people to build codemods, are available as Affero GPL (AGPL). 11 | 12 | ## Core Codemods 13 | All of our codemodder frameworks also retain a set of core codemods which are of common interest for the broad community. These are available as Affero GPL (AGPL). 14 | 15 | ## Documentation 16 | Our documentation is available as MIT. 17 | -------------------------------------------------------------------------------- /sidebars.js: -------------------------------------------------------------------------------- 1 | /** 2 | * Creating a sidebar enables you to: 3 | - create an ordered group of docs 4 | - render a sidebar for each doc of that group 5 | - provide next/previous navigation 6 | 7 | The sidebars can be generated from the filesystem, or explicitly defined here. 8 | 9 | Create as many sidebars as you want. 10 | */ 11 | 12 | // @ts-check 13 | 14 | /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ 15 | const sidebars = { 16 | // By default, Docusaurus generates a sidebar from the docs folder structure 17 | tutorialSidebar: [{type: 'autogenerated', dirName: '.'}], 18 | 19 | // But you can create a sidebar manually 20 | 21 | /*tutorialSidebar: [ 22 | 'intro', 23 | 'getting-started', 24 | { 25 | type: 'category', 26 | label: 'Tutorial', 27 | items: ['tutorial-basics/create-a-document'], 28 | }, 29 | ],*/ 30 | 31 | }; 32 | 33 | module.exports = sidebars; 34 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "codemodder-doc-site", 3 | "version": "1.0.0", 4 | "private": true, 5 | "scripts": { 6 | "docusaurus": "docusaurus", 7 | "start": "docusaurus start", 8 | "build": "docusaurus build", 9 | "swizzle": "docusaurus swizzle", 10 | "deploy": "docusaurus deploy", 11 | "clear": "docusaurus clear", 12 | "serve": "docusaurus serve", 13 | "write-translations": "docusaurus write-translations", 14 | "write-heading-ids": "docusaurus write-heading-ids" 15 | }, 16 | "dependencies": { 17 | "@docusaurus/core": "^3.1.1", 18 | "@docusaurus/preset-classic": "^3.1.1", 19 | "@mdx-js/react": "^3.0.0", 20 | "clsx": "^1.2.1", 21 | "prism-react-renderer": "^2.3.1", 22 | "react": "^18.2.0", 23 | "react-dom": "^18.2.0" 24 | }, 25 | "devDependencies": { 26 | "@docusaurus/module-type-aliases": "^3.1.1", 27 | "@docusaurus/types": "^3.1.1" 28 | }, 29 | "browserslist": { 30 | "production": [ 31 | ">0.5%", 32 | "not dead", 33 | "not op_mini all" 34 | ], 35 | "development": [ 36 | "last 1 chrome version", 37 | "last 1 firefox version", 38 | "last 1 safari version" 39 | ] 40 | }, 41 | "engines": { 42 | "node": ">=18.00" 43 | } 44 | } 45 | -------------------------------------------------------------------------------- /.github/workflows/deploy.yml: -------------------------------------------------------------------------------- 1 | name: Deploy to GitHub Pages 2 | 3 | on: 4 | pull_request: 5 | branches: [main] 6 | push: 7 | branches: [main] 8 | 9 | jobs: 10 | test-deploy: 11 | if: github.event_name != 'push' 12 | runs-on: ubuntu-latest 13 | steps: 14 | - uses: actions/checkout@v2 15 | - uses: actions/setup-node@v3 16 | with: 17 | node-version: 18 18 | cache: yarn 19 | - name: Install dependencies 20 | run: yarn install --frozen-lockfile 21 | - name: Test build website 22 | run: yarn build 23 | deploy: 24 | if: github.event_name != 'pull_request' 25 | runs-on: ubuntu-latest 26 | steps: 27 | - uses: actions/checkout@v2 28 | - uses: actions/setup-node@v3 29 | with: 30 | node-version: 18 31 | cache: yarn 32 | - uses: webfactory/ssh-agent@v0.5.0 33 | with: 34 | ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }} 35 | - name: Deploy to GitHub Pages 36 | env: 37 | USE_SSH: true 38 | run: | 39 | git config --global user.email "actions@github.com" 40 | git config --global user.name "gh-actions" 41 | yarn install --frozen-lockfile 42 | yarn deploy 43 | -------------------------------------------------------------------------------- /docs/provided.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 5 3 | title: Fix-Only Codemods 4 | --- 5 | 6 | You may see the term "Fix-Only Codemod" in our documentation and in our code. This page discusses what differentiates "fix-only" codemods from typical codemods. 7 | 8 | ## It's about how we find the code 9 | 10 | Fix-only codemods are a special type of codemod that use code location data that is produced by external tool. We currently support the following external tools: 11 | 12 | * Sonar 13 | * CodeQL 14 | * Semgrep 15 | 16 | If you want to make a codemod for fixing something these tools find, please look at the documentation for the codemodder project for your language. 17 | 18 | ### Sonar 19 | 20 | To fix issues found by Sonar, take JSON returned by the Issues API, save it to a file, and pass that file to the `--sonar-issues` CLI argument. 21 | 22 | ### SARIF producing tools 23 | 24 | To fix issues generated by CodeQL and Semgrep, pass their SARIF file output to a codemod's `--sarif` CLI argument. 25 | 26 | ## Let's support more! 27 | 28 | Note that these are the "built-in" providers we support and for which we offer easy-to-implement supertypes. We'd be interested in fixing the stuff your favorite tool finds -- just open an issue on the codemodder framework GitHub page ([Java](https://github.com/pixee/codemodder-java/issues), [Python](https://github.com/pixee/codemodder-python/issues)). -------------------------------------------------------------------------------- /static/img/slack-icon-dark.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /static/img/slack-icon-light.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /static/img/twitter-icon-dark.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /static/img/twitter-icon-light.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/faqs.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 4 3 | --- 4 | 5 | # FAQs 6 | 7 | ### Can you help me make a codemod? 8 | 9 | Yes! We're passionate about this and would love to help. Join the Pixee community [on Slack!](https://join.slack.com/t/openpixee/shared_invite/zt-1pnk7jqdd-kfwilrfG7Ov4M8rorfOnUA) 10 | 11 | ### How does codemodder compare to jscodeshift/JavaParser/Semgrep/libcst? 12 | 13 | codemodder is a collection of language-specific frameworks for building codemods. Other tools are really good at searching code for patterns (like Semgrep or PMD), or mutating code (like jscodeshift or JavaParser.) The purpose of codemodder is to make it very easy orchestrate these tools together to quickly build powerful codemods. Many tools could be used in orchestration of a codemodder codemod. 14 | 15 | ### How does codemodder compare to OpenRewrite? 16 | 17 | At a high level, we are both codemod development tools (except they call them "recipes"). There are multiple differences in the technical approach between [OpenRewrite](https://github.com/openrewrite/) and codemodder. While we appreciate their work on building a complete stack for codemod development, we're focused on orchestration of idiomatic community tools and integration with other tools. 18 | 19 | ### How does codemodder relate to Pixeebot? 20 | 21 | The team behind [Pixeebot](https://pixee.ai/) delivers code improvements using codemodder-based codemods and sponsors the development of codemodder. 22 | 23 | ### How can I make codemods for language X|Y|Z? 24 | 25 | All of the specifications for creating a codemodder framework for your language are [available here](https://github.com/pixee/codemodder-specs). This is a heavy lift, but we'd love to support you. 26 | -------------------------------------------------------------------------------- /static/img/github-icon-dark.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /static/img/github-icon-light.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/languages/java/testing.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 5 3 | title: Testing Your Codemod 4 | --- 5 | 6 | ## Testing 7 | 8 | If you want to write tests for your codemod (highly recommended, you're changing peoples' code!), let's show how. 9 | 10 | First, we add the test dependency. 11 | 12 | ``` 13 | // could instead use any of the codeql, sonar, or pmd plugins 14 | implementation("io.codemodder:codemodder-testutils:$VERSION") 15 | ``` 16 | 17 | This type adds a [mixin](https://en.wikipedia.org/wiki/Mixin) called [`CodemodTestMixin`](https://www.javadoc.io/doc/io.codemodder/codemodder-testutils/latest/io/codemodder/testutils/CodemodTestMixin.html). 18 | 19 | This mixin reads annotation data from a JUnit test class and performs all the logic for validating the codemod based on convention. It provides the two basic following features: 20 | 21 | * verification of expected code changes 22 | * verification of dependencies injected (if any) 23 | 24 | Here's the test for our `ReadLinesCodemod`: 25 | 26 | ```java 27 | @Metadata( 28 | codemodType = ReadLinesCodemod.class, 29 | testResourceDir = "readlines", 30 | dependencies = {}) 31 | final class ReadLinesCodemodTest implements CodemodTestMixin {} 32 | ``` 33 | 34 | That's it! 35 | 36 | This mixin expects a directory called `readlines` in the test classpath (e.g., `src/test/resources/readlines`). This directory can have multiple file pairs that follow a name pattern like `ArbitraryTestName.java.before` and `ArbitraryTestName.java.after`. For each of these pairs, the codemod will be run on the `.before` file, and the output should match the `.after` file. These files end up being your test cases, and should be thorough. 37 | 38 | You can also specify if you expect a codemod to be injected as a dependency into the project manifest when a change is made. 39 | 40 | 41 | -------------------------------------------------------------------------------- /src/components/HomepageFeatures/index.js: -------------------------------------------------------------------------------- 1 | import React from 'react'; 2 | import clsx from 'clsx'; 3 | import styles from './styles.module.css'; 4 | 5 | const FeatureList = [ 6 | { 7 | title: 'Easy to Use', 8 | Svg: require('@site/static/img/undraw_docusaurus_mountain.svg').default, 9 | description: ( 10 | <> 11 | Docusaurus was designed from the ground up to be easily installed and 12 | used to get your website up and running quickly. 13 | 14 | ), 15 | }, 16 | { 17 | title: 'Focus on What Matters', 18 | Svg: require('@site/static/img/undraw_docusaurus_tree.svg').default, 19 | description: ( 20 | <> 21 | Docusaurus lets you focus on your docs, and we'll do the chores. Go 22 | ahead and move your docs into the docs directory. 23 | 24 | ), 25 | }, 26 | { 27 | title: 'Powered by React', 28 | Svg: require('@site/static/img/undraw_docusaurus_react.svg').default, 29 | description: ( 30 | <> 31 | Extend or customize your website layout by reusing React. Docusaurus can 32 | be extended while reusing the same header and footer. 33 | 34 | ), 35 | }, 36 | ]; 37 | 38 | function Feature({Svg, title, description}) { 39 | return ( 40 |
41 |
42 | 43 |
44 |
45 |

{title}

46 |

{description}

47 |
48 |
49 | ); 50 | } 51 | 52 | export default function HomepageFeatures() { 53 | return ( 54 |
55 |
56 |
57 | {FeatureList.map((props, idx) => ( 58 | 59 | ))} 60 |
61 |
62 |
63 | ); 64 | } 65 | -------------------------------------------------------------------------------- /docs/languages/java/project_setup.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 2 3 | title: Project Setup 4 | --- 5 | import Tabs from '@theme/Tabs'; 6 | import TabItem from '@theme/TabItem'; 7 | 8 | This page walks through adding the right dependencies on your project. Create an empty project in either Maven or Gradle, then add our base dependency: 9 | 10 | 11 | 12 | 13 | ```kotlin 14 | implementation("io.codemodder:codemodder-base:$VERSION") 15 | ``` 16 | 17 | 18 | 19 | 20 | ```xml 21 | 22 | io.codemodder 23 | codemodder-base 24 | $VERSION 25 | 26 | ``` 27 | 28 | 29 | 30 | 31 | ## Decide how to find the code we want to change 32 | 33 | Codemodder is designed to leverage common third-party tools to identify issues to fix. So, our next step is to choose which static analysis tool (if any) we'll use to _find_ the problem we want to fix. Some simple changes may not require anything more than the basic AST traversal features provided by JavaParser (which is in the base dependency). Other more complicated changes will require the use of third-party static analysis tools. 34 | 35 | A good option for many use cases is to use [Semgrep](https://semgrep.dev) to find the code we want to change. This tool is excellent at finding different shapes of code, with tools for suppressing common false positives cases. Let's add the Semgrep plugin to our build so we can act on Semgrep findings. 36 | 37 | 38 | 39 | 40 | ```kotlin 41 | implementation("io.codemodder:codemodder-plugin-semgrep:$VERSION") 42 | ``` 43 | 44 | 45 | 46 | 47 | ```xml 48 | 49 | io.codemodder 50 | codemodder-plugin-semgrep 51 | $VERSION 52 | 53 | ``` 54 | 55 | 56 | 57 | 58 | In order to test and run, you will have to install Semgrep as well: 59 | 60 | ```bash 61 | $ pip install semgrep 62 | ``` 63 | 64 | With our setup done, our next step is to write the codemod! -------------------------------------------------------------------------------- /docs/languages/java/building_codemod.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 4 3 | title: Building & Running Your Codemod 4 | --- 5 | import Tabs from '@theme/Tabs'; 6 | import TabItem from '@theme/TabItem'; 7 | 8 | There are 2 steps for turning our codemod type into a runnable codemod artifact: 9 | 10 | * Creating the CLI entry point code 11 | * Configuring our build tool to add that entry point to the manifest 12 | 13 | ## Create the CLI Entry Point 14 | 15 | Codemodder is a library for building codemods. We need to write a small piece of code to enable our codemods to be invoked using a CLI entry point. Let's create a new type, `App.java`: 16 | 17 | ```java 18 | package io.codemodder.sample; 19 | 20 | import io.codemodder.Runner; 21 | 22 | public final class App { 23 | public static void main(String[] args) { 24 | Runner.run( 25 | List.of(ReadLinesCodemod.class), // the codemods to run 26 | args // the arguments 27 | ); 28 | } 29 | } 30 | ``` 31 | 32 | The [`Runner`](https://www.javadoc.io/doc/io.codemodder/codemodder-base/latest/io/codemodder/Runner.html) type will handle supporting all the supported [command line arguments](https://github.com/pixee/codemodder-specs/blob/main/cli.md), so you don't have to worry about any of that -- just point your `Main-Class` in your packaged `MANIFEST.MF` to `MyCodeRunner`, usually done with some code like this: 33 | 34 | 35 | 36 | 37 | ```kotlin 38 | description = "" 39 | val main = "io.codemodder.sample.App" 40 | application { 41 | mainClass.set(main) 42 | } 43 | ``` 44 | 45 | 46 | 47 | 48 | ```xml 49 | 50 | 51 | org.apache.maven.plugins 52 | maven-jar-plugin 53 | 54 | 55 | 56 | io.codemodder.sample.App 57 | 58 | 59 | 60 | 61 | 62 | ``` 63 | 64 | 65 | 66 | 67 | 68 | ## Running 69 | 70 | It doesn't really matter if you created a Gradle distribution zip, or a fatjar with Maven -- your project has _some_ packaged up artifact. We can now invoke it with the standard CLI parameters and watch it work! 71 | 72 | ```bash 73 | $ cd build/distributions/ 74 | $ unzip app.zip 75 | $ app/bin/app /my-project-that-needs-updating 76 | ``` 77 | -------------------------------------------------------------------------------- /docusaurus.config.js: -------------------------------------------------------------------------------- 1 | // @ts-check 2 | // Note: type annotations allow type checking and IDEs autocompletion 3 | 4 | const lightCodeTheme = require("prism-react-renderer").themes.github; 5 | const darkCodeTheme = require("prism-react-renderer").themes.dracula; 6 | 7 | /** @type {import('@docusaurus/types').Config} */ 8 | const config = { 9 | title: 'Codemodder', 10 | tagline: 'The best codemods', 11 | url: 'https://codemodder.io', 12 | baseUrl: '/', 13 | onBrokenLinks: 'throw', 14 | onBrokenMarkdownLinks: 'warn', 15 | favicon: 'img/favicon.ico', 16 | 17 | // GitHub pages deployment config. 18 | // If you aren't using GitHub pages, you don't need these. 19 | organizationName: 'pixee', // Usually your GitHub org/user name. 20 | projectName: 'internal-codemodder-docs', // Usually your repo name. 21 | deploymentBranch: 'main', 22 | 23 | // Even if you don't use internalization, you can use this field to set useful 24 | // metadata like html lang. For example, if your site is Chinese, you may want 25 | // to replace "en" with "zh-Hans". 26 | i18n: { 27 | defaultLocale: 'en', 28 | locales: ['en'], 29 | }, 30 | 31 | stylesheets: [ 32 | 'https://fonts.googleapis.com/css?family=Source+Sans+Pro:200,200i,300,300i,400,400i,600,600i,700,700i,900,900i&display=swap', 33 | ], 34 | 35 | presets: [ 36 | [ 37 | '@docusaurus/preset-classic', 38 | /** @type {import('@docusaurus/preset-classic').Options} */ 39 | ({ 40 | docs: { 41 | sidebarPath: require.resolve('./sidebars.js'), 42 | routeBasePath: '/', 43 | // Please change this to your repo. 44 | // Remove this to remove the "edit this page" links. 45 | editUrl: 'https://github.com/pixee/codemodder-docs/edit/main/', 46 | }, 47 | blog: { 48 | showReadingTime: true, 49 | // Please change this to your repo. 50 | // Remove this to remove the "edit this page" links. 51 | editUrl: 'https://github.com/pixee/codemodder-docs/edit/main/', 52 | }, 53 | theme: { 54 | customCss: require.resolve('./src/css/custom.css'), 55 | }, 56 | gtag: { 57 | trackingID: 'G-PP500P3417', 58 | anonymizeIP: true, 59 | }, 60 | }), 61 | ], 62 | ], 63 | 64 | themeConfig: 65 | /** @type {import('@docusaurus/preset-classic').ThemeConfig} */ 66 | ({ 67 | navbar: { 68 | logo: { 69 | alt: 'Codemodder', 70 | src: 'img/CodemodderLM.png', 71 | srcDark: 'img/CodemodderDM.png', 72 | }, 73 | 74 | items: [ 75 | { 76 | type: 'doc', 77 | docId: 'intro', 78 | position: 'left', 79 | label: 'Home', 80 | }, 81 | { 82 | type: 'html', 83 | position: 'right', 84 | value: 85 | '
', 86 | }, 87 | { 88 | type: 'html', 89 | position: 'right', 90 | value: 91 | '
', 92 | }, 93 | ], 94 | }, 95 | head: [], 96 | footer: { 97 | links: [ 98 | { 99 | items: [ 100 | { 101 | html: ` 102 |
103 |
© 2023 Pixee Inc. All rights reserved
104 | 108 | 109 |
110 | Terms of Service 111 | Privacy Policy 112 | Contact us 113 |
114 |
115 | `, 116 | }, 117 | ], 118 | }, 119 | ], 120 | }, 121 | prism: { 122 | additionalLanguages: ['java', 'python'], 123 | theme: lightCodeTheme, 124 | darkTheme: darkCodeTheme, 125 | }, 126 | }), 127 | 128 | scripts: [ 129 | { 130 | src: '/js/loadtags.js', 131 | async: true, 132 | }, 133 | { 134 | src: '/js/handle_double_slash.js', 135 | async: true, 136 | }, 137 | ], 138 | }; 139 | 140 | module.exports = config; 141 | -------------------------------------------------------------------------------- /docs/intro.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 1 3 | slug: / 4 | --- 5 | 6 | import Tabs from '@theme/Tabs'; 7 | import TabItem from '@theme/TabItem'; 8 | 9 | # Introduction 10 | 11 | Codemodder is a pluggable framework for building expressive codemods. Previous codemod libraries allow for building cool stuff, but they were all missing key features that would allow more expressive and impactful code changes. 12 | 13 | Codemodder offers: 14 | * **Maximum expressiveness**. We allow you to use your favorite fancy static analysis tools to identify the code you want to change. 15 | * **Storytelling as a first class feature**. Automating code changes isn't very helpful without the necessary communication to the other developers on your team. 16 | * **The quietest changes possible**. There's some distance between "making a change" and "making a change that is easy to approve" and our framework guides you towards the latter. 17 | 18 | Codemodder is a good framework to choose if your problem is one level more complex than linters can detect and fix, or require more or better storytelling because the issues they tackle are not straightforward (for instance, like advanced security issues.) Most of the feedback experienced developers give to junior developers fits into this bucket, but we offer many open source "core codemods" that solve the easy stuff too. 19 | 20 | # An example 21 | 22 | The easiest codemod we can imagine writing is to replace all insecure (predictable) sources of randomness with secure (unpredictable) sources. Here we show what that codemod might look like across languages: 23 | 24 | 25 | 26 | 27 | ```java 28 | /** Turns {@link java.util.Random} into {@link java.security.SecureRandom}. */ 29 | @Codemod( 30 | id = "pixee:java/secure-random", 31 | reviewGuidance = ReviewGuidance.MERGE_WITHOUT_REVIEW) 32 | public final class SecureRandomCodemod extends SarifPluginJavaParserChanger { 33 | 34 | private static final String DETECTION_RULE = 35 | """ 36 | rules: 37 | - id: secure-random 38 | pattern: new Random() 39 | """; 40 | 41 | @Inject 42 | public SecureRandomCodemod(@SemgrepScan(yaml = DETECTION_RULE) RuleSarif sarif) { 43 | super(sarif, ObjectCreationExpr.class); 44 | } 45 | 46 | @Override 47 | public boolean onResultFound( 48 | final CodemodInvocationContext context, 49 | final CompilationUnit cu, 50 | final ObjectCreationExpr objectCreationExpr, 51 | final Result result) { 52 | objectCreationExpr.setType("SecureRandom"); 53 | addImportIfMissing(cu, SecureRandom.class.getName()); 54 | return true; 55 | } 56 | } 57 | ``` 58 | 59 | You can see this code [live on GitHub](https://github.com/pixee/codemodder-java/blob/main/core-codemods/src/main/java/io/codemodder/codemods/SecureRandomCodemod.java). 60 | 61 | This codemod, which would be easy to implement even without the need for a fancy static analysis tool, uses [Semgrep](https://semgrep.dev/) to find all the constructor calls for `java.util.Random`. These are the locations we want to change to `SecureRandom` instead. 62 | 63 | The codemodder framework then hands off all those locations Semgrep found to the `onResultfound()` method, where the code just has to change the type and add the missing import. It takes care of a lot of annoying work -- the execution of static analysis tools, the parsing of its results, aligning the results to the code that handles them, the formatting of the resulting code, etc. All you specify is how to find the code to change and what change do you want to make. We handle the rest. 64 | 65 | For more real-world examples, check out our [core Java codemods](https://github.com/pixee/codemodder-java/tree/main/core-codemods), which are codemods maintained by the framework and made for general use. We also provide utilities for building and testing these codemods to make the whole process seamless. 66 | 67 | 68 | 69 | 70 | ```python 71 | class SecureRandom(SimpleCodemod): 72 | metadata = Metadata( 73 | name="secure-random", 74 | review_guidance=ReviewGuidance.MERGE_AFTER_CURSORY_REVIEW, 75 | summary="Secure Source of Randomness", 76 | ) 77 | 78 | detector_pattern = """ 79 | - patterns: 80 | - pattern: random.$F(...) 81 | - pattern-inside: | 82 | import random 83 | ... 84 | """ 85 | 86 | def on_result_found(self, original_node, updated_node): 87 | self.remove_unused_import(original_node) 88 | self.add_needed_import("secrets") 89 | return self.update_call_target(updated_node, "secrets.SystemRandom()") 90 | ``` 91 | 92 | You can see this code [live on GitHub](https://github.com/pixee/codemodder-python/blob/main/src/core_codemods/secure_random.py). 93 | 94 | This codemod uses [Semgrep](https://semgrep.dev/) to detect cases where unsafe random methods are used. The codemod itself is implemented using the [libCST framework](https://github.com/Instagram/LibCST#readme). 95 | 96 | For more real-world examples, check out our [core Python codemods](https://github.com/pixee/codemodder-python/tree/main/src/core_codemods), which are codemods maintained by the framework and made for general use. We also provide utilities for building and testing codemods to make the whole process seamless. See the [Python codemodder repo](https://github.com/pixee/codemodder-python/) for more details. 97 | 98 | ⚠️ The Python codemodder API is still under heavy development and is subject to breaking changes. ⚠️ 99 | 100 | 101 | 102 | 103 | ``` 104 | Coming soon! 105 | ``` 106 | 107 | 108 | 109 | 110 | 111 | 112 | ### What languages does Codemodder support? 113 | * Java 114 | * Python 115 | * JavaScript (coming soon) 116 | 117 | -------------------------------------------------------------------------------- /static/img/logo.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /src/css/custom.css: -------------------------------------------------------------------------------- 1 | /** 2 | * Any CSS included here will be global. The classic template 3 | * bundles Infima by default. Infima is a CSS framework designed to 4 | * work well for content-centric websites. 5 | */ 6 | 7 | /* You can override the default Infima variables here. */ 8 | /* Import the custom fonts */ 9 | @font-face { 10 | font-family: 'CustomFont'; 11 | src: url('./../../static/fonts/Poppins-Bold.woff2') format('woff2'), 12 | url('./../../static/fonts/Poppins-Bold.woff') format('woff'); 13 | font-weight: normal; 14 | font-style: normal; 15 | } 16 | 17 | @font-face { 18 | font-family: 'Poppins-thin'; 19 | src: url('./../../static/fonts/Poppins-Light.woff2') format('woff2'), 20 | url('./../../static/fonts/Poppins-Light.woff') format('woff'); 21 | font-weight: normal; 22 | font-style: normal; 23 | } 24 | 25 | @font-face { 26 | font-family: 'Poppins-regular'; 27 | src: url('./../../static/fonts/Poppins-Regular.woff2') format('woff2'), 28 | url('./../../static/fonts/Poppins-Light.woff') format('woff'); 29 | font-weight: normal; 30 | font-style: normal; 31 | } 32 | 33 | body { 34 | font-family: 'Source Sans Pro'; 35 | color: var(--ifm-color-text); 36 | } 37 | 38 | [data-theme='dark'] body { 39 | color: var(--ifm-color-text); 40 | } 41 | 42 | /* Menu styles */ 43 | .menu, 44 | .navbar__link { 45 | font-weight: 600; 46 | } 47 | 48 | .navbar__title { 49 | font-family: 'Poppins-regular', sans-serif; 50 | font-size: 20px; 51 | } 52 | 53 | .menu, 54 | .navbar__item { 55 | padding-right: 5px; 56 | padding-left: 5px; 57 | } 58 | 59 | /* Nav-bar styles*/ 60 | 61 | .navbar, 62 | .navbar__fixed-top { 63 | padding-left: 24px; 64 | padding-right: 24px; 65 | } 66 | 67 | .header-routes { 68 | color: #1c1533; 69 | font-size: 16px; 70 | font-weight: 400; 71 | } 72 | 73 | .custom-navbar-logo-class { 74 | content: ''; 75 | width: 24px; 76 | height: 24px; 77 | display: flex; 78 | background: url('./../../static/img/pixee-logo.png') no-repeat; 79 | background-size: cover; 80 | } 81 | 82 | [data-theme='dark'] .header-routes { 83 | color: #fbfafb; 84 | } 85 | 86 | [data-theme='dark'] .navbar__link:hover, 87 | [data-theme='dark'] .navbar__link--active { 88 | color: var(--ifm-navbar-link-hover-color); 89 | text-decoration: none; 90 | font-weight: 700; 91 | } 92 | 93 | .navbar__link:hover, 94 | .navbar__link--active { 95 | color: var(--ifm-navbar-link-hover-color); 96 | text-decoration: none; 97 | font-weight: 700; 98 | } 99 | 100 | .header-github-link::before { 101 | content: ''; 102 | width: 24px; 103 | height: 24px; 104 | display: flex; 105 | background: url('./../../static/img/github-icon-light.svg') no-repeat; 106 | background-size: cover; 107 | } 108 | 109 | .header-slack-link::before { 110 | content: ''; 111 | width: 24px; 112 | height: 24px; 113 | display: flex; 114 | background: url('./../../static/img/slack-icon-light.svg') no-repeat; 115 | background-size: cover; 116 | } 117 | 118 | [data-theme='dark'] .header-github-link::before { 119 | background: url('./../../static/img/github-icon-dark.svg') no-repeat; 120 | background-size: cover; 121 | } 122 | 123 | [data-theme='dark'] .header-slack-link::before { 124 | background: url('./../../static/img/slack-icon-dark.svg') no-repeat; 125 | background-size: cover; 126 | } 127 | 128 | /* Footer styles */ 129 | .footer { 130 | background-color: #fff; 131 | padding-bottom: 24px; 132 | padding: 10px 80px 10px 80px; 133 | font-size: 14px; 134 | font-family: 'Source Sans Pro'; 135 | font-weight: 400; 136 | color: #656074; 137 | } 138 | 139 | .footer a { 140 | color: #656074; 141 | } 142 | 143 | .footer a:hover { 144 | color: var(--ifm-color-primary); 145 | text-decoration: none; 146 | } 147 | 148 | .footer .container { 149 | max-width: none; 150 | } 151 | 152 | .footer .footerContent { 153 | display: flex; 154 | justify-content: space-between; 155 | flex-direction: row; 156 | } 157 | 158 | .footer .links { 159 | display: flex; 160 | flex-direction: row; 161 | gap: 32px; 162 | color: #656074; 163 | } 164 | 165 | .footer .socialIcons { 166 | display: flex; 167 | flex-direction: row; 168 | gap: 8px; 169 | } 170 | 171 | .footer .copyright span { 172 | font-weight: 700; 173 | } 174 | 175 | .footer-twitter-link::before { 176 | content: ''; 177 | width: 16px; 178 | height: 16px; 179 | display: flex; 180 | background: url('./../../static/img/twitter-icon-light.svg') no-repeat; 181 | background-size: cover; 182 | } 183 | 184 | [data-theme='dark'] .footer-twitter-link::before { 185 | background: url('./../../static/img/twitter-icon-dark.svg') no-repeat; 186 | background-size: cover; 187 | } 188 | 189 | .footer-linkedin-link::before { 190 | content: ''; 191 | width: 16px; 192 | height: 16px; 193 | display: flex; 194 | background: url('./../../static/img/linkedin-icon-light.svg') no-repeat; 195 | background-size: cover; 196 | } 197 | 198 | [data-theme='dark'] .footer-linkedin-link::before { 199 | background: url('./../../static/img/linkedin-icon-dark.svg') no-repeat; 200 | background-size: cover; 201 | } 202 | 203 | /* Mobile view styles*/ 204 | @media (max-width: 800px) { 205 | .footer { 206 | padding: 0; 207 | } 208 | .footer .col { 209 | margin-bottom: 10px; 210 | } 211 | .footer .footerContent { 212 | flex-direction: column; 213 | text-align: center; 214 | } 215 | .footer .socialIcons { 216 | justify-content: center; 217 | } 218 | .footer .links { 219 | flex-direction: column; 220 | gap: 0; 221 | } 222 | } 223 | 224 | :root { 225 | --ifm-color-primary: #6000fe; 226 | --ifm-color-primary-dark: #5600e5; 227 | --ifm-color-primary-darker: #5200d8; 228 | --ifm-color-primary-darkest: #4300b2; 229 | --ifm-color-primary-light: #7018ff; 230 | --ifm-color-primary-lighter: #7725ff; 231 | --ifm-color-primary-lightest: #8f4bff; 232 | --ifm-heading-color: var(--ifm-color-text); 233 | --ifm-link-color: var(--ifm-color-primary); 234 | --ifr-color-neutral-10: #fbfafb; 235 | --ifm-color-text: #1c1e21; 236 | --ifr-color-neutral-10: #fbfafb; 237 | --ifr-color-neutral-20: #e6e4ea; 238 | --ifr-color-neutral-70: #3d3751; 239 | --ifr-color-neutral-80: #2c2541; 240 | --ifr-color-neutral-90: #1c1533; 241 | --ifr-color-neutral-white: #fff; 242 | --ifm-heading-font-family: 'CustomFont', sans-serif; 243 | } 244 | 245 | /* Dark mode styles */ 246 | [data-theme='dark'] { 247 | --ifm-color-primary: #ba95f9; 248 | --ifm-color-primary-dark: #a16ff7; 249 | --ifm-color-primary-darker: #955cf6; 250 | --ifm-color-primary-darkest: #7024f3; 251 | --ifm-color-primary-light: #d3bbfb; 252 | --ifm-color-primary-lighter: #dfcefc; 253 | --ifm-color-primary-lightest: #ffffff; 254 | --ifm-color-text: #e3e3e3; 255 | } 256 | 257 | [data-theme='dark'] .navbar { 258 | background-color: #242526; 259 | } 260 | 261 | [data-theme='dark'] .footer { 262 | background-color: #1b1b1d; 263 | color: #aeabb6; 264 | } 265 | 266 | [data-theme='dark'] .footer .links, 267 | [data-theme='dark'] .footer .links a { 268 | color: #aeabb6; 269 | } 270 | 271 | [data-theme='dark'] .footer a:hover { 272 | color: var(--ifm-color-primary); 273 | text-decoration: none; 274 | } 275 | 276 | /* left side bar */ 277 | 278 | /* light mode default */ 279 | .theme-doc-sidebar-item-category li .menu__link, 280 | .theme-doc-sidebar-menu li .menu__link { 281 | border-left: 4px solid transparent; 282 | color: var(--ifr-color-neutral-90); 283 | font-weight: 400; 284 | } 285 | 286 | /* light mode default hover */ 287 | .theme-doc-sidebar-item-category li .menu__link:hover, 288 | .theme-doc-sidebar-menu li .menu__link:hover { 289 | border-left: 4px solid #ebedf0; 290 | color: var(--ifm-color-primary); 291 | font-weight: 400; 292 | } 293 | 294 | /* light mode active */ 295 | .theme-doc-sidebar-item-category li .menu__link.menu__link--active, 296 | .theme-doc-sidebar-menu li .menu__link.menu__link--active { 297 | border-left: 4px solid var(--ifm-color-primary); 298 | color: var(--ifm-color-primary); 299 | font-weight: 700; 300 | } 301 | 302 | /* light mode active hover */ 303 | .theme-doc-sidebar-item-category li .menu__link.menu__link--active:hover, 304 | .theme-doc-sidebar-menu li .menu__link.menu__link--active:hover { 305 | border-left: 4px solid var(--ifm-color-primary); 306 | color: var(--ifm-color-primary); 307 | font-weight: 700; 308 | } 309 | 310 | /* dark mode default */ 311 | [data-theme='dark'] .theme-doc-sidebar-item-category li .menu__link, 312 | [data-theme='dark'] .theme-doc-sidebar-menu li .menu__link { 313 | border-left: 4px solid transparent; 314 | color: var(--ifr-color-neutral-10); 315 | font-weight: 400; 316 | } 317 | 318 | /* dark mode default hover */ 319 | [data-theme='dark'] .theme-doc-sidebar-item-category li .menu__link:hover, 320 | [data-theme='dark'] .theme-doc-sidebar-menu li .menu__link:hover { 321 | border-left: 4px solid #2c2541; 322 | color: var(--ifm-color-primary); 323 | font-weight: 400; 324 | } 325 | 326 | /* dark mode active */ 327 | [data-theme='dark'] 328 | .theme-doc-sidebar-item-category 329 | li 330 | .menu__link.menu__link--active, 331 | [data-theme='dark'] .theme-doc-sidebar-menu li .menu__link.menu__link--active { 332 | border-left: 4px solid var(--ifm-color-primary); 333 | color: var(--ifm-color-primary); 334 | font-weight: 700; 335 | } 336 | 337 | /* dark mode active hover */ 338 | [data-theme='dark'] 339 | .theme-doc-sidebar-item-category 340 | li 341 | .menu__link.menu__link--active:hover, 342 | [data-theme='dark'] 343 | .theme-doc-sidebar-menu 344 | li 345 | .menu__link.menu__link--active:hover { 346 | color: var(--ifm-color-primary); 347 | font-weight: 700; 348 | } 349 | 350 | [data-theme='dark'] .theme-doc-sidebar-item-category li .menu__link, 351 | [data-theme='dark'] .theme-doc-sidebar-menu li .menu__link { 352 | color: var(--ifr-color-neutral-10); 353 | } 354 | [data-theme='dark'] 355 | .theme-doc-sidebar-item-category 356 | li 357 | [data-theme='dark'] 358 | .menu__link.menu__link--active, 359 | .theme-doc-sidebar-menu li .menu__link.menu__link--active { 360 | color: var(--ifm-color-primary); 361 | } 362 | 363 | .menu__link--active:not(.menu__link--sublist) { 364 | border-left: 4px solid var(--ifm-color-primary); 365 | background-color: #f2f2f2; 366 | } 367 | 368 | [data-theme='dark'] .menu__link--active:not(.menu__link--sublist) { 369 | border-left: 4px solid var(--ifm-color-primary); 370 | background: #242526; 371 | } 372 | -------------------------------------------------------------------------------- /static/img/undraw_docusaurus_tree.svg: -------------------------------------------------------------------------------- 1 | 2 | Focus on What Matters 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | -------------------------------------------------------------------------------- /docs/languages/java/write_codemod.md: -------------------------------------------------------------------------------- 1 | --- 2 | sidebar_position: 3 3 | title: Writing our First Codemod 4 | --- 5 | 6 | Now, let's write our first codemod! 7 | 8 | The newer methods in `java.nio.file.Files` removed the need for some community-provided APIs in `org.apache.commons.io.FileUtils`. So, let's write a codemod to move `org.apache.commons.io.FileUtils#readLines()` to `java.nio.file.Files.readAllLines()`. The diffs should look something like this: 9 | 10 | ```diff 11 | - import org.apache.commons.io.FileUtils; // remove the import if possible 12 | + import java.nio.file.Files; 13 | 14 | ... 15 | 16 | - List lines = FilesUtils.readLines(file); 17 | + List lines = Files.readAllLines(file.toPath()); 18 | ``` 19 | 20 | ## Step #1: Write the Semgrep to find the calls we want to change 21 | 22 | The first thing we need is a Semgrep query to find all the invocations of `FileUtils#readLines()`. The [Semgrep Playground](https://semgrep.dev/playground/new) is a great place to iterate on new Semgrep queries. They have [plenty of docs](https://semgrep.dev/docs/) that we won't try to re-create here, so let's just show you the finished product: 23 | 24 | ```yaml 25 | rules: 26 | - id: migrate-files-commons-io-to-nio-read-file-to-lines 27 | pattern-either: 28 | - pattern: (org.apache.commons.io.FileUtils).readLines($X) 29 | - pattern: (org.apache.commons.io.FileUtils).readLines($X, (Charset $Y)) 30 | ``` 31 | 32 | ## Step #2: Choose a type to implement 33 | 34 | Here are some of the key types for creating a new codemod. 35 | 36 | | Type | Description | 37 | |-------------------------------------------------|-------------------------------------------------------------------------------------| 38 | | io.codemodder.CodeChanger | The base `interface` for a codemod. Should rarely be implemented directly. | 39 | | io.codemodder.javaparser.JavaParserChanger | A codemod that gets handed a fully-built JavaParser model of a source file. | 40 | | io.codemodder.javaparser.SarifJavaParserChanger | A codemod that reads SARIF results and acts on their matching JavaParser AST nodes. | 41 | 42 | So -- what is SARIF? The [Static Analysis Results Interchange Format (SARIF)](https://sarifweb.azurewebsites.net/) is a JSON format that static analysis tools use to capture their results. You don't need to know too much (anything?) about SARIF -- but we're going to use `SarifJavaParserChanger` because that's the type that takes SARIF results from Semgrep and feeds them to JavaParser. 43 | 44 | ## Step #3: Code it up 45 | 46 | We're going to step through the codemod from the top to the bottom, piece by piece, then show you the whole thing. 47 | 48 | ### The Class Definition 49 | 50 | Let's look at the class definition and meet a few new concepts 51 | 52 | ```java 53 | @Codemod( 54 | id = "pixee:java/migrate-files-commons-io-to-nio", 55 | reviewGuidance = ReviewGuidance.MERGE_WITHOUT_REVIEW) 56 | public final class ReadLinesCodemod extends SarifPluginJavaParserChanger { 57 | ... 58 | } 59 | ``` 60 | 61 | First, each codemod needs a `@Codemod` annotation. This gives some necessary metadata for end users and will eventually feed a more robust CLI experience. 62 | 63 | Second, notice the generic component of `SarifPluginJavaParserChanger`. This generic tells our framework that the Semgrep query returns the locations of Java method call expressions. If the SARIF points to a location that doesn't point to a method call, the callback won't execute. Let's see how to inject the Semgrep SARIF into the type. 64 | 65 | ### The Injection 66 | 67 | We use Guice to inject stuff into codemods, so they don't have to worry about how to create them. 68 | 69 | ```java 70 | 71 | private static final String RULE = 72 | """ 73 | rules: 74 | - id: migrate-files-commons-io-to-nio-read-file-to-lines 75 | pattern-either: 76 | - pattern: (org.apache.commons.io.FileUtils).readLines($X) 77 | - pattern: (org.apache.commons.io.FileUtils).readLines($X, (Charset $Y)) 78 | """; 79 | 80 | @Inject // tell Guice to inject stuff here 81 | public ReadLinesCodemod( 82 | @SemgrepScan(yaml = RULE) final RuleSarif sarif // asks for callbacks for hits on the given Semgrep rule 83 | ) { 84 | super( 85 | sarif, // give it the SARIF that will be used to find hits 86 | MethodCallExpr.class, // only look for method calls that match the SARIF 87 | CodemodReporterStrategy.fromClasspath(ReadLinesCodemod.class) // pull storytelling text from classpath resource 88 | ); 89 | } 90 | ``` 91 | 92 | Now, if we were use another static analysis tool like PMD, we would add the `codemodder-plugin-pmd` dependency and instead use the `@PmdScan` annotation. 93 | 94 | ### The Callback 95 | 96 | Let's see the implemented callback, starting with the declaration: 97 | 98 | ```java 99 | @Override 100 | public boolean onResultFound( 101 | CodemodInvocationContext context, // some context, like the file path, configuration, etc. 102 | CompilationUnit cu, // the JavaParser model of this source file source 103 | MethodCallExpr apacheReadLinesCall, // the method call AST node that was found by Semgrep in our query 104 | Result result // the SARIF result for this particular finding 105 | ) { 106 | ``` 107 | 108 | Here's the code change we want to make again: 109 | 110 | ```diff 111 | - List lines = FilesUtils.readLines(file); 112 | + List lines = Files.readAllLines(file.toPath()); 113 | ``` 114 | 115 | Notice we need to not only change the static method being invoked, but we also have to translate the first argument to be a `Path`. Here's the code we'll use to do that: 116 | 117 | ```java 118 | NodeList arguments = apacheReadLinesCall.getArguments(); // get the arguments for the call 119 | MethodCallExpr toPath = new MethodCallExpr(arguments.get(0), "toPath"); // call toPath() on the first arg) 120 | arguments.set(0, toPath); 121 | ``` 122 | 123 | Next we use a convenience utility we created, [`replace(Node)`](https://www.javadoc.io/doc/io.codemodder/codemodder-base/latest/io/codemodder/javaparser/JavaParserTransformer.html), to help us replace the call with the new version: 124 | ```java 125 | boolean success = 126 | replace(apacheReadLinesCall) 127 | .withStaticMethod("java.nio.file.Files", "readAllLines") 128 | .withSameArguments(); 129 | ``` 130 | 131 | If the replacing was successful, we'll remove the import if we can't find any references to it. 132 | 133 | ```java 134 | if (success) { 135 | removeImportIfUnused(cu, "org.apache.commons.io.FileUtils"); // won't remove if it's still needed 136 | } 137 | return success; // should return true if a change was made, so it can be communicated to the user 138 | ``` 139 | 140 | We're done! Here's the whole codemod: 141 | 142 | ```java 143 | @Codemod( 144 | id = "pixee:java/migrate-files-commons-io-to-nio", 145 | reviewGuidance = ReviewGuidance.MERGE_WITHOUT_REVIEW) 146 | public final class ReadLinesCodemod extends SarifPluginJavaParserChanger { 147 | 148 | private static final String RULE = 149 | """ 150 | rules: 151 | - id: migrate-files-commons-io-to-nio-read-file-to-lines 152 | pattern-either: 153 | - pattern: (org.apache.commons.io.FileUtils).readLines($X) 154 | - pattern: (org.apache.commons.io.FileUtils).readLines($X, (Charset $Y)) 155 | """; 156 | 157 | public ReadLinesCodemod(@SemgrepScan(yaml = RULE) final RuleSarif sarif) { 158 | super( 159 | sarif, // give it the SARIF that will be used to find hits 160 | MethodCallExpr.class, // only look for method calls that match the SARIF 161 | CodemodReporterStrategy.fromClasspath(ReadLinesCodemod.class) // pull storytelling text from classpath resource 162 | ); 163 | } 164 | 165 | @Override 166 | public boolean onResultFound( 167 | final CodemodInvocationContext context, 168 | final CompilationUnit cu, 169 | final MethodCallExpr apacheReadLinesCall, 170 | final Result result) { 171 | NodeList arguments = apacheReadLinesCall.getArguments(); 172 | MethodCallExpr toPath = new MethodCallExpr(arguments.get(0), "toPath"); 173 | arguments.set(0, toPath); 174 | boolean success = 175 | replace(apacheReadLinesCall) 176 | .withStaticMethod("java.nio.file.Files", "readAllLines") 177 | .withSameArguments(); 178 | 179 | if (success) { 180 | removeImportIfUnused(cu, "org.apache.commons.io.FileUtils"); 181 | } 182 | 183 | return success; 184 | } 185 | } 186 | ``` 187 | 188 | ## Step #3: Add the storytelling 189 | 190 | Well, we lied a little. We wrote all the _code_, but one of the philosophies of codemodder is that we need to tell a good story about the changes we make. Without good storytelling, people won't know the purpose or value of the changes being made. 191 | 192 | ### Provide Storytelling From the Classpath (Recommended) 193 | We provide a shortcut for folks who don't want to write and maintain big blocks of text in a Java file (like us). You can provide a [CodemodReporterStrategy](https://www.javadoc.io/doc/io.codemodder/codemodder-base/latest/io/codemodder/CodemodReporterStrategy.html) that builds reports based on text from a well-defined location on the classpath. This is an alternative to storing data inline to the Java source code of your codemod. It's easier to maintain this "data" outside of code, so we prefer a simple mechanism for doing that. Both the files read are expected to be in `/com/acme/MyCodemod/` (assuming that's the name of your codemod type). 194 | 195 | The first expected file in that directory is `{@code report.json}`. It contains most of the fields we want to report: 196 | 197 | ```json 198 | { 199 | "summary": "A headline describing the changes provided by this codemod", 200 | "change": "A description of the change suitable for a particular instance of a change", 201 | "references": [ 202 | "A URL for further reading", 203 | "Another URL for further reading" 204 | ] 205 | } 206 | ``` 207 | 208 | The second file is `description.md`, and it provides a description of the codemod's purpose and an exploration of the changes it makes. It's expected to contain more verbose text, so it is stored in a separate file where it can be easily edited with an IDE supporting markdown. 209 | 210 | Thus, in a typical Java project, using this `CodemodReporterStrategy` would mean your artifact would include at least these 3 files: 211 | 212 | - src/main/java/com/acme/MyCodemod.java 213 | - src/main/resources/com/acme/MyCodemod/report.json 214 | - src/main/resources/com/acme/MyCodemod/description.md 215 | 216 | 217 | ### Provide Storytelling In The Codemod 218 | Alternatively, if you have very simple storytelling, you can directly implement the following methods in your codemod: 219 | 220 | ```java 221 | @Override 222 | public String getSummary() { return "Fixes Acme thing..."; } 223 | 224 | @Override 225 | public String getDescription() { return "This change ..."; } 226 | 227 | @Override 228 | public List getReferences() { return List.of("https://internal.acme.com/use-x-instead-of-y"); } 229 | ``` 230 | 231 | ### Skip Storytelling 232 | If you don't care about storytelling, you can just use `CodemodReporterStrategy.empty()`. 233 | 234 | ## Back to our example 235 | 236 | For our codemod, we'll choose the classpath reporter strategy, so we're going to add those two files: 237 | 238 | Here's `src/main/resources/io/codemodder/sample/ReadLinesCodemod/report.json`: 239 | ```json 240 | { 241 | "summary": "Modernize Apache Commons IO Files API to Java NIO", 242 | "change": "Modernized Apache Commons IO Files#readLines() to use Java NIO Files#readAllLines()", 243 | "references": [ 244 | "https://docs.oracle.com/javase/8/docs/api/java/nio/file/Files.html#readAllLines-java.nio.file.Path-" 245 | ] 246 | } 247 | ``` 248 | 249 | Here's `src/main/resources/io/codemodder/sample/ReadLinesCodemod/description.md`: 250 | ``` 251 | This change modernizes an Apache Commons IO method to use Java NIO alternatives instead. 252 | 253 | We prefer to use `java.nio` libraries instead of 3rd party to reduce our dependencies. 254 | 255 | This change in particular translates Apache Commons IO `FileUtils#readLines()` to use Java NIO's `Files#readAllLines()`. 256 | ``` 257 | 258 | ## Done! 259 | 260 | Ok, now we're actually done. Now let's build and run this thing! -------------------------------------------------------------------------------- /LICENSE.md: -------------------------------------------------------------------------------- 1 | Attribution-NonCommercial-ShareAlike 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International 58 | Public License 59 | 60 | By exercising the Licensed Rights (defined below), You accept and agree 61 | to be bound by the terms and conditions of this Creative Commons 62 | Attribution-NonCommercial-ShareAlike 4.0 International Public License 63 | ("Public License"). To the extent this Public License may be 64 | interpreted as a contract, You are granted the Licensed Rights in 65 | consideration of Your acceptance of these terms and conditions, and the 66 | Licensor grants You such rights in consideration of benefits the 67 | Licensor receives from making the Licensed Material available under 68 | these terms and conditions. 69 | 70 | 71 | Section 1 -- Definitions. 72 | 73 | a. Adapted Material means material subject to Copyright and Similar 74 | Rights that is derived from or based upon the Licensed Material 75 | and in which the Licensed Material is translated, altered, 76 | arranged, transformed, or otherwise modified in a manner requiring 77 | permission under the Copyright and Similar Rights held by the 78 | Licensor. For purposes of this Public License, where the Licensed 79 | Material is a musical work, performance, or sound recording, 80 | Adapted Material is always produced where the Licensed Material is 81 | synched in timed relation with a moving image. 82 | 83 | b. Adapter's License means the license You apply to Your Copyright 84 | and Similar Rights in Your contributions to Adapted Material in 85 | accordance with the terms and conditions of this Public License. 86 | 87 | c. BY-NC-SA Compatible License means a license listed at 88 | creativecommons.org/compatiblelicenses, approved by Creative 89 | Commons as essentially the equivalent of this Public License. 90 | 91 | d. Copyright and Similar Rights means copyright and/or similar rights 92 | closely related to copyright including, without limitation, 93 | performance, broadcast, sound recording, and Sui Generis Database 94 | Rights, without regard to how the rights are labeled or 95 | categorized. For purposes of this Public License, the rights 96 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 97 | Rights. 98 | 99 | e. Effective Technological Measures means those measures that, in the 100 | absence of proper authority, may not be circumvented under laws 101 | fulfilling obligations under Article 11 of the WIPO Copyright 102 | Treaty adopted on December 20, 1996, and/or similar international 103 | agreements. 104 | 105 | f. Exceptions and Limitations means fair use, fair dealing, and/or 106 | any other exception or limitation to Copyright and Similar Rights 107 | that applies to Your use of the Licensed Material. 108 | 109 | g. License Elements means the license attributes listed in the name 110 | of a Creative Commons Public License. The License Elements of this 111 | Public License are Attribution, NonCommercial, and ShareAlike. 112 | 113 | h. Licensed Material means the artistic or literary work, database, 114 | or other material to which the Licensor applied this Public 115 | License. 116 | 117 | i. Licensed Rights means the rights granted to You subject to the 118 | terms and conditions of this Public License, which are limited to 119 | all Copyright and Similar Rights that apply to Your use of the 120 | Licensed Material and that the Licensor has authority to license. 121 | 122 | j. Licensor means the individual(s) or entity(ies) granting rights 123 | under this Public License. 124 | 125 | k. NonCommercial means not primarily intended for or directed towards 126 | commercial advantage or monetary compensation. For purposes of 127 | this Public License, the exchange of the Licensed Material for 128 | other material subject to Copyright and Similar Rights by digital 129 | file-sharing or similar means is NonCommercial provided there is 130 | no payment of monetary compensation in connection with the 131 | exchange. 132 | 133 | l. Share means to provide material to the public by any means or 134 | process that requires permission under the Licensed Rights, such 135 | as reproduction, public display, public performance, distribution, 136 | dissemination, communication, or importation, and to make material 137 | available to the public including in ways that members of the 138 | public may access the material from a place and at a time 139 | individually chosen by them. 140 | 141 | m. Sui Generis Database Rights means rights other than copyright 142 | resulting from Directive 96/9/EC of the European Parliament and of 143 | the Council of 11 March 1996 on the legal protection of databases, 144 | as amended and/or succeeded, as well as other essentially 145 | equivalent rights anywhere in the world. 146 | 147 | n. You means the individual or entity exercising the Licensed Rights 148 | under this Public License. Your has a corresponding meaning. 149 | 150 | 151 | Section 2 -- Scope. 152 | 153 | a. License grant. 154 | 155 | 1. Subject to the terms and conditions of this Public License, 156 | the Licensor hereby grants You a worldwide, royalty-free, 157 | non-sublicensable, non-exclusive, irrevocable license to 158 | exercise the Licensed Rights in the Licensed Material to: 159 | 160 | a. reproduce and Share the Licensed Material, in whole or 161 | in part, for NonCommercial purposes only; and 162 | 163 | b. produce, reproduce, and Share Adapted Material for 164 | NonCommercial purposes only. 165 | 166 | 2. Exceptions and Limitations. For the avoidance of doubt, where 167 | Exceptions and Limitations apply to Your use, this Public 168 | License does not apply, and You do not need to comply with 169 | its terms and conditions. 170 | 171 | 3. Term. The term of this Public License is specified in Section 172 | 6(a). 173 | 174 | 4. Media and formats; technical modifications allowed. The 175 | Licensor authorizes You to exercise the Licensed Rights in 176 | all media and formats whether now known or hereafter created, 177 | and to make technical modifications necessary to do so. The 178 | Licensor waives and/or agrees not to assert any right or 179 | authority to forbid You from making technical modifications 180 | necessary to exercise the Licensed Rights, including 181 | technical modifications necessary to circumvent Effective 182 | Technological Measures. For purposes of this Public License, 183 | simply making modifications authorized by this Section 2(a) 184 | (4) never produces Adapted Material. 185 | 186 | 5. Downstream recipients. 187 | 188 | a. Offer from the Licensor -- Licensed Material. Every 189 | recipient of the Licensed Material automatically 190 | receives an offer from the Licensor to exercise the 191 | Licensed Rights under the terms and conditions of this 192 | Public License. 193 | 194 | b. Additional offer from the Licensor -- Adapted Material. 195 | Every recipient of Adapted Material from You 196 | automatically receives an offer from the Licensor to 197 | exercise the Licensed Rights in the Adapted Material 198 | under the conditions of the Adapter's License You apply. 199 | 200 | c. No downstream restrictions. You may not offer or impose 201 | any additional or different terms or conditions on, or 202 | apply any Effective Technological Measures to, the 203 | Licensed Material if doing so restricts exercise of the 204 | Licensed Rights by any recipient of the Licensed 205 | Material. 206 | 207 | 6. No endorsement. Nothing in this Public License constitutes or 208 | may be construed as permission to assert or imply that You 209 | are, or that Your use of the Licensed Material is, connected 210 | with, or sponsored, endorsed, or granted official status by, 211 | the Licensor or others designated to receive attribution as 212 | provided in Section 3(a)(1)(A)(i). 213 | 214 | b. Other rights. 215 | 216 | 1. Moral rights, such as the right of integrity, are not 217 | licensed under this Public License, nor are publicity, 218 | privacy, and/or other similar personality rights; however, to 219 | the extent possible, the Licensor waives and/or agrees not to 220 | assert any such rights held by the Licensor to the limited 221 | extent necessary to allow You to exercise the Licensed 222 | Rights, but not otherwise. 223 | 224 | 2. Patent and trademark rights are not licensed under this 225 | Public License. 226 | 227 | 3. To the extent possible, the Licensor waives any right to 228 | collect royalties from You for the exercise of the Licensed 229 | Rights, whether directly or through a collecting society 230 | under any voluntary or waivable statutory or compulsory 231 | licensing scheme. In all other cases the Licensor expressly 232 | reserves any right to collect such royalties, including when 233 | the Licensed Material is used other than for NonCommercial 234 | purposes. 235 | 236 | 237 | Section 3 -- License Conditions. 238 | 239 | Your exercise of the Licensed Rights is expressly made subject to the 240 | following conditions. 241 | 242 | a. Attribution. 243 | 244 | 1. If You Share the Licensed Material (including in modified 245 | form), You must: 246 | 247 | a. retain the following if it is supplied by the Licensor 248 | with the Licensed Material: 249 | 250 | i. identification of the creator(s) of the Licensed 251 | Material and any others designated to receive 252 | attribution, in any reasonable manner requested by 253 | the Licensor (including by pseudonym if 254 | designated); 255 | 256 | ii. a copyright notice; 257 | 258 | iii. a notice that refers to this Public License; 259 | 260 | iv. a notice that refers to the disclaimer of 261 | warranties; 262 | 263 | v. a URI or hyperlink to the Licensed Material to the 264 | extent reasonably practicable; 265 | 266 | b. indicate if You modified the Licensed Material and 267 | retain an indication of any previous modifications; and 268 | 269 | c. indicate the Licensed Material is licensed under this 270 | Public License, and include the text of, or the URI or 271 | hyperlink to, this Public License. 272 | 273 | 2. You may satisfy the conditions in Section 3(a)(1) in any 274 | reasonable manner based on the medium, means, and context in 275 | which You Share the Licensed Material. For example, it may be 276 | reasonable to satisfy the conditions by providing a URI or 277 | hyperlink to a resource that includes the required 278 | information. 279 | 3. If requested by the Licensor, You must remove any of the 280 | information required by Section 3(a)(1)(A) to the extent 281 | reasonably practicable. 282 | 283 | b. ShareAlike. 284 | 285 | In addition to the conditions in Section 3(a), if You Share 286 | Adapted Material You produce, the following conditions also apply. 287 | 288 | 1. The Adapter's License You apply must be a Creative Commons 289 | license with the same License Elements, this version or 290 | later, or a BY-NC-SA Compatible License. 291 | 292 | 2. You must include the text of, or the URI or hyperlink to, the 293 | Adapter's License You apply. You may satisfy this condition 294 | in any reasonable manner based on the medium, means, and 295 | context in which You Share Adapted Material. 296 | 297 | 3. You may not offer or impose any additional or different terms 298 | or conditions on, or apply any Effective Technological 299 | Measures to, Adapted Material that restrict exercise of the 300 | rights granted under the Adapter's License You apply. 301 | 302 | 303 | Section 4 -- Sui Generis Database Rights. 304 | 305 | Where the Licensed Rights include Sui Generis Database Rights that 306 | apply to Your use of the Licensed Material: 307 | 308 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 309 | to extract, reuse, reproduce, and Share all or a substantial 310 | portion of the contents of the database for NonCommercial purposes 311 | only; 312 | 313 | b. if You include all or a substantial portion of the database 314 | contents in a database in which You have Sui Generis Database 315 | Rights, then the database in which You have Sui Generis Database 316 | Rights (but not its individual contents) is Adapted Material, 317 | including for purposes of Section 3(b); and 318 | 319 | c. You must comply with the conditions in Section 3(a) if You Share 320 | all or a substantial portion of the contents of the database. 321 | 322 | For the avoidance of doubt, this Section 4 supplements and does not 323 | replace Your obligations under this Public License where the Licensed 324 | Rights include other Copyright and Similar Rights. 325 | 326 | 327 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 328 | 329 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 330 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 331 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 332 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 333 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 334 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 335 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 336 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 337 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 338 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 339 | 340 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 341 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 342 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 343 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 344 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 345 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 346 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 347 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 348 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 349 | 350 | c. The disclaimer of warranties and limitation of liability provided 351 | above shall be interpreted in a manner that, to the extent 352 | possible, most closely approximates an absolute disclaimer and 353 | waiver of all liability. 354 | 355 | 356 | Section 6 -- Term and Termination. 357 | 358 | a. This Public License applies for the term of the Copyright and 359 | Similar Rights licensed here. However, if You fail to comply with 360 | this Public License, then Your rights under this Public License 361 | terminate automatically. 362 | 363 | b. Where Your right to use the Licensed Material has terminated under 364 | Section 6(a), it reinstates: 365 | 366 | 1. automatically as of the date the violation is cured, provided 367 | it is cured within 30 days of Your discovery of the 368 | violation; or 369 | 370 | 2. upon express reinstatement by the Licensor. 371 | 372 | For the avoidance of doubt, this Section 6(b) does not affect any 373 | right the Licensor may have to seek remedies for Your violations 374 | of this Public License. 375 | 376 | c. For the avoidance of doubt, the Licensor may also offer the 377 | Licensed Material under separate terms or conditions or stop 378 | distributing the Licensed Material at any time; however, doing so 379 | will not terminate this Public License. 380 | 381 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 382 | License. 383 | 384 | 385 | Section 7 -- Other Terms and Conditions. 386 | 387 | a. The Licensor shall not be bound by any additional or different 388 | terms or conditions communicated by You unless expressly agreed. 389 | 390 | b. Any arrangements, understandings, or agreements regarding the 391 | Licensed Material not stated herein are separate from and 392 | independent of the terms and conditions of this Public License. 393 | 394 | 395 | Section 8 -- Interpretation. 396 | 397 | a. For the avoidance of doubt, this Public License does not, and 398 | shall not be interpreted to, reduce, limit, restrict, or impose 399 | conditions on any use of the Licensed Material that could lawfully 400 | be made without permission under this Public License. 401 | 402 | b. To the extent possible, if any provision of this Public License is 403 | deemed unenforceable, it shall be automatically reformed to the 404 | minimum extent necessary to make it enforceable. If the provision 405 | cannot be reformed, it shall be severed from this Public License 406 | without affecting the enforceability of the remaining terms and 407 | conditions. 408 | 409 | c. No term or condition of this Public License will be waived and no 410 | failure to comply consented to unless expressly agreed to by the 411 | Licensor. 412 | 413 | d. Nothing in this Public License constitutes or may be interpreted 414 | as a limitation upon, or waiver of, any privileges and immunities 415 | that apply to the Licensor or You, including from the legal 416 | processes of any jurisdiction or authority. 417 | 418 | ======================================================================= 419 | 420 | Creative Commons is not a party to its public 421 | licenses. Notwithstanding, Creative Commons may elect to apply one of 422 | its public licenses to material it publishes and in those instances 423 | will be considered the “Licensor.” The text of the Creative Commons 424 | public licenses is dedicated to the public domain under the CC0 Public 425 | Domain Dedication. Except for the limited purpose of indicating that 426 | material is shared under a Creative Commons public license or as 427 | otherwise permitted by the Creative Commons policies published at 428 | creativecommons.org/policies, Creative Commons does not authorize the 429 | use of the trademark "Creative Commons" or any other trademark or logo 430 | of Creative Commons without its prior written consent including, 431 | without limitation, in connection with any unauthorized modifications 432 | to any of its public licenses or any other arrangements, 433 | understandings, or agreements concerning use of licensed material. For 434 | the avoidance of doubt, this paragraph does not form part of the 435 | public licenses. 436 | 437 | Creative Commons may be contacted at creativecommons.org. 438 | -------------------------------------------------------------------------------- /static/img/undraw_docusaurus_mountain.svg: -------------------------------------------------------------------------------- 1 | 2 | Easy to Use 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | -------------------------------------------------------------------------------- /static/img/undraw_docusaurus_react.svg: -------------------------------------------------------------------------------- 1 | 2 | Powered by React 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107 | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115 | 116 | 117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | 136 | 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | 151 | 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | --------------------------------------------------------------------------------