Support for skipping lines before license header

[abelk2]

This PR proposes a solution for supporting license headers on files where the header cannot be added immediately to the top of the file because of the format's restrictions. Examples are XML (<?xml version="1.0" ...) or shell scripts (#!/bin/bash).

The change simply allows configuring a regex for the LicenseHeaderStep. All the lines at the beginning of the file that match this regex will be skipped, and written directly to the output, then the rest of the lines will be processed the same way as before.

An example configuration would be something like:

format "licenseHeaderSh", {
  target "**/*.sh"
  licenseHeaderFile(file("$rootDir/config/license/sh.txt"), "^(?!##).+")
    .skipLinesMatching("^#!.+?\$")
}

This PR contains a working proof of concept, but lacks the following:

• New test cases
• Maven support
• Change log updates

I'll add these if the concept is accepted.

Related issues:
#496

[nedtwigg]

This is a great proposal as-is, thanks very much! We will definitely merge this when you are ready :)

[nedtwigg]

Run spotlessApply and commit so that the CI passes. Then update all three CHANGES.md , and also the README.md for plugin-maven and plugin-gradle.

[abelk2]

Run spotlessApply and commit so that the CI passes. Then update all three CHANGES.md , and also the README.md for plugin-maven and plugin-gradle.

Sure. Almost done, I also added a test case for it.
Let me add the README updates too and it's finished. :)

[nedtwigg]

This looks great and I think it's ready to merge! Do you agree that it's ready to merge @abelk2?

[abelk2]

This looks great and I think it's ready to merge! Do you agree that it's ready to merge @abelk2?

Yes, everything's ready :)

[anantdamle]

when following configuration with spotless 6.18.0

format "licenseHeaderSh", {
  target "**/*.sh"
  licenseHeader(licenseWithHash, "^(?!##).+")
    .skipLinesMatching("^#!.+?\$")
}

Results in

Skipping '/path/to/shell/script.sh' because it does not converge.

File sample:

#!/bin/bash

# Fail on any error.
set -e

# Display commands being run.
# WARNING: please only enable 'set -x' if necessary for debugging, and be very
#  careful if you handle credentials
set -x

# Code under repo is checked out to
cd my-dir

# build all of them, concurrency is unlimited, sync output
./gradlew clean test build

[abelk2]

@anantdamle Two things would help us to advise you more easily:

• The contents of the licenseWithHash variable
• The output of the spotlessDiagnose task (few of the files it outputs)

[nedtwigg]

I'm pretty sure what's happening is this:

{file}

license header
{file}

license header
license header
{file}

license header
license header
license header
{file}

etc, and that's why it's not converging. If you'd like more help, please open an issue.

[anantdamle]

Thanks folks as requested by @abelk2 contents of licenseWithHash

#
# Copyright 2023 My Awesome Company
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#

the output from Diagnose is different than @nedtwigg

license header

license header
...

{file}

[abelk2]

I think I see what causes the issue. First of all, Spotless has to tell somehow which line is the first one after the license header, i.e. where is the end of the license header if it's already in the file. A regex is used for this purpose, which has to match the first line that is not part of the license header.

I think you're using the one from the example ("^(?!##).+") which translates to "a line that does not start with double # symbols". Since your license header does not start with ##, but with a single # symbol, the header itself will match the regex. Because of this, the header is not replaced, but duplicated with each step, causing the divergence.

I'd recommend either:

• Using ## prefix for the license header - preferred, this helps Spotless distinguish license headers from ordinary comments, or
• Modifying the regex to "^(?!#).+" - however, please note that this will not match ordinary comments either, so comments immediately after the license header will be replaced by the header too