Output a warning for unknown configuration rules in `.swift-format` #612

natikgadzhi · 2023-09-04T01:25:43Z

Summary:

Helps developers surface any errors and typos in their .swift-format config files by showing a warning when running swift-format if the configuration includes invalid rules.
The actual check is in Frontend.swift.
The dictionary of rules for verification is in RuleRegistry, which is made public to be able to import it in swift-format target.

Example output:

 ❯ ../swift-format/.build/debug/swift-format lint Sources/SwiftSyntax/Convenience.swift
/Users/nategadzhi/src/apple/swift-syntax/.swift-format:10:10: warning: Configuration contains an unrecognized rule IAmABrokenRule
/Users/nategadzhi/src/apple/swift-syntax/.swift-format:14:10: warning: Configuration contains an unrecognized rule LolNope

Motivation:

Closes Implement a warning or error if an unrecognized Rule is specified in .swift-format #607

Reviewing

I'm a beginner — pretty please "well actually" me if you see me making mistakes, I'm here to learn ❤️
~~I've made RuleRegistry.rules public. We could in theory use _@spi instead. public seems simple and okay — do you think that's fine?~~ RuleRegistry is now @_spi(Internal).
There are no tests whatsoever, as in the whole swift-format executable target is not tested. See Unit tests for swift-format CLI tool and for Plugins #611. I think I can start us off with a very simple test that tests specifically Frontend.configuration().

Potential improvements

✅ This PR does not report the source location, hence the <unknown> in the warning line. Hypothetically, we could read the configuration into an array of strings, and find the index of the string containing the unsupported rule, and construct the source location from that. Since the performance hit is negligible, that could be a nice touch. Source location reporting is in, but it's sliiiightly ugly.

@allevato, how does that look to you? What else can I improve? If the general direction seems good, I would be happy to invest a bit more time and perhaps provide source locations.

allevato

Can you update this now that #614 has been merged, which moved everything from the SwiftFormatConfiguration module into SwiftFormat?

Sources/SwiftFormatConfiguration/RuleRegistry+Generated.swift

Sources/swift-format/Frontend/Frontend.swift

natikgadzhi · 2023-09-06T00:05:53Z

@allevato, I've addressed your first round of feedback:

@_spi for RuleRegistry
Wording

Next up: potentially do source location. If you're happy with what is currently here, it would be okay by me to merge and follow up with an improvement. But, up to you!

natikgadzhi

@allevato ready for another review! I made the source locations work in a not entirely ugly way, I think!

natikgadzhi · 2023-09-06T04:51:52Z

Sources/SwiftFormat/Core/RuleRegistry+Generated.swift

@@ -12,8 +12,8 @@

 // This file is automatically generated with generate-pipeline. Do Not Edit!

-enum RuleRegistry {
-  static let rules: [String: Bool] = [
+@_spi(Internal) public enum RuleRegistry {


@allevato, @_spi is done here.

natikgadzhi · 2023-09-06T04:52:33Z

Sources/swift-format/Frontend/Frontend.swift

 import SwiftSyntax
 import SwiftParser

+@_spi(Internal) import SwiftFormat


Reordered imports, but we should probably just setup formatter in #610. I'm happy to do it, just say the word ;)

natikgadzhi · 2023-09-06T04:52:58Z

Sources/swift-format/Frontend/Frontend.swift

-    // If an explicit configuration file path was given, try to load it and fail if it cannot be
-    // loaded. (Do not try to fall back to a path inferred from the source file path.)
+    // The actual config file that this frontend is going to use.
+    let configURL: URL?


I need the config file URL later to figure out the source location, so this function got a little refactor in.

natikgadzhi · 2023-09-06T04:55:40Z

Sources/swift-format/Frontend/Frontend.swift

+  /// - parameters:
+  ///   - configuration: `Configuration` to verify
+  ///   - configURL: Configuration file `URL` to use in `Diagnostic.Location`
+  private func verifyConfigurationRules(for configuration: Configuration, at configURL: URL) throws {


I'm meh on naming here. It does get the job done, but I don't think the name is 💯.

verify implies that if the config is invalid, it will throw and the program will exit with an error.

Perhaps an explicit checkForUnrecognizedRules(in: config, at: path)?

Also: I don't think it throws anymore.

checkForUnrecognizedRules(in: config, at: path) sounds good to me. And yeah, remove the throws if it's no longer necessary.

Sources/swift-format/Utilities/Diagnostic.swift

Sources/swift-format/Utilities/DiagnosticsEngine.swift

allevato · 2023-09-06T12:48:54Z

Sources/swift-format/Frontend/Frontend.swift

+  /// - parameters:
+  ///   - configuration: `Configuration` to verify
+  ///   - configURL: Configuration file `URL` to use in `Diagnostic.Location`
+  private func verifyConfigurationRules(for configuration: Configuration, at configURL: URL) throws {


checkForUnrecognizedRules(in: config, at: path) sounds good to me. And yeah, remove the throws if it's no longer necessary.

allevato · 2023-09-06T12:51:36Z

Sources/swift-format/Frontend/Frontend.swift

+
+  /// Returns a `Diagnostic.Location` of the substring in an array of Strings.
+  /// It's intented to find the location of a configuration Rule in an array of Strings representing the encoded JSON swift-format configuration file.
+  private func diagnosticLocationFor(substring: String, in configuration: String, filePath: String) -> Diagnostic.Location? {


For what it's worth, I don't think this is really necessary. If someone mistypes a rule name, it won't take them long to figure out where in the configuration it is. And if we could get the information during decoding, it might be useful (still questionable though), but since this is just doing raw string searches, it's too prone to false positives if the invalid rule name matches something somewhere else in the configuration string.

Can you remove this and just emit a warning with no location?

natikgadzhi · 2023-09-06T14:47:14Z

Can you remove this and just emit a warning with no location?

Sounds great to me. I felt that it's too much ceremony, but liked the neat detail of having a line number.

I'll do that, and some light cleaning up — that should be ready in a couple of hours.

**Summary**: - Helps developers surface any errors and typos in their `.swift-format` config files by showing a warning when running `swift-format` if the configuration includes invalid rules. - The actual check is in `Frontend.swift`. - The dictionary of rules for verification is in `RuleRegistry`, which is made `public` to be able to import it in `swift-format` target. **Motivation**: - Closes swiftlang#607 Apply suggestions from code review Co-authored-by: Tony Allevato <tony.allevato@gmail.com> Cleaning up based on PR review

natikgadzhi · 2023-09-06T22:27:25Z

@allevato, alright, cleaned it up. Pained me to reduce clarity by removing source location, but you're right — re-reading config and doing raw string match is clumsy and buggy.

allevato

Looks good now, thank you!

…on/unknown-rules Output a warning for unknown configuration rules in `.swift-format`

natikgadzhi force-pushed the feature/configuration/unknown-rules branch 2 times, most recently from 49c9a8d to cad7b65 Compare September 4, 2023 05:05

allevato reviewed Sep 5, 2023

View reviewed changes

Sources/SwiftFormatConfiguration/RuleRegistry+Generated.swift Outdated Show resolved Hide resolved

Sources/swift-format/Frontend/Frontend.swift Outdated Show resolved Hide resolved

Sources/swift-format/Frontend/Frontend.swift Outdated Show resolved Hide resolved

natikgadzhi force-pushed the feature/configuration/unknown-rules branch from 6d3c19f to 3a62daa Compare September 5, 2023 17:35

natikgadzhi requested a review from allevato September 6, 2023 00:04

natikgadzhi commented Sep 6, 2023

View reviewed changes

allevato reviewed Sep 6, 2023

View reviewed changes

natikgadzhi force-pushed the feature/configuration/unknown-rules branch from e982bac to 5d45493 Compare September 6, 2023 22:26

natikgadzhi requested a review from allevato September 6, 2023 22:26

allevato mentioned this pull request Sep 7, 2023

[DO NOT MERGE] allevato's dummy PR for swift-format CI swiftlang/swift-syntax#1086

Open

allevato approved these changes Sep 7, 2023

View reviewed changes

allevato merged commit 5a5d876 into swiftlang:main Sep 7, 2023

allevato added a commit to allevato/swift-format that referenced this pull request Sep 14, 2023

Merge pull request swiftlang#612 from natikgadzhi/feature/configurati…

27bfeca

…on/unknown-rules Output a warning for unknown configuration rules in `.swift-format`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Output a warning for unknown configuration rules in `.swift-format` #612

Output a warning for unknown configuration rules in `.swift-format` #612

natikgadzhi commented Sep 4, 2023 •

edited

Loading

allevato left a comment

natikgadzhi commented Sep 6, 2023

natikgadzhi left a comment

natikgadzhi Sep 6, 2023

natikgadzhi Sep 6, 2023

natikgadzhi Sep 6, 2023

natikgadzhi Sep 6, 2023

allevato Sep 6, 2023

allevato Sep 6, 2023

allevato Sep 6, 2023

natikgadzhi commented Sep 6, 2023

natikgadzhi commented Sep 6, 2023

allevato left a comment

Output a warning for unknown configuration rules in .swift-format #612

Output a warning for unknown configuration rules in .swift-format #612

Conversation

natikgadzhi commented Sep 4, 2023 • edited Loading

allevato left a comment

Choose a reason for hiding this comment

natikgadzhi commented Sep 6, 2023

natikgadzhi left a comment

Choose a reason for hiding this comment

natikgadzhi Sep 6, 2023

Choose a reason for hiding this comment

natikgadzhi Sep 6, 2023

Choose a reason for hiding this comment

natikgadzhi Sep 6, 2023

Choose a reason for hiding this comment

natikgadzhi Sep 6, 2023

Choose a reason for hiding this comment

allevato Sep 6, 2023

Choose a reason for hiding this comment

allevato Sep 6, 2023

Choose a reason for hiding this comment

allevato Sep 6, 2023

Choose a reason for hiding this comment

natikgadzhi commented Sep 6, 2023

natikgadzhi commented Sep 6, 2023

allevato left a comment

Choose a reason for hiding this comment

Output a warning for unknown configuration rules in `.swift-format` #612

Output a warning for unknown configuration rules in `.swift-format` #612

natikgadzhi commented Sep 4, 2023 •

edited

Loading