Add custom ktlint rules to prevent Java interop issues

[alancai98]

Relevant Issues

• Decide on Java interop w/ Kotlin top-level functions #1387

Description

Adds custom ktlint rules to report on Java interop issues mentioned in #1387:

• top-level internal functions and values
• top-level public functions and values without a @file:JvmName annotation

This PR integrates the checks into gradle and GH Actions. By default, the custom rules will not be run since there are quite a few usages of the above patterns throughout our code. These usages should be fixed in upcoming PRs. The following outlines how the custom rules can be run:

# No option -- runs the standard ktlint checks as before
❯ ./gradlew ktlintCheck

# `custom-ktlint-rules` parameter included -- runs the standard ktlint checks along with the custom ktlint rules
# Note: run on just the `main` sources; `test` sources are excluded
# Note: any detected issues won't fail-fast so that all detected issues can be reported
❯ ./gradlew ktlintCheck -Pcustom-ktlint-rules

# Run on a given subproject
❯ ./gradlew :partiql-ast:ktlintCheck -Pcustom-ktlint-rules

> Task :partiql-ast:ktlintMainSourceSetCheck
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/helpers/ToBinder.kt:21:17 Top-level public declaration found without `@file:JvmName` annotation: toBinder (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/helpers/ToBinder.kt:35:17 Top-level public declaration found without `@file:JvmName` annotation: toBinder (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/helpers/ToLegacyAst.kt:58:20 Top-level public declaration found without `@file:JvmName` annotation: toLegacyAst (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/normalize/Normalize.kt:22:22 Top-level public declaration found without `@file:JvmName` annotation: normalize (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:10:20 Top-level public declaration found without `@file:JvmName` annotation: sql (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:19:20 Top-level public declaration found without `@file:JvmName` annotation: sql (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:27:20 Top-level public declaration found without `@file:JvmName` annotation: sql (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:35:20 Top-level public declaration found without `@file:JvmName` annotation: sql (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:42:29 Top-level internal declaration found: concat (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:44:29 Top-level internal declaration found: concat (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:46:38 Top-level internal declaration found: plus (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:48:38 Top-level internal declaration found: plus (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:52:14 Top-level internal declaration found: NIL (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:54:14 Top-level internal declaration found: NL (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:56:14 Top-level internal declaration found: text (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:58:14 Top-level internal declaration found: link (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:60:14 Top-level internal declaration found: nest (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/Sql.kt:62:14 Top-level internal declaration found: list (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/ast/sql/SqlBlock.kt:10:21 Top-level public declaration found without `@file:JvmName` annotation: sql (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/lang/ast/meta.kt:63:20 Top-level public declaration found without `@file:JvmName` annotation: to (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/lang/ast/meta.kt:65:19 Top-level public declaration found without `@file:JvmName` annotation: find (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/lang/ast/meta.kt:67:19 Top-level public declaration found without `@file:JvmName` annotation: hasMeta (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/lang/ast/meta.kt:69:19 Top-level public declaration found without `@file:JvmName` annotation: add (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/lang/ast/SourceLocationMeta.kt:78:5 Top-level public declaration found without `@file:JvmName` annotation: UNKNOWN_SOURCE_LOCATION (cannot be auto-corrected)
./partiql-lang-kotlin/partiql-ast/src/main/kotlin/org/partiql/lang/ast/SourceLocationMeta.kt:80:19 Top-level public declaration found without `@file:JvmName` annotation: sourceLocation (cannot be auto-corrected)

Output of the GH Action step running the custom ktlint rules can be seen here: https://github.com/partiql/partiql-lang-kotlin/actions/runs/8639028556/job/23684585083?pr=1414.

Other Information

• Updated Unreleased Section in CHANGELOG: [NO]

  • No public API changes.

• Any backward-incompatible changes? [NO]

• Any new external dependencies? [YES]

  • com.pinterest.ktlint:ktlint-core:0.42.1
  • com.pinterest.ktlint:ktlint-test:0.42.1

• Do your changes comply with the Contributing Guidelines
  and Code Style Guidelines? [YES]

License Information

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.

[github-actions]

Conformance comparison report

	Base (ab65143)	363d943	+/-
% Passing	92.54%	92.54%	0.00%
✅ Passing	5384	5384	0
❌ Failing	434	434	0
🔶 Ignored	0	0	0
Total Tests	5818	5818	0

Number passing in both: 5384

Number failing in both: 434

Number passing in Base (ab65143) but now fail: 0

Number failing in Base (ab65143) but now pass: 0

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 73.16%. Comparing base (d059c81) to head (15f6bfc).
Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff            @@
##               main    #1414   +/-   ##
=========================================
  Coverage     73.16%   73.16%           
  Complexity     2393     2393           
=========================================
  Files           247      247           
  Lines         17627    17627           
  Branches       3178     3178           
=========================================
  Hits          12896    12896           
  Misses         3854     3854           
  Partials        877      877           

Flag	Coverage Δ
CLI	11.82% <ø> (ø)
EXAMPLES	80.07% <ø> (ø)
LANG	81.06% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[alancai98]

After the internal top-level and public top-level code issues are resolved, we can remove this property logic such that the custom ktlint rules will run by default.

# End state after existing code issues detected by custom ktlint rules are resolved
> ./gradlew ktlintCheck # will run standard and custom rules

Any detected issues in gradle and GH Actions will also fail the build.

[rchowell]

How did we go back from 11.6.0 to 0.42.1? Was the original one for the the gradle plugin, and this is for the custom rule dependencies?

[alancai98]

There were a couple confusing things here previously.

• The ktlint dependency defined previously actually referred to the ktlint gradle plugin -- https://github.com/JLLeitschuh/ktlint-gradle and not the actual ktlint Maven dependency -- https://github.com/pinterest/ktlint
• The 11.6.0 dependency (defined in buildSrc/src/main/kotlin/partiql.versions.kt) was actually unused. We were actually using the 10.2.1 ktlint gradle plugin defined in buildSrc/build.gradle.kts

The v0.42.1 refers to the default ktlint version that the 10.2.1 kotlin gradle plugin uses (see their source). I chose to use the same ktlint version for the custom rules that we were using for the default ktlintCheck/ktlintFormat runs. I didn't upgrade the default ktlint version from v0.42.1 to a newer one since there are some additional rules that our code is not compliant with. We can perform this ktlint version upgrade in a future PR (tracked in #1418).

Hope that makes things clearer.

[alancai98]

There were a couple confusing things here previously.

• The ktlint dependency defined previously actually referred to the ktlint gradle plugin -- https://github.com/JLLeitschuh/ktlint-gradle and not the actual ktlint Maven dependency -- https://github.com/pinterest/ktlint
• The 11.6.0 dependency (defined in buildSrc/src/main/kotlin/partiql.versions.kt) was actually unused. We were actually using the 10.2.1 ktlint gradle plugin defined in buildSrc/build.gradle.kts

The v0.42.1 refers to the default ktlint version that the 10.2.1 kotlin gradle plugin uses (see their source). I chose to use the same ktlint version for the custom rules that we were using for the default ktlintCheck/ktlintFormat runs. I didn't upgrade the default ktlint version from v0.42.1 to a newer one since there are some additional rules that our code is not compliant with. We can perform this ktlint version upgrade in a future PR (tracked in #1418).

Hope that makes things clearer.

[alancai98]

For clarity, we were actually using this version, 10.2.1 of the ktlint gradle plugin -- https://github.com/JLLeitschuh/ktlint-gradle/tree/v10.2.1.