Skip to content

Commit

Permalink
Rename the directory to polyglot (#197)
Browse files Browse the repository at this point in the history
Rename the directory `generic` to `polyglot`
  • Loading branch information
ketkarameya authored Jun 22, 2022
1 parent ea5d103 commit bae2449
Show file tree
Hide file tree
Showing 122 changed files with 24 additions and 30 deletions.
3 changes: 1 addition & 2 deletions .github/workflows/polyglot_release.yml
Original file line number Diff line number Diff line change
@@ -1,4 +1,3 @@
# .github/workflows/release.yml
name: Release Polyglot Piranha
on:
release:
Expand Down Expand Up @@ -27,4 +26,4 @@ jobs:
with:
RUSTTARGET: ${{ matrix.target }}
ARCHIVE_TYPES: ${{ matrix.archive }}
SRC_DIR: generic/piranha
SRC_DIR: polyglot/piranha
8 changes: 3 additions & 5 deletions .github/workflows/rust.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,11 @@ jobs:
toolchain: stable
override: true
components: rustfmt, clippy
- name: Install Tree-Sitter
run: cargo install tree-sitter-cli
- name: Build Piranha
run: cargo build
working-directory: generic/piranha
working-directory: polyglot/piranha
- name: Clippy check
run: cargo clippy
working-directory: generic/piranha
working-directory: polyglot/piranha
- run: cargo test
working-directory: generic/piranha
working-directory: polyglot/piranha
11 changes: 4 additions & 7 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -10,13 +10,10 @@ swift/artifact
swift/Piranha.xcodeproj
swift/Package.resolved
**/*.iml
generic/piranha/target
generic/piranha/Cargo.lock
generic/piranha/.idea
generic/tree-sitter-src/tree-sitter-java
generic/tree-sitter-src/tree-sitter-swift
generic/tree-sitter-src/tree-sitter-kotlin
polyglot/piranha/target
polyglot/piranha/Cargo.lock
polyglot/piranha/.idea
.history
.vscode
**/*.log
generic/piranha/demo/piranha
polyglot/piranha/demo/piranha
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Feature flags are commonly used to enable gradual rollout or experiment with new

Piranha is a tool to automatically refactor code related to stale flags. At a higher level, the input to the tool is the name of the flag and the expected behavior, after specifying a list of APIs related to flags in a properties file. Piranha will use these inputs to automatically refactor the code according to the expected behavior.

This repository contains four independent versions of Piranha, one for each of the four supported languages: Java, JavaScript, Objective-C and Swift. **It also contains a redesigned variant of Piranha (as of May 2022) that is a common refactoring tool to support multiple languages and feature flag APIs. If interested in this generic variant, goto [PiranhaGeneric](generic/README.md)**.
This repository contains four independent versions of Piranha, one for each of the four supported languages: Java, JavaScript, Objective-C and Swift. **It also contains a redesigned variant of Piranha (as of May 2022) that is a common refactoring tool to support multiple languages and feature flag APIs. If interested in this polyglot variant, goto [Polyglot Piranha](polyglot/README.md)**.

To use/build each version, look under the corresponding [lang]/ directory and follow instructions in the corresponding [lang]/README.md file. Make sure to cd into that directory to build any related code following the instructions in the README.

Expand Down
30 changes: 15 additions & 15 deletions generic/README.md → polyglot/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,30 +47,30 @@ Languages supported :
## Building Piranha from Source
* Install [Rust](https://www.rust-lang.org/tools/install), Git and [tree-sitter CLI](https://github.com/tree-sitter/tree-sitter/blob/master/cli/README.md)
* Checkout this repository - `git checkout https://github.com/uber/piranha.git`
* `cd piranha/generic/piranha`
* `cd piranha/polyglot/piranha`
* `cargo build --release`
* You will see the binary under `target/release`

## Getting started with Piranha

*Please refer to our [demo](/generic/piranha/demo/run_piranha_demo.sh) - to quickly get started with Piranha.*
*Please refer to our [demo](/polyglot/piranha/demo/run_piranha_demo.sh) - to quickly get started with Piranha.*
To run the demo :
* `cd generic/piranha`
* `cd polyglot/piranha`
* `./demo/run_piranha_demo.sh`
*Please refer to our test cases at [`/generic/piranha/src/test-resources/<language>/`](/generic/piranha/src/test-resources/) as a reference for handling complicated scenarios*
*Please refer to our test cases at [`/polyglot/piranha/src/test-resources/<language>/`](/polyglot/piranha/src/test-resources/) as a reference for handling complicated scenarios*

To get started with Piranha, please follow the below steps:
* Check if the current version of Piranha supports the required language.
* If so, then check if the API usage is similar to the ones shown in the demo ([java-demo](/generic/piranha/demo/java/configurations/rules.toml)) or in the test resources ([java-ff_system1](/piranha/test-resources/java/feature_flag_system_1/control/configurations/rules.toml), [java-ff_system2](/piranha/test-resources/java/feature_flag_system_2/control/configurations/rules.toml)).
* If so, then check if the API usage is similar to the ones shown in the demo ([java-demo](/polyglot/piranha/demo/java/configurations/rules.toml)) or in the test resources ([java-ff_system1](/piranha/test-resources/java/feature_flag_system_1/control/configurations/rules.toml), [java-ff_system2](/piranha/test-resources/java/feature_flag_system_2/control/configurations/rules.toml)).
* If not, adapt these examples to your requirements. Further, you can study the [tree-sitter query documentation](https://tree-sitter.github.io/tree-sitter/using-parsers#pattern-matching-with-queries) to understand how tree-sitter queries work.
* Now adapt the [argument file](/generic/piranha/demo/java/configurations/piranha_arguments.toml) as per your requirements. For instance, you may want to update the value corresponding to the `@stale_flag_name` and `@treated`. If your rules do not contain require other tags feel free to remove them from your arguments file. In most cases [edges file](/demo/java/configurations/edges.toml) is not required, unless your feature flag system API rules are inter-dependent.
* Now adapt the [argument file](/polyglot/piranha/demo/java/configurations/piranha_arguments.toml) as per your requirements. For instance, you may want to update the value corresponding to the `@stale_flag_name` and `@treated`. If your rules do not contain require other tags feel free to remove them from your arguments file. In most cases [edges file](/demo/java/configurations/edges.toml) is not required, unless your feature flag system API rules are inter-dependent.

More details for configuring Piranha - [Adding support for a new feature flag system](adding-support-for-a-new-feature-flag-system)
and [Adding Support for a new language](adding-support-for-a-new-language).

## Adding support for a new feature flag system

To onboard a new feature flag system users will have to specify the `<path-to-configurations>/rules.toml` and `<path-to-configurations>/edges.toml` files (look [here](/generic/piranha/src/cleanup_rules/java)). The `rules.toml` will contain rules that identify the usage of a feature flag system API. Defining `edges.toml` is required if your feature flag system API rules are inter-dependent.
To onboard a new feature flag system users will have to specify the `<path-to-configurations>/rules.toml` and `<path-to-configurations>/edges.toml` files (look [here](/polyglot/piranha/src/cleanup_rules/java)). The `rules.toml` will contain rules that identify the usage of a feature flag system API. Defining `edges.toml` is required if your feature flag system API rules are inter-dependent.
For instance, you want to delete a method declaration with specific annotations and then update its usages with some boolean value.
Please refer to the `test-resources/java` for detailed examples.

Expand Down Expand Up @@ -207,30 +207,30 @@ int foobar(){

We would first define flag API rules as discussed in the section [Adding Support for a new language](adding-support-for-a-new-language). Assuming this rule replaces the occurrence of the flag API corresponding to `SOME_STALE_FLAG` with `true`; we would have to define more cleanup rules as follows:

* `R0`: Deletes the enclosing variable declaration (i.e. `x`) (E.g. [java-rules](/generic/piranha/src/cleanup_rules/java/rules.toml):`delete_variable_declarations`)
* `R1`: replace the identifier with the RHS of the deleted variable declaration, within the body of the enclosing method where `R0` was applied i.e. replace `x` with `true` within the method body of `foobar`. (E.g. [java-rules](/generic/piranha/src/cleanup_rules/java/rules.toml):`replace_expression_with_boolean_literal`)
* `R2`: simplify the boolean expressions, for example replace `true || someCondition()` with `true`, that encloses the node where `R1` was applied. (E.g. [java-rules](/generic/piranha/src/cleanup_rules/java/rules.toml): `true_or_something`)
* `R3`: eliminate the enclosing if statement with a constant condition where `R2` was applied (`if (true) { return 100;}``return 100;`). E.g. [java-rules](/generic/piranha/src/cleanup_rules/java/rules.toml): `simplify_if_statement_true, remove_unnecessary_nested_block`
* `R4`: eliminate unreachable code (`return 0;` in `return 100; return 0;`) in the enclosing block where `R3` was applied. (E.g. [java-rules](/generic/piranha/src/cleanup_rules/java/rules.toml): `delete_all_statements_after_return`)
* `R0`: Deletes the enclosing variable declaration (i.e. `x`) (E.g. [java-rules](/polyglot/piranha/src/cleanup_rules/java/rules.toml):`delete_variable_declarations`)
* `R1`: replace the identifier with the RHS of the deleted variable declaration, within the body of the enclosing method where `R0` was applied i.e. replace `x` with `true` within the method body of `foobar`. (E.g. [java-rules](/polyglot/piranha/src/cleanup_rules/java/rules.toml):`replace_expression_with_boolean_literal`)
* `R2`: simplify the boolean expressions, for example replace `true || someCondition()` with `true`, that encloses the node where `R1` was applied. (E.g. [java-rules](/polyglot/piranha/src/cleanup_rules/java/rules.toml): `true_or_something`)
* `R3`: eliminate the enclosing if statement with a constant condition where `R2` was applied (`if (true) { return 100;}``return 100;`). E.g. [java-rules](/polyglot/piranha/src/cleanup_rules/java/rules.toml): `simplify_if_statement_true, remove_unnecessary_nested_block`
* `R4`: eliminate unreachable code (`return 0;` in `return 100; return 0;`) in the enclosing block where `R3` was applied. (E.g. [java-rules](/polyglot/piranha/src/cleanup_rules/java/rules.toml): `delete_all_statements_after_return`)

The fact that `R2` has to be applied to the enclosing node where `R1` was applied, is expressed by specifying the `edges.toml` file.

To define how these cleanup rules should be chained, one needs to specify edges (e.g. the [java-edges](/generic/piranha/src/cleanup_rules/java/edges.toml) file) between the groups and (or) individual rules.
To define how these cleanup rules should be chained, one needs to specify edges (e.g. the [java-edges](/polyglot/piranha/src/cleanup_rules/java/edges.toml) file) between the groups and (or) individual rules.
The edges can be labelled as `Parent`, `Global` or even much finer scopes like `Method` or `Class` (or let's say `functions` in `go-lang`).
* A `Parent` edge implies that after Piranha applies the `"from"` rule to update the node `n1` in the AST to node `n2`, Piranha tries to apply `"to"` rules on any ancestor of `"n2"` (e.g. `R1``R2`, `R2``R3`, `R3``R4`)
* A `Method` edge implies that after Piranha applies the `"from"` rule to update the node `n1` in the AST to node `n2`, Piranha tries to apply `"to"` rules within the enclosing method's body. (e.g. `R0``R1`)
* A `Class` edge implies that after Piranha applies the `"from"` rule to update the node `n1` in the AST to node `n2`, Piranha tries to apply `"to"` rules within the enclosing class body. (e.g. in-lining a private field)
* A `Global` edge implies that after Piranha applies the `"from"` rule to update the node `n1` in the AST to node `n2`, Piranha tries to apply `"to"` rules in the entire code base. (e.g. in-lining a public field).

`scope_config.toml` file specifies how to capture these fine-grained scopes like `method`, `function`, `lambda`, `class`.
First decide, what scopes you need to capture, for instance, in Java we capture "Method" and "Class" scopes. Once, you decide the scopes construct scope query generators similar to [java-scope_config](/generic/piranha/src/cleanup_rules/java/scope_config.toml). Each scope query generator has two parts - (i) `matcher` is a tree-sitter query that matches the AST for the scope, and (ii) `generator` is a tree-sitter query with holes that is instantiated with the code snippets corresponding to tags when `matcher` is matched.
First decide, what scopes you need to capture, for instance, in Java we capture "Method" and "Class" scopes. Once, you decide the scopes construct scope query generators similar to [java-scope_config](/polyglot/piranha/src/cleanup_rules/java/scope_config.toml). Each scope query generator has two parts - (i) `matcher` is a tree-sitter query that matches the AST for the scope, and (ii) `generator` is a tree-sitter query with holes that is instantiated with the code snippets corresponding to tags when `matcher` is matched.


## Contributing

### Naming conventions for the rules
* We name the rules in the format - <verb>_<ast_kind>. E.g., `delete_method_declaration` or `replace_expression with_boolean_literal`
* We name the dummy rules in the format - `<ast_kind>_cleanup` E.g. `statement_cleanup` or `boolean_literal_cleanup`. Using dummy rules (E.g. [java-rules](/generic/piranha/src/cleanup_rules/java/rules.toml): `boolean_literal_cleanup`) makes it easier and cleaner when specifying the flow between rules.
* We name the dummy rules in the format - `<ast_kind>_cleanup` E.g. `statement_cleanup` or `boolean_literal_cleanup`. Using dummy rules (E.g. [java-rules](/polyglot/piranha/src/cleanup_rules/java/rules.toml): `boolean_literal_cleanup`) makes it easier and cleaner when specifying the flow between rules.

### Writing tests
Currently we maintain
Expand Down
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.

0 comments on commit bae2449

Please sign in to comment.