Customizing transformations on the command line with Amazon Q Developer - Amazon Q Developer
Orchestrator filesCustom transformation files

Customizing transformations on the command line with Amazon Q Developer

Note

This feature is only available for transformations on the command line.

You can customize transformations by providing custom logic in the form of ast-grep rules that Amazon Q uses to make changes to your code. ast-grep is an abstract syntax tree tool that can be used to rewrite code. Amazon Q leverages ast-grep to run customized transformations. For more information, see What is ast-grep? in the ast-grep documentation.

Amazon Q performs the custom transformation locally. The custom transformation happens in addition to the Java upgrades in an Amazon Q transformation.

To configure a custom transformation, you provide two file types that specify the custom logic:

  • An orchestrator file, where you define what custom transformations to run before the Amazon Q transformation, and which ones to run after

  • One or more custom transformation files, where you define an ast-grep rule

After creating an orchestrator file and your custom transformation files, you can start a transformation job with the customization option and the path to your orchestrator file. Following is the command you run to start a transformation with a custom transformation:

qct transform --source_folder <path-to-folder>
    --custom_transformation_file <path-to-orchestrator-file>

Orchestrator files

An orchestrator file is a YAML file where you provide the paths to the custom transformation files that Amazon Q will run, and specify when to run the rules (before or after the Amazon Q transformation).

The following fields are required in the transformation file:

  • name

  • description

  • At least one of the following:

    • To run a custom transformation before the Amazon Q transformation, add the path to a custom transformation file under pre_qct_actions:

    • To run a custom transformation after the Amazon Q transformation, add the path to a custom transformation file under post_qct_actions:

Following is an example of the syntax in an orchestrator file:

name: custom_change_1
description: My collection of custom transformations to run before and after a transformation.

pre_qct_actions:
  ast-grep:
    rules:
      - /path/to/custom-transformation3.yaml
      - /path/to/custom-transformation2.yaml

post_qct_actions:
  ast-grep:
    rules:
      - /path/to/custom-transformation3.yaml

Custom transformation files

Custom transformation files are YAML files where you define the code changes you want Amazon Q to make in the form of an ast-grep rule. Amazon Q only supports ast-grep compatible rules for custom transformations.

Amazon Q can run custom transformations before or after it runs a transformation. See the following guidance on when custom transformation types should be run:

  • Custom transformations you run before the Amazon Q transformation should focus on code preprocessing tasks. Your code must be compilable after the custom transformations are run in order to continue with the Amazon Q transformation.

  • Custom transformations run after the Amazon Q transformation can involve tasks like upgrading internal libraries or other tasks related to private resources. If these tasks break the code build, Amazon Q can debug and fix issues that arise from the custom transformation.

Following is an example of a custom transformation file with an ast-grep rule:

id: no-unused-vars
language: java
rule:
    kind: local_variable_declaration
    all:
        - has:
            has:
                kind: identifier
                pattern: $IDENT
        - not:
            precedes:
                stopBy: end
                has:
                    stopBy: end
                    any:
                        - { kind: identifier, pattern: $IDENT }
                        - { has: {kind: identifier, pattern: $IDENT, stopBy: end}}
fix: ''

You can learn more about how this example works at https://ast-grep.github.io/catalog/java/.