NAME

Dist::Conformance::Check::CriticProfile - The perlcritic profile enables or turns off every policy of its template, and no retired one

VERSION

version 0.006

DESCRIPTION

A profile is compared with its template by the policies that each names. Both are read as Perl::Critic reads a profile, with Config::Tiny: each section [Name] enables the policy Name, a section [-Name] turns it off, and the keys before the first section are global settings. A name with the prefix Perl::Critic::Policy:: is the same policy as the name without it.

The check passes when the file names each policy that the template enables, either as [Name], which enables it, or as [-Name], which turns it off on purpose. It fails when the file is missing, when it does not parse, and when it does not name a policy that the template enables. The detail names each such policy. So when the template gains a policy, every profile that does not have it yet fails, by the name of that policy.

It also fails when the file enables a policy that retired names, and the detail names each such policy and says that conformance update removes it. Dropping a policy from the template is not enough to take it away, because a profile may enable policies of its own, and the check cannot tell one of them from a policy that the standards used to have. So the standards say which policies they take back, by name. A section [-Name], which turns a retired policy off, is not an error, and stays.

What else the file says is the distribution's own business, and does not change the result:

the parameters of a policy

A policy that the template configures, and the file configures differently or not at all, is there. An exemption or a threshold of its own is a choice of the distribution, not a policy that it lacks.

a policy that the template does not enable

A policy of the distribution's own, or one that the template has dropped or turns off, can stay, unless retired names it.

the global settings and the comments

The first line among them, so a header says nothing about whether a profile is current.

The update writes the template when the file is missing. A profile that is there usually has changes of its own, such as exemptions, so it is replaced only when replace is true. Otherwise the update appends to the end of the file each policy that it lacks, as the template writes its section: the [Name] line and the parameters below it, without the comments. Every line that the file had stays as it was. A profile that does not parse is left for a person, and so is one whose template still has a placeholder that nothing fills.

Without replace, the update also removes the section of each retired policy that the file enables: the [Name] line, the parameters below it, and the comment lines directly above the [Name] line, up to a line that is blank or is not a comment. A comment block at the very top of the file is its header, and stays. The comment lines and blank lines at the end of the section stay as well, because they are usually about the section after it. Every other line stays as it was.

A template that enables a policy that retired names contradicts itself, so the check dies, and so does the update, and each says which policy.

METHODS

missing_policies

($text). The sorted names of the policies that the template enables and the profile $text does not name. Dies when either does not parse.

retired

The short names of the policies that retired names, in its order. Dies when the template enables one of them, or does not parse.

enabled_retired

($text, @retired). The sorted names of the policies of @retired that the profile $text enables. Dies when it does not parse.

verdict

($text). The status and the detail of the profile $text, as check returns them. For a profile that does not parse, then what a person must do to fix it by hand; for one that lacks policies or enables retired ones, then undef and two array references: the names of the policies that it lacks, and of the retired policies that it enables. Dies when the template enables a retired policy, as "retired" does.

check

($snapshot). The status and the detail that "DESCRIPTION" says, for the profile in $snapshot.

update

Writes the template when the profile is missing, or when it is not current and replace is true. Otherwise removes the sections of the retired policies that the profile enables, and appends the sections of the template that it lacks, as "DESCRIPTION" says.

append_policies

($update, $text, @missing). The profile $text with the section of the template of each policy of @missing appended. When the template still has a placeholder, returns undef and records through $update what is needed.

FUNCTIONS

policies

($text, $where). The policies of the profile $text, as a hash reference from the short name of each to enabled or disabled. Dies, naming $where, when Perl::Critic could not parse the text either.

policy_of

($section). Whether the header $section of a profile turns its policy off, and the short name of the policy.

lacks

(@missing). The detail for a profile that lacks the policies @missing, without the template.

header_of

($line). The section that the line $line of a profile starts, as Config::Tiny reads it, with its inline ; comment: undef when it starts none.

ignored

($line). Whether Config::Tiny ignores the line $line of a profile, as a comment or a blank line.

sections

($text). The text of each section of the profile $text that enables a policy, as a hash reference from the short name of the policy: the line of the section and the lines of its parameters, each with its newline, without the comments and the blank lines. The lines are found as Config::Tiny finds them, so the names are the names of "policies".

without_sections

($text, @names). The profile $text without each section that enables a policy of @names, as "DESCRIPTION" says: the line of the section, its parameters, and the comment lines directly above it unless they start the file, but not the comment lines and blank lines that end it. A section that turns a policy off stays.

IN A FLAVOR

checks:
  CriticProfile:
    file: .perlcriticrc
    template: templates/perlcriticrc
    replace: false
    retired:
      - Subroutines::ProhibitUnderscorePrivateSubs

CONFIGURATION

file

Required. The path of the profile.

template

Required. The template of the current profile.

replace

Whether an update overwrites a profile that is not current. Default false.

retired

The policies that the standards have taken back, by name, with or without the prefix Perl::Critic::Policy::. A profile must not enable one, and the update removes it. Default none. Name a policy here when the template drops it, and keep it here for as long as a profile made from an older template can still enable it.

outdated

Deprecated, and ignored. Each named a first line to compare, which the check no longer does. They are accepted so that a flavor that names them still loads.

SEE ALSO

Please see those modules/websites for more information related to this module.

BUGS

Please report any bugs or feature requests on the bugtracker website https://github.com/Troglodyne-Internet-Widgets/Dist-Conformance/issues

When submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature.

AUTHORS

Current Maintainers:

  • George S. Baugh <george@troglodyne.net>

COPYRIGHT AND LICENSE

Copyright (c) 2026 Troglodyne LLC

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.