#!/usr/bin/perl

=head1 NAME

dh_assistant - tool for supporting debhelper tools and provide introspection

=cut

use v5.28;
use warnings;
use constant EXIT_CODE_LINT_ISSUES_FOUND => 2;
use Debian::Debhelper::Dh_Lib;
use JSON::PP ();

=head1 SYNOPSIS

B<dh_assistant> B<I<command>> [S<I<additional options>>]

=head1 DESCRIPTION

B<dh_assistant> is a debhelper program that provides introspection into the
debhelper stack to assist third-party tools (e.g. linters) or third-party
debhelper implementations not using the debhelper script API (e.g., because
they are not written in Perl).

=head1 COMMANDS

The B<dh_assistant> supports the following commands:

=head2 active-compat-level (AJSON)

B<Synopsis>: B<dh_assistant> B<active-compat-level>

Outputs information about which compat level the package is using.

For packages without valid debhelper compatibility information (whether missing, ambiguous,
not supported or simply invalid), this command operates on a "best effort" basis and may abort
when error instead of providing data.

The returned JSON dictionary contains the following key-value pairs:

=over 4

=item active-compat-level

The compat level that debhelper will be using.  This is the same as B<DH_COMPAT> when present
or else B<declared-compat-level>.  This can be B<null> when no compat level can be detected.

=item declared-compat-level

The compat level that the package declared as its default compat level.  This can be B<null>
if the package does not declare any compat level at all.

=item declared-compat-level-source

Defines how the compat level was declared.  This is null (for the same reason as
B<declared-compat-level>) or one of:

=over 4

=item debian/compat

The compatibility level was declared in the single line F<debian/compat> file.

=item X-DH-Compat: <C>

The compatibility was declared in the F<debian/control> via a the B<X-DH-Compat>
field. In the output, the B<C> is replaced by the actual compatibility level.
A full example value would be:

   X-DH-Compat: 15

=item Build-Depends: debhelper-compat (= <C>)

The compatibility was declared in the F<debian/control> via a build dependency on the
B<< debhelper-compat (= <C>) >> package in the B<Build-Depends> field.  In the output,
the B<C> is replaced by the actual compatibility level.  A full example value would be:

   Build-Depends: debhelper-compat (= 15)

=back

=back

=head2 supported-compat-levels (AJSON, CRFA)

B<Synopsis>: B<dh_assistant> B<supported-compat-levels>

Outputs information about which compat levels, this build of debhelper knows
about.

This command accepts no options or arguments.

=head2 which-build-system (AJSON)

B<Synopsis>: B<dh_assistant> B<which-build-system> [S<I<build step>>] [S<I<build system options>>]

Output information about which build system would be used for a particular build step.  The build step
must be one of B<configure>, B<build>, B<test>, B<install> or B<clean> and must be the first argument
after B<which-build-system> when provided.  If omitted, it defaults to B<configure> as it is the
most reliable step to use auto-detection on in a clean source directory.  Note that build steps do not
always agree when using auto-detection - particularly if the B<configure> step has not been run.

Additionally, the B<clean> step can also provide "surprising" results for builds that rely on
a separate build directory.  In such cases, debhelper will return the first build system that
uses a separate build directory rather than the one build system that B<configure> would detect.
This is generally a cosmetic issue as both build systems are all basically a glorified
B<rm -fr builddir> and more precise detection is functionally irrelevant as far as debhelper is
concerned.

The option accepts all debhelper build system arguments - i.e., options you can pass to all of
the B<dh_auto_*> commands plus (for the B<install> step) the B<--destdir> option.  These options
affect the output and auto-detection in various ways.  Passing B<-S> or B<--buildsystem>
overrides the auto-detection (as it does for B<dh_auto_*>) but it still provides introspection
into the chosen build system.

Things that are useful to know about the output:

=over 4

=item *

The key B<build-system> is the build system that would be used by debhelper for the given
step (with the given options, debhelper compat level, environment variables and the given
working directory).  When B<-S> and B<--buildsystem> are omitted, this is the result of
debhelper's auto-detection logic.

The value is valid as a parameter for the B<--buildsystem> option.

The special value B<"none"> is used to denote that no build system would be used (that is,
a JSON I<string>).  This value is not present in B<--list> parameter for the B<dh_auto_*>
commands, but since debhelper/12.9 the value is accepted for the B<--buildsystem> option.


Note that auto-detection is subject to limitations in regards to third-party build systems.
While debhelper I<does> support auto-detecting some third-party build systems, they must be
installed for the detection to work.  If they are not installed, the detection logic silently
skips that build system (often resulting in B<build-system> being B<"none"> in the output).

=item *

The B<build-directory> and B<buildpath> values serve different but related purposes.  The
B<build-directory> generally mirrors the B<--builddirectory> option where as B<buildpath>
is the output directory that debhelper will use.  Therefore the former will often be null
when B<--builddirectory> has not been passed while the latter will generally not be null
(except when B<build-system> is B<none>).

=item *

The B<dest-directory> (B<--destdir>) is undefined for all build steps except the B<install> build
step (will be output as null or absent).  For the same reason, B<--destdir> should only be
passed for B<install> build step.

Note that if not specified, this value is currently null by default.

=item *

The B<parallel> value is subject to B<DEB_BUILD_OPTIONS>.  Notably, if that does not include
the B<parallel> keyword, then B<parallel> field in the output will always be 1.

=item *

Most fields in the output I<can> be null.  Particular if there is no build system is detected
(or when B<--buildsystem=none>).  Additionally, many of the fields can be null even if there
is a build system if the build system does not use/set/define that variable.

=back

=head2 detect-hook-targets (EXEC, AJSON)

B<Synopsis>: B<dh_assistant> B<detect-hook-targets>

Detects possible override targets and hook targets that L<dh(1)> might use (provided that the
relevant command is in the sequence).

**UNSAFE**: This command relies on the output of L<make>. Even it its dry-run mode, B<make> may
execute commands from F<debian/rules>. Avoid using on packages from untrusted sources, where you
have not reviewed the packaging for backdoors.

The detection is based on scanning the rules file for any target that I<might look> like a hook
target and can therefore list targets that are in fact not hook targets (or are but will never
be triggered for other reasons).

The detection uses a similar logic for scanning the rules file and is therefore subject to
makefile conditionals (i.e., the truth value of makefile conditionals can change whether a hook
target is visible in the output of this command).  In theory, you would have to setup up the
environment to look like it would during a build for getting the most accurate output.  Though,
a lot of packages will not have conditional hook targets, so the "out of the box" behaviour
will work well in most cases.

The output looks something like this:

    {
       "commands-not-in-path": [
          "dh_foo"
       ],
       "hook-targets": [
          {
             "command": "dh_strip_nondeterminism",
             "is-empty": true,
             "package-section-param": null,
             "filename": "debian/rules",
             "target-name": "override_dh_strip_nondeterminism"
          },
          {
             "command": "dh_foo",
             "is-empty": false,
             "package-section-param": "-a",
             "filename": "debian/rules",
             "target-name": "override_dh_foo-arch"
          }
       ]
    }

In more details:

=over 4

=item commands-not-in-path

This attribute lists all the commands related to hook targets, which B<dh_assistant> could B<not>
find in PATH.  These are usually caused by either the command not being installed on the system
where B<dh_assistant> is run or by the command not existing at all.

If you are using this command to verify an hook target is present, please double check that the
command is spelled correctly.

=item hook-targets

List over hook targets found along with additional information about them.

=over 4

=item command

Attribute that lists which command this hook target is related too.

=item target-name

The actual target name detected in the F<debian/rules> file.

=item is-empty

A boolean that determines whether L<dh(1)> will optimize the hook out at runtime (see "Completely empty targets" in
L<dh(1)>). Note that empty override targets will still cause L<dh(1)>  to skip the original command.

=item package-section-param

This attribute defines what package selection parameter should be passed to B<dh_*> commands used
in the hook target.  It can either be B<-a>, B<-i> or (if no parameter should be used) C<null>.

=item filename

This attribute reports which file the target was found it. In most cases, this will always be "debian/rules"
though in case of include files, the target could appear in an include file.  Note this attribute is not
super reliable as L<make(1)> only reports it for targets with a "recipe" (targets with commands inside
them). When B<make> does not provide the filename, B<dh_assistant> blindly assumes the filename is
"debian/rules" (as overrides via includes is not a commonly used feature).

Note this accuracy of this attribute is limited about what data B<dh_assistant> can read out from the
following command:

    LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null

=back

=back

This command accepts no options or arguments.


=head2 detect-unknown-hook-targets (EXEC, AJSON, LINT)

B<Synopsis>: B<dh_assistant> B<detect-unknown-hook-targets> [--output-format=json] [command-options]

Detects unknown and possibly misspelled override targets and hook targets in F<debian/rules> that
will most likely not be used by L<dh(1)>.

**UNSAFE**: This command relies on the output of L<make>. Even it its dry-run mode, B<make> may
execute commands from F<debian/rules>. Avoid using on packages from untrusted sources, where you
have not reviewed the packaging for backdoors.

This command differs from B<detect-hook-targets> subtly in the scope. The B<detect-hook-targets>
will list all targets that looks like hook targets whether they are applicable or not. This
command show all hook targets, for which a command cannot be found in any sequence. Accordingly,
this command is better for linting purposes whereas B<detect-hook-targets> is better if you want
to know which hook targets are present. All the limitations listed in B<detect-hook-targets>
about scanning the rules file apply equally to this command.

This command will attempt will attempt to load any sequence add-on listed via build-dependencies
and therefore these must be installed. Additional modules can be passed via B<--with> like with
L<dh(1)> as needed.

This command will also need one of the following perl modules to be available:
L<Text::Levenshtein>, L<Text::LevenshteinXS>, L<Text::Levenshtein::XS>. The first one can be
installed via B<apt install libtext-levenshtein-perl>.

The text output is intended for human consumption and should be self-explanatory.  Since it is
not stable, it will not be documented. The JSON output looks something like this:

    {
       "unknown-hook-targets": [
          {
             "target-name": "execute_before_dh_instlal",
             "filename": "debian/rules",
             "candidates": [
                "execute_before_dh_install"
             ]
          }
       ],
      "hook-targets-for-disabled-commands": [
          {
             "filename": "debian/rules",
             "target-name": "override_dh_builddeb",
             "removed-by": "zz-debputy"
          }
       ],

    }

In more details:

=over 4

=item unknown-hook-targets

List of all the unknown hook targets found along with additional information about them.

=over 4

=item target-name

The actual target name detected in the file (usually F<debian/rules>).

=item filename

This attribute reports which file the target was found it. In most cases, this will always be "debian/rules"
though in case of include files, the target could appear in an include file.  Note this attribute is not
super reliable as L<make(1)> only reports it for targets with a "recipe" (targets with commands inside
them). When B<make> does not provide the filename, B<dh_assistant> blindly assumes the filename is
"debian/rules" (as overrides via includes is not a commonly used feature).

Note this accuracy of this attribute is limited about what data B<dh_assistant> can read out from the
following command:

    LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null

=item candidates

When not null and not empty, each element in this list are names for likely candidates for the
"correct" name of this target.

=back

=item hook-targets-for-disabled-commands

List of known hook targets found related to disabled commands along with additional information about them.

=over 4

=item target-name

The actual target name detected in the file (usually F<debian/rules>).

=item filename

This attribute reports which file the target was found it. In most cases, this will always be "debian/rules"
though in case of include files, the target could appear in an include file.  Note this attribute is not
super reliable as L<make(1)> only reports it for targets with a "recipe" (targets with commands inside
them). When B<make> does not provide the filename, B<dh_assistant> blindly assumes the filename is
"debian/rules" (as overrides via includes is not a commonly used feature).

Note this accuracy of this attribute is limited about what data B<dh_assistant> can read out from the
following command:

    LC_ALL=C make -Rrnpsf debian/rules debhelper-fail-me 2>/dev/null

=item removed-by

If present, this denotes the B<dh> add-on that removed the command from the sequence (thereby disabling
this command for that package).

Note this field is not present in all cases. As an example, as obsolete commands (such as B<dh_gconf>) are
not part of any sequence by the time they are marked as obsolete.

If you (as a consumer) need to know whether a command is obsolete or the particular reason why a command
was disabled, please file a feature request to get that data. The absence of B<removed-by> is not
guaranteed to imply the command is obsolete.

=back

=item issues

If present, then it is a list of one or more reasons why this output is definitely incomplete. Each element
in the list is an object with the following keys:

=over 4

=item issue

A key defining the issue. Currently, it is always B<load-addon>, which signals that B<dh_assistant> could
not load the add-on listed in the B<addon> key.

Parsers should assume new issue types may appear in the future.

=item addon

If present, it defines the name of a B<dh> sequence add-on that is related to the failure.

=back

=back

This command accepts the following options:

=over 4

=item B<--output-format=>I<FORMAT>

Request a certain type of output format. Valid values are B<text> or B<json>.

The text format is intended for human consumption and may change between versions without any
regard for machine consumption. If you want to use this command for machine consumption, please
use the JSON format.

=item B<--no-linter-exit-code>, B<--linter-exit-code>

These options control whether the command should exit with the linter exit code (2) or not (0)
when an unknown target is found. By default, it uses the linter exit code when an unknown target
is found.

=item B<--with> I<addon>, B<--without> I<addon>

These options behave the same as the L<dh(1)> options with the same name.

=back

=head2 list-commands (RJSON)

B<Synopsis>: B<dh_assistant> B<list-commands> [--output-format=json] [command-options]

Load all B<dh> sequence add-ons and extract a full list of all commands that will be invoked across
all sequences. The command makes no attempt to filter out commands that will not be run due to
override targets or due to certain sequences not being run (by B<dh> or at all).

As the command will attempt to load all plugins, they must be installed.

The text output is intended for human consumption and should be self-explanatory.  Since it is
not stable, it will not be documented. The JSON output looks something like this:

    {
       "commands": [
          {
             "command": "dh_auto_build"
          },
          {
             "command": "dh_auto_clean"
          },
          [... more commands listed here... ]
       ],
       "removed-commands": [
           {
             "command": "dh_gconf"
          },
       ]
       "issues": [
            {
                "issue": "load-addon",
                "addon": "foo"
            }
       ]
    }

=over 4

=item commands

The top level key containing the list of all commands. Each element in the list are an object and
can have the following keys:

=over 4

=item command

The name of the command.

While most commands are resolved via PATH, a sequence add-on could register a command via a full path
(by passing the path search). If so, the command provided in this output will also use the full path.

=back

=item disabled-commands

The top level key containing the list of all known commands that have been disabled. Each element in
the list are an object and can have the following keys:

=over 4

=item command

The name of the command.

While most commands are resolved via PATH, a sequence add-on could register a command via a full path
(by passing the path search). If so, the command provided in this output will also use the full path.

=item removed-by

If present, this denotes the B<dh> add-on that removed the command from the sequence (thereby disabling
this command for that package).

Note this field is not present in all cases. As an example, as obsolete commands (such as B<dh_gconf>) are
not part of any sequence by the time they are marked as obsolete.

If you (as a consumer) need to know whether a command is obsolete or the particular reason why a command
was disabled, please file a feature request to get that data. The absence of B<removed-by> is not
guaranteed to imply the command is obsolete.

=back

=item issues

If present, then it is a list of one or more reasons why this output is definitely incomplete. Each element
in the list is an object with the following keys:

=over 4

=item issue

A key defining the issue. Currently, it is always B<load-addon>, which signals that B<dh_assistant> could
not load the add-on listed in the B<addon> key.

Parsers should assume new issue types may appear in the future.

=item addon

If present, it defines the name of a B<dh> sequence add-on that is related to the failure.

=back

=back

This command accepts the following options:

=over 4

=item B<--output-format=>I<FORMAT>

Request a certain type of output format. Valid values are B<text> or B<json>.

The text format is intended for human consumption and may change between versions without any
regard for machine consumption. If you want to use this command for machine consumption, please
use the JSON format.

=item B<--with> I<addon>, B<--without> I<addon>

These options behave the same as the L<dh(1)> options with the same name.

=back

=head2 list-guessed-dh-config-files (AJSON)

B<Synopsis>: B<dh_assistant> B<list-guessed-dh-config-files> [command-options]

Load all B<dh> sequence add-ons declaratively depended on, determine the full list of
commands could be relevant for this source package and for each command used, then
attempt to I<guess> which "config files" these commands are interested in.

The command will include config files for commands that are not active with current add-ons,
since the commands might be run manually from hook targets.

Note this command only guesses "per command config files". Standard global config files
such as F<debian/control>, F<debian/rules>, and F<debian/compat> are not included in this
output.

As the command name implies, the resulting output is not a full list (and will never be).
The B<dh_assistant> tool have to derive this from optional metadata that commands can
choose to provide and B<dh_assistant> has no means to validate that this metadata is up
to date.

As the command will attempt to load all plugins referenced by the package, they must
be installed.

The text output is intended for human consumption and should be self-explanatory.  Since it is
not stable, it will not be documented. The JSON output looks something like this:

    {
       "config-files": [
          {
             "commands": [
                {
                   "command": "dh_autoreconf_clean"
                   "is-active": true
                }
             ],
             "file-type": "pkgfile",
             "pkgfile": "autoreconf.before"
          },
          {
             "commands": [
                {
                   "command": "dh_installgsettings"
                   "is-active": true
                }
             ],
             "file-type": "pkgfile",
             "pkgfile": "gsettings-override"
          },
          # [ ... more entries here ...]
       ],
       "issues": [
           {
                "issue": "load-addon",
                "addon": "foo"
           }
       ]
    }


=over 4

=item config-files

The top level key containing the list of all config-files. Each element in the list are an object and
can have the following keys:

=over 4

=item file-type

The type of config file detected. At the time of writing, this will either be B<pkgfile> or B<path>. However,
other values may appear in the future.

When it is B<pkgfile>, then the config file is a B<debhelper pkgfile> (named after the B<pkgfile> sub
in L<Debian::Debhelper::Dh_Lib> that locates the file). The value denoted by the B<pkgfile> key will
be the I<stem> of the B<pkgfile> (the I<install> in B<< debian/package. I<install> >>).

=item pkgfile

When B<file-type> is B<pkgfile>, this key defines the name stem of the B<pkgfile>. An example, this will
be B<install> for L<dh_install(1)>'s config file and B<docs> for L<dh_installdocs(1)>'s config file.

When B<file-type> is B<not> B<pkgfile>, then this key will be absent.

Typically names for these files are:

     debian/PKGFILE
     debian/PACKAGE.PKGFILE

However, there are more variants caused by B<--name> plus architecture specific suffixes.

=item path

When B<file-type> is B<path>, this key defines the static path of the configuration. An example,
this will be B<debian/clean> for L<dh_clean(1)>'s config file and B<debian/not-installed> for
L<dh_missing(1)>.

When B<file-type> is B<not> B<path>, then this key will be absent.

=item internal

This key may exist and any value for it is not standardized. Use at own peril.

It used for document certain specific implementation details such as bug compatibility and may change
as the situation changes.

=item commands

This key will be a list with each element in it being an object with the following keys:

=over 4

=item command

Name of the command that is interested in this config file. Multiple commands can be interested in the same
config file. An example of this would be B<dh_installinit>, B<dh_installsystemd> and B<dh_installtmpfiles>,
which all reacts to (the now) deprecated B<tmpfile> pkgfile. In the particular case, only one command reacts
to the file for a given compat level (but that information is not available to B<dh_assistant> and therefore
is not available in this output either).

=item is-active

A boolean that determines whether the command is active with the loaded sequences. When false, the command
is known to debhelper, but it is not run automatically via B<dh>. The command might be explicitly removed
by a sequence, marked as obsolete or possibly known to debhelper a command that would activate in a different
command level (than the one currently active).

Note that commands that are not "active" can often still be invoked manually from F<debian/rules> via hook
targets. Therefore, this reflects whether B<dh> would call the command directly or provide its standard
hook targets for the command.

=item removed-by

If present, this denotes the B<dh> add-on that removed the command from the sequence (thereby disabling
this command for that package).

Note this field is not present in all cases regardless of the value of B<is-active>. As an example, as obsolete
commands (such as B<dh_gconf>) are not part of any sequence by the time they are marked as obsolete.

If you (as a consumer) need to know whether a command is obsolete or the particular reason why a command
was disabled, please file a feature request to get that data. The absence of B<removed-by> plus
B<is-active> being false is not guaranteed to imply the command is obsolete.

=back

=back

=item issues

If present, then it is a list of one or more reasons why this output is definitely incomplete. Each element
in the list is an object with the following keys:

=over 4

=item issue

A key defining the issue. Currently, it is always B<load-addon>, which signals that B<dh_assistant> could
not load the add-on listed in the B<addon> key.

Parsers should assume new issue types may appear in the future.

=item addon

If present, it defines the name of a B<dh> sequence add-on that is related to the failure.

=back

=back

This command accepts the following options:

=over 4

=item B<--with> I<addon>, B<--without> I<addon>

These options behave the same as the L<dh(1)> options with the same name.

=back

=head2 log-installed-files (BLD)

B<Synopsis>: B<dh_assistant> B<log-installed-files> B<< -pI<pkg> >> I<[--on-behalf-of-cmd=dh_foo]> B<path ...>

Mark one or more paths as installed for a given package.  This is useful for telling L<dh_missing(1)> that the
paths have been installed manually.

The B<--on-behalf-of-cmd> option can be used by third-party tools to have B<dh_assistant> list them as the
installer of the provided paths.  The convention is to use the basename of the tool itself as its name
(e.g. B<dh_install>).

Please keep in mind that:

=over 4

=item *

B<No> glob or substitution expansion is done by B<dh_assistant> on the provided paths.  If you want to use globs,
have the shell perform the expansion first.

=item *

Paths must be given as relative to the source root directory (e.g., F<debian/tmp/...>)

=item *

You I<can> provide a directory.  If you do, the directory and anything recursively below it will be considered
as installed.  Note that it is fine to provide the directory even if paths inside of it has been excluded as long
as the directory is fully "covered".

=item *

Do not worry about providing the same filename twice in different invocations to B<dh_assistant> due to B<-arch> /
B<-indep> overrides.  While it will be recorded multiple internally, L<dh_missing(1)> will deduplicate when it
parses the records.

=back

Note this command only I<marks> paths as installed. It does not actually install them - the caller should ensure
that the paths are in fact handled (or installed).

=head2 restore-file-on-clean (BLD)

B<Synopsis>: B<dh_assistant> B<restore-file-on-clean> B<FILE ...>

This command will take a backup of listed files and tell L<dh_clean(1)> to restore them when it runs.

Note that generally you do not need to restore modified files on clean. Often you can get away with just
removing them if they are regenerated anyway (which is the most common case for files being modified during
builds).  Use this command when something taints a file and the build does not cope with the file being
removed.

The file is stored in B<debian/.debhelper>. If you remove this directory manually without calling
L<dh_clean(1)> then your B<dh_assistant> provided backup is gone permanently and the restore will never
occur. At this point, only a version control system or another backup can restore the files.

The command has the following limitations:

=over 4

=item No thread-safety - concurrency will corrupt the restore

The command relies on updating an internal index and concurrent writes will cause it to be corrupt.

While most B<dh_*> commands does not use the underlying function, any of them could do so. Avoid running
another B<dh_*> command while B<dh_assistant> processes this command (especially running multiple concurrent
instances of B<dh_assistant restore-file-on-clean> is asking for corruption!).

=item Files only, not directories nor symlinks to files

This command will only restore files; not directories or symlinks to files. It will reject any non-files.

Additionally, if the directory containing the file is removed, the restore will fail (as B<debhelper>
does not track the directory, it cannot restore it reliably). If this happens, you can do a B<mkdir>
to restore the directory and run L<dh_clean(1)> again to get the files back. After that, consider
what went wrong and whether you are using the correct tool(s).

=item Strict file names

All filenames must be relative to the package root (without using the B<./> prefix). No hidden files (that
is any file starting with a period B<.>) and no version control directories (such as B<CVS>). The checks
are best effort.

These checks are here to ensure you do not accidentally trash important data that would help you undo
mistakes.

=item Heavy duty

The command takes a B<full copy> of all files you pass it. This is fine for a handful of small files,
which is the intended use-case. If you find yourself passing 10+ files or very large files, you might
be applying a sledgehammer where you needed a different tool.

=back

=head2 compat-upgrade-checklist (EXEC)

B<Synopsis>: B<dh_assistant> B<compat-upgrade-checklist> [B<--target-compat> I<N>]

This command generates a compat upgrade checklist for the current package.

The upgrade checklist is intended as an aid for contributors that upgrade a package to a newer
compat level. Where possible, B<dh_assistant> will attempt to detect whether some of the items
are likely to be irrelevant and mark them as such. The logic will in many cases be a heuristic
that can have false-positives and false-negatives.

The output is a markdown based checklist template aimed at being human-readable (output stability
is not a goal). Typically, the user will want to direct standard output and then edit the checklist
as they process to a file a la:

    dh_assistant compat-upgrade-checklist > debian/compat-upgrade-checklist.md
    editor debian/compat-upgrade-checklist.md
    # Iterate through the checklist, tweak the packaging, cross off items from the checklist (rinse and repeat)
    # Finally, remove the checklist.
    rm -f debian/compat-upgrade-checklist.md  # when the migration is complete

The command will provide a checklist up to latest stable compat level or the compat level provided
via the B<--target-compat> option.

This command accepts the following options:

=over 4

=item B<--target-compat> I<N>

Request the upgrade checklist to stop at the provided compat level rather than the highest stable compat
level. This option can be used to limit the checklist to a given compat level or request checklists
for experimental compat levels.

The option I<cannot> be used to generate a checklist for downgrading to a previous compat level. Trying
to do so will result in an error message.

=back

Note: If you run this command from a git checkout of B<debhelper>, the behavior is slight different, since
it will not correctly track which compat levels are stable (it is a build-time inserted property). As such,
you will see experimental compat levels in the checklists by default, and they will B<not> be marked as such.
If you use the git checkout, it falls on you to be extra careful with these limitations of the generated
checklist.

=head2 supports (CFFA)

B<Synopsis>: B<dh_assistant> B<supports> B<COMMAND>

This command is a scripting aid to programmatically determine whether B<dh_assistant> knows about a given
subcommand. Pass the name of a subcommand and this command will exit successfully if the subcommand was known
and unsuccessfully otherwise.

=head1 COMMAND TAGS

Most commands have one or more of the following "tags" associated with them.  Their
meaning is defined here.

=over 4

=item EXEC

This command will or may execute content from the package. Do not run on untrusted packages.

Note: This tag only applies if the command will I<out of the box> be unsafe. As an example, commands that
parse the output of B<make> is inherently unsafe, because it is trivial B<make> to have B<make> run
code even in B<--dry-run> mode. As a counter example, commands that only loads B<dh> add-ons will be
considered safe, because B<PERL5LIB> is assumed to be curated to only include trusted plugins.

=item AJSON

The command always provides JSON output. See L</JSON OUTPUT> for details.

=item OJSON

The command *can* provide JSON output via B<--output-format=json>, but does not
do so by default. See L</JSON OUTPUT> for details when using B<--output-format=json>.

=item LINT

The command is or can be used for linting purposes. This command will exit with code 2 when an important
issue is found. B<Be careful> if the command is also tagged with B<EXEC>. When this happens, the
command should only be used on trusted content (see the B<EXEC> tag for details).

Note that commands may have options that redefine what is considered an "important" issue.

=item CRFA

I<Mnemonic "Can be Run From Anywhere">

Most commands must be run inside a source package root directory (a directory
containing F<debian/control>) because debhelper will need the package metadata
to lookup the information.  Any command with this tag are exempt from this
requirement and is expected to work regardless of where they are run.

=item BLD

The command is intended to be used as a part of a package build. It may leave
artifacts behind that will need a L<dh_clean(1)> invocation to remove.

=back

=head1 JSON OUTPUT

Most commands uses JSON format as output.  Consumers need to be aware that:

=over 4

=item *

Additional keys may be added at any time.  For backwards compatibility, the absence
of a key should in general be interpreted as null unless another default is documented
or would be "obvious" for that case.

=item *

Many keys can be null/undefined in special cases.  As an example, some information may
be unavailable when this command is run directly from the debhelper source (git repository).

=back

The output will be prettified when stdout is detected as a terminal.  If
you need to pipe the output to a pager/file (etc.) and still want it
prettified, please use an external JSON formatter. An example of this:

     dh_assistant supported-compat-levels | json_pp | less

=cut

my $JSON_ENCODER = JSON::PP->new->utf8;

# Prettify if we think the user is reading this.
$JSON_ENCODER = $JSON_ENCODER->pretty->space_before(0)->canonical if -t STDOUT;

# We never use the log file for this tool
inhibit_log();
$Debian::Debhelper::Dh_Lib::PARSE_DH_SEQUENCE_INFO = 1;
# Force commands to opt-in
$Debian::Debhelper::Dh_Lib::ALLOW_UNSAFE_EXECUTION = 0;


my %COMMANDS = (
	'help'                         => \&_do_help,
	'-h'                           => \&_do_help,
	'--help'                       => \&_do_help,
	'active-compat-level'          => \&active_compat_level,
	'supported-compat-levels'      => \&supported_compat_levels,
	'which-build-system'           => \&which_build_system,
	'detect-hook-targets'          => \&detect_hook_targets,
	'detect-unknown-hook-targets'  => \&detect_unknown_hook_targets,
	'list-commands'                => \&list_commands,
	'list-guessed-dh-config-files' => \&list_guessed_dh_config_files,
	'log-installed-files'          => \&log_installed_files_cmd,
	'restore-file-on-clean'        => \&dh_assistant_restore_file_on_clean,
	'compat-upgrade-checklist'     => \&compat_upgrade_checklist,
    'supports'                     => \&supports,
);

my ($COMMAND) = shift(@ARGV);
for my $arg (@ARGV) {
    if ($arg eq '--help' or $arg eq '-h') {
        $COMMAND = 'help';
        last;
    }
}


sub _do_help {
    my $me = basename($0);
    print <<"EOF";
${me}: Tool for supporting debhelper tools and provide introspection

Usage: ${me} <command> [... addition arguments or options ...]

The following commands are available:
  help                       Show this help
  compat-upgrade-checklist   Provide an compat upgrade checklist for the current package (EXEC)
  active-compat-level        Output information about which compat level is declared/active (AJSON)
  supported-compat-levels    Output information about supported compat levels (AJSON, CRFA)
  which-build-system         Determine which build system will be used (AJSON)
  detect-hook-targets        Detect and output possible override and hook targets (EXEC, AJSON)
  detect-unknown-hook-targets
                             Detect unknown / typos of known hook targets (EXEC, LINT, RJSON)
  list-commands              List all commands across all sequences (RJSON)
  list-guessed-dh-config-files
                             List guessed "config files" for debhelper commands (AJSON)
  log-installed-files        Mark one or more paths as "installed" so dh_missing is aware (BLD)
  restore-file-on-clean      Mark one or more files as to be restored by dh_clean (BLD)
  supports                   Script aid: Test whether dh_assistant knows a particular command (CRFA)

Command tags:

 * EXEC    *UNSAFE*: The command may execute code from the package. Do not use on unsafe content.
 * AJSON   The command always provides JSON output.
 * RJSON   The command *can* provide JSON output via --output-format=json.
 * LINT    The command is or can be used for linting purposes. This command will exit with code 2
           when an important issue is found. Be careful when using commands also tagged EXEC!
 * CRFA    Command does not need to be run from a package source directory
           (Mnemonic "Can be Run From Anywhere")
 * BLD     The command is intended to be used as a part of a package build.
           It may leave artifacts behind that will need a dh_clean invocation to remove.


Its primary purpose is to provide support for third-party debhelper implementations
not using the debhelper script API or provide introspection for third-party tools
(e.g., linters).  Unless stated otherwise, commands must be run inside a source
package root directory - that is, the directory containing "debian/control".

Most commands use or can provide JSON output.  When stdout is a TTY, the JSON will be
prettified. See the manpage if you want formatting in other cases.
EOF
    return;
}

sub _assert_debian_control_exists {
    return if -f 'debian/control';
    require Cwd;
    my $cwd = Cwd::getcwd();
    warning("$cwd does not look like a package source directory (expected $cwd/debian/control to exist and be a file)");
    error("$COMMAND must be run inside a package source directory");
    return;
}

sub _output {
    my ($kvpairs) = @_;
    print $JSON_ENCODER->encode($kvpairs);
    return;
}

sub _allow_unsafe_execution() {
    $Debian::Debhelper::Dh_Lib::ALLOW_UNSAFE_EXECUTION = 1;
}

sub active_compat_level {
    if (@ARGV) {
        error("$COMMAND: No arguments supported (please remove everything after the command)");
    }
    _assert_debian_control_exists();
    my ($active_compat, $declared_compat, $declared_compat_source) = Debian::Debhelper::Dh_Lib::get_compat_info();
    if (not defined($declared_compat_source)) {
        $declared_compat = undef;
        $active_compat = undef if not exists($ENV{DH_COMPAT});
    }
    my %compat_info = (
        'active-compat-level'          => $active_compat,
        'declared-compat-level'        => $declared_compat,
        'declared-compat-level-source' => $declared_compat_source,
    );
    _output(\%compat_info);
    return;
}

sub supported_compat_levels {
    if (@ARGV) {
        error("$COMMAND: No arguments supported (please remove everything after the command)");
    }
    my %compat_levels = (
        'MIN_COMPAT_LEVEL'                           => Debian::Debhelper::Dh_Lib::MIN_COMPAT_LEVEL,
        'LOWEST_NON_DEPRECATED_COMPAT_LEVEL'         => Debian::Debhelper::Dh_Lib::LOWEST_NON_DEPRECATED_COMPAT_LEVEL,
        'LOWEST_VIRTUAL_DEBHELPER_COMPAT_LEVEL'      => Debian::Debhelper::Dh_Lib::LOWEST_VIRTUAL_DEBHELPER_COMPAT_LEVEL,
        'MAX_COMPAT_LEVEL'                           => Debian::Debhelper::Dh_Lib::MAX_COMPAT_LEVEL,
        'HIGHEST_STABLE_COMPAT_LEVEL'                => Debian::Debhelper::Dh_Lib::HIGHEST_STABLE_COMPAT_LEVEL,
        'MIN_COMPAT_LEVEL_NOT_SCHEDULED_FOR_REMOVAL' => Debian::Debhelper::Dh_Lib::MIN_COMPAT_LEVEL_NOT_SCHEDULED_FOR_REMOVAL,
    );
    _output(\%compat_levels);
    return;
}

sub which_build_system {
    my ($opt_buildsys, $destdir);
    my $first_argv = @ARGV ? $ARGV[0] : '';
    my %options = (
        # Emulate dh_auto_install's --destdir
        "destdir=s" => \$destdir,
    );
    _assert_debian_control_exists();
    # We never want the build system initialization to modify anything (e.g. create "HOME")
    $dh{NO_ACT} = 1;
    require Debian::Debhelper::Dh_Buildsystems;
    Debian::Debhelper::Dh_Buildsystems::buildsystems_init(options => \%options);
    my @non_options = grep { !m/^-/ } @ARGV;
    my $step = @non_options ? $non_options[0] : 'configure';
    if (@non_options && $first_argv =~ m/^-/) {
        error("$COMMAND: If the build step is provided, it must be before any options");
    }
    if (@non_options > 1) {
        error("$COMMAND: At most one positional argument is supported");
    }
    if (defined($destdir) and $step ne 'install') {
        warning("$COMMAND: --destdir is not defined for build step \"$step\". Ignoring option")
    }
    {
        no warnings qw(once);
        $opt_buildsys = $Debian::Debhelper::Dh_Buildsystems::opt_buildsys;
    }
    my $build_system = Debian::Debhelper::Dh_Buildsystems::load_buildsystem($opt_buildsys, $step);
    my %result = (
        'build-system'       => defined($build_system) ? $build_system->NAME : 'none',
        'for-build-step'     => $step,
        'source-directory'   => defined($build_system) ? $build_system->get_sourcedir : undef,
        'build-directory'    => defined($build_system) ? $build_system->get_builddir : undef,
        'dest-directory'     => defined($build_system) ? $destdir : undef,
        'buildpath'          => defined($build_system) ? $build_system->get_buildpath : undef,
        'parallel'           => defined($build_system) ? $build_system->get_parallel : undef,
        'upstream-arguments' => $dh{U_PARAMS},
    );
    _output(\%result);
    return;
}

sub _in_path {
    my ($cmd) = @_;
    for my $dir (split(':', $ENV{PATH})) {
        return 1 if -x "${dir}/${cmd}";
    }
    return 0;
}

sub _load_hook_targets {
    require Debian::Debhelper::SequencerUtil;
    Debian::Debhelper::SequencerUtil::rules_explicit_target('does-not-matter');
    my ($explicit_targets);
    {
        no warnings qw(once);
        $explicit_targets = \%Debian::Debhelper::SequencerUtil::EXPLICIT_TARGETS;
    }
    return $explicit_targets;
}

sub _hook_target_variants {
    my ($name) = @_;
    my @base = (
        "override_${name}",
        "execute_before_${name}",
        "execute_after_${name}",
    );
    return map {
        (
            $_,
            "${_}-arch",
            "${_}-indep",
        )
    } @base;
}


sub _load_levenshtein {
    my @modules = (qw(
        Text::LevenshteinXS
        Text::Levenshtein::XS
        Text::Levenshtein
    ));
    my $err;
    for my $module (@modules) {
        my $distance_func = eval "use $module (); \\&${module}::distance";
        $err = $@;
        if (defined($distance_func)) {
            return $distance_func;
        }
    }
    my $module_names = join(', ', @modules);
    warning("Could not load any of the modules ${module_names}");
    warning("Usually, `apt install libtext-levenshtein-perl` will fix this problem.");
    error("This subcommand requires one of the following modules to be available: ${module_names}. Last failure was: $@");
}


sub _all_sequence_commands {
    my ($forgive_errors, @addon_requests) = @_;
    my ($sequences, @all_commands, @unloadable, $commands_removed_by_sequence);
    Debian::Debhelper::SequencerUtil::load_sequence_addon('root-sequence', 'both');
    my @addons = Debian::Debhelper::SequencerUtil::compute_selected_addons('binary', @addon_requests);
    # Load addons, which can modify sequences.
    foreach my $addon (@addons) {
        my $addon_name = $addon->{'name'};
        my $addon_type = $addon->{'addon-type'};
        eval {
            Debian::Debhelper::SequencerUtil::load_sequence_addon($addon_name, $addon_type);
        };
        if (my $err = $@) {
            die($err) if not $forgive_errors;
            push(@unloadable, $addon_name);
        }
    }
    {
        no warnings qw(once);
        $sequences = \%Debian::Debhelper::DH::SequenceState::sequences;
        $commands_removed_by_sequence = \%Debian::Debhelper::DH::SequenceState::commands_removed_by_sequence;
    }
    my %seen;
    my %disabled_commands = %{$commands_removed_by_sequence};  # Copy
    for my $sequence(values(%{$sequences})) {
        my @commands = map {$_->[0]} $sequence->flatten_sequence('both', 0);
        for my $command (@commands) {
            next if $command =~ m{^(?:debian/rules|create-stamp)};
            next if exists($seen{$command});
            $seen{$command} = 1;
            push(@all_commands, $command);
            delete($disabled_commands{$command});
        }
    }
    return \@all_commands, \%disabled_commands, \@unloadable;
}

sub list_commands {
    _assert_debian_control_exists();
    require Getopt::Long;
    Getopt::Long::config('no_ignore_case');
    require Debian::Debhelper::SequencerUtil;
    my $output_format = "text";
    my (@addon_requests);
    my %options=(
        "output-format=s" => \$output_format,
        "with=s" => sub {
			my ($option, $value) = @_;
			push(@addon_requests, map { "+${_}" } split(",", $value));
		},
		"without=s" => sub {
			my ($option, $value) = @_;
			push(@addon_requests, map { "-${_}" } split(",", $value));
		},
	);
    Getopt::Long::GetOptionsFromArray(\@ARGV, %options)
        or error("Could not parse the arguments");

    if (@ARGV) {
        my $value = $ARGV[0];
        error("$COMMAND: No non-options supported - please remove ${value}");
    }
    my ($all_commands, $disabled_commands, $unloadables) = _all_sequence_commands(1, @addon_requests);
    if ($output_format eq 'json') {
        my (@commands_json, %known_commands);
        for my $command (sort(@{$all_commands})) {
            push(@commands_json, {
                'command' => $command,
            });
            $known_commands{$command} = 1;
        }
        my %result = (
            "commands" => \@commands_json,
        );
        if (%{$disabled_commands}) {
            my @remove_commands;
            while (my ($command, $addon) = each(%{$disabled_commands})) {
                next if $known_commands{$command};
                my $data = {
                    'command' => $command,
                };
                $data->{'removed-by'} = $addon if $addon;
                push(@remove_commands, $data);
            }
            if (@remove_commands) {
                $result{'disabled-commands'} = \@remove_commands;
            }
        }
        if (@{$unloadables}) {
            my @issues;
            for my $addon (@{$unloadables}) {
                push(@issues, {
                    "issue" => "load-addon",
                    "addon" => $addon,
                });
            };
            $result{'issues'} = \@issues;
        }
        _output(\%result);
    } elsif ($output_format eq 'text') {
        print("Commands present in at least one sequence for this source package (sorted by name):\n");
        for my $command (sort(@{$all_commands})) {
            print("\t${command}\n");
        }
        if (@{$unloadables}) {
            my $addon_names = join(" ", @{$unloadables});
            print("\n");
            warning("Incomplete result. The following sequence add-ons could not be loaded: $addon_names");
        }
    } else {
        error("Internal error: Missing case for ${output_format}");
    }
}

sub _extract_annotations {
    my ($command) = @_;
    my $has_explicit_no_config = 0;
    my @annotations;

    foreach my $dir (split(':', $ENV{PATH})) {
        if (open (my $h, "<", "$dir/$command")) {
            while (<$h>) {
                if (m/PROMISE: DH NOOP( WITHOUT\s+(.*))?\s*$/) {
                    if (defined($2)) {
                        push(@annotations, split(' ', $2));
                    } else {
                        push(@annotations, 'always-skip');
                    }
                }
                if (m/INTROSPECTABLE: CONFIG-FILES\s+(.*)\s*$/) {
                    my $anno = $1 // '';
                    if ($anno eq 'NONE') {
                        $has_explicit_no_config = 1;
                    } else {
                        push(@annotations, split(' ', $anno));
                    }
                }
            }
            close $h;
            return $has_explicit_no_config, @annotations;
        }
    }
    return;
}

sub list_guessed_dh_config_files {
    _assert_debian_control_exists();
    require Getopt::Long;
    Getopt::Long::config('no_ignore_case');
    require Debian::Debhelper::SequencerUtil;
    my (@addon_requests);
    my %options=(
        "with=s" => sub {
			my ($option, $value) = @_;
			push(@addon_requests, map { "+${_}" } split(",", $value));
		},
		"without=s" => sub {
			my ($option, $value) = @_;
			push(@addon_requests, map { "-${_}" } split(",", $value));
		},
	);
    Getopt::Long::GetOptionsFromArray(\@ARGV, %options)
        or error("Could not parse the arguments");

    if (@ARGV) {
        my $value = $ARGV[0];
        error("$COMMAND: No non-options supported - please remove ${value}");
    }

    my ($active_commands, $disabled_cmds, $unloadables) = _all_sequence_commands(1, @addon_requests);
    my $pkg_files = {};
    my $path_files = {};
    my @all_commands = (@{$active_commands}, keys(%{$disabled_cmds}));
    my (%known_no_config_files, %has_config_files);
    for my $command (@all_commands) {
        my ($has_explicit_no_config, @annotations) = _extract_annotations($command);
        $known_no_config_files{$command} = 1 if $has_explicit_no_config;
        next if not @annotations or $annotations[0] eq 'always-skip';
        my $bug_950723;
        for my $annotation (@annotations) {
            my $type = 'pkgfile';
            my $need = $annotation;
            if ($annotation =~ m/^([a-zA-Z0-9-_]+)\((.*)\)$/) {
                ($type, $need) = ($1, $2);
            }
            if ($type eq 'internal') {
                $bug_950723 = 1 if $need eq 'bug#950723';
            }
            next if $type ne 'pkgfile' and $type ne 'pkgfile-logged' and $type ne 'path';
            my $key = "pkgfile/${need}";
            my $is_active = not exists($disabled_cmds->{$command});
            my $command_data = {
                'command'   => $command,
                'is-active' => $is_active ? JSON::PP::true : JSON::PP::false,
            };
            if (not $is_active) {
                my $removed_by = $disabled_cmds->{$command};
                $command_data->{'removed-by'} = $removed_by if $removed_by;
            }
            if ($type eq 'path') {
                next if $need =~ m{(?:\A|.*/)[.][.]?(?:/.*|\Z)};
                my $existing = $path_files->{$key};
                if (defined($existing)) {
                    push(@{$existing->{'commands'}}, $command_data);
                } elsif ($type eq 'path') {
                    $existing = {
                        'file-type' => 'path',
                        'path'      => $need,
                        'commands'  => [$command_data],
                    };
                    $path_files->{$key} = $existing;
                }
            } else {
                my $existing = $pkg_files->{$key};
                if (defined($existing)) {
                    push(@{$existing->{'commands'}}, $command_data);
                } else {
                    $existing = {
                        'file-type' => 'pkgfile',
                        'pkgfile'   => $need,
                        'commands'  => [$command_data],
                    };
                    $pkg_files->{$key} = $existing;
                }
                if ($bug_950723) {
                    $existing->{"internal"}{"bug#950723"} = JSON::PP::true;
                }
            }
            $has_config_files{$command} = 1;
        }
    }

    my @config_files = values(%{$pkg_files});
    push(@config_files, values(%{$path_files}));
    my %result = (
        "config-files" => \@config_files,
    );
    my @commands_unknown_state = grep {
        not exists($known_no_config_files{$_})
        and not exists($has_config_files{$_})
        and not exists($disabled_cmds->{$_})
    } @all_commands;
    if (@commands_unknown_state) {
        $result{'commands-not-introspectable'} = \@commands_unknown_state;
    }
    if (@{$unloadables}) {
        my @issues;
        for my $addon (@{$unloadables}) {
            push(@issues, {
                "issue" => "load-addon",
                "addon" => $addon,
            });
        };
        $result{'issues'} = \@issues;
    }
    _output(\%result);
}

sub _is_single_binary_addon_candidate_pending_opt_in {
	return _uses_dh() && getpackages() == 1 && !_has_addon('single-binary')
}

sub _is_single_binary_package {
	return scalar(getpackages()) < 2;
}

sub _first_package {
	my @packages = getpackages();
	return $packages[0];
}

sub _uses_name {
	state $uses_name;
	return $uses_name if defined($uses_name);
	return if not -f 'debian/rules';
	open(my $fd, '<', 'debian/rules') or error("Cannot read debian/rules: $!");
	while (my $line = <$fd>) {
		next if $line =~ m/^\s*#/;
		if ($line =~ m/^\t(?:.*[\s;&])?dh_.*--name/){
			$uses_name = 1;
			last;
		}
	}
	$uses_name //= 0;
	close($fd);
	return $uses_name;
}

sub _source_has_path_with_basename {
	my ($requested_basename) = @_;
	state %checked;
	if (exists($checked{$requested_basename})) {
		return $checked{$requested_basename};
	}
	require File::Find;
	my $found = 0;
	File::Find::find({
		wanted => sub {
			no warnings qw(once);
			my $path = $File::Find::name;
			my $name = basename($path);
			if ($found || (-d $path && $name eq '.git')) {
				$File::Find::prune = 1;
				return;
			}
			if ($requested_basename eq $name) {
				$found = 1;
				$File::Find::prune = 1;
				return;
			}
		},
		no_chdir => 1,
	}, '.');
	$checked{$requested_basename} = $found;
	return $found;
}

sub _uses_build_system {
	my ($build_system) = @_;
	# Main problem is dealing with `dh ... --sourcedirectory .... -Sautoreconf` + overrides for `dh_auto_configure`.
	# - For now, we basically re-implement the auto-detection because it is more reliable.
	if ($build_system eq 'cmake' or $build_system =~ m/^cmake[+]/) {
		# cmake has a decent indicator in the form of `CMakeLists.txt`
		return _source_has_path_with_basename('CMakeLists.txt');
	}
	if ($build_system eq 'meson' or $build_system =~ m/^meson[+]/) {
		# meson has a decent indicator in the form of `meson.build`
		return _source_has_path_with_basename('meson.build');
	}
	if ($build_system eq 'gradle') {
		# gradle has a decent indicator in the form of `build.gradle` or `build.gradle.kts`
		return _source_has_path_with_basename('build.gradle') || _source_has_path_with_basename('build.gradle.kts');
	}
	# TODO: Not implemented; assumes true to put it into manual review for now.
	return 1;
}

# Does not explicitly check for _uses_dh, but is generally stronger than _uses_dh anyway.
sub _has_hook_target {
	my ($hook_target) = @_;
	my $explicit_targets = _load_hook_targets();
	return exists($explicit_targets->{$hook_target}) ? 1 : 0;
}

# Does not explicitly check for _uses_dh, but is generally stronger than _uses_dh anyway.
sub _has_hook_target_for_cmd {
	my ($command) = @_;
	for my $variant (_hook_target_variants($command)) {
		return 1 if _has_hook_target($variant);
	}
	return 0;
}

sub _has_pkgfile {
	my ($stem) = @_;
	my @packages = getpackages();
	return 1 if pkgfile(\@packages, $stem);
	return 0;
}

sub _has_addon {
	my ($addon) = @_;
	# TODO: Not implemented; assumes true to put it into manual review for now.
	#
	# Main problem is dealing with `dh ... --with ....`
	return 1;
}

sub _has_file {
	my ($filename) = @_;
	return -f $filename;
}

sub _uses_dh {
	state $uses_dh;
	return $uses_dh if defined($uses_dh);
	return if not -f 'debian/rules';
	open(my $fd, '<', 'debian/rules') or error("Cannot read debian/rules: $!");
	while (my $line = <$fd>) {
		next if $line =~ m/^\s*#/;
		if ($line =~ m/^\t(?:.*[\s;&])?dh\s/){
			$uses_dh = 1;
			last;
		}
	}
	$uses_dh //= 0;
	close($fd);
	return $uses_dh;
}

# Programmatic upgrade checklist.
#   - The Key is the compat level being upgraded **from**. That is `13` is for the `13 -> 14` upgrade.
#   - The Value is a dict with the following keys:
#      - title: The headline (mandatory)
#      - howtofix: A short description aimed at how to fix the problem (de facto mandatory)
#      - careful: A short description of what will or can go wrong if this item is not properly heeded.
#                 Examples include "Orphaned conffiles", "Silent misbuilds".
#      - validate: How to validate if the package is affected.
#      - lintian: The lintian bug for this change if relevant.
#      - docs: List of documentation URIs to show for this item.
#      - is_relevant: Sub that when invoked returns true if the item is relevant or would require manual review to
#                     determine if it is relevant. When it returns false, the item does not or is very unlikely to
#                     affect the source package. When in doubt, factor in the consequence of omitting this item in
#                     upgrade. If the consequence is bad (such as silent misbuild) then prefer the manual review.
#
my %UPGRADE_CHECKLIST_WHEN_UPGRADING_FROM = (
	7 => [
		{
			"title"    => 'Commands from `debhelper` will fail rather than warning when they are passed unknown options except where prefixed by `-O`',
			"howtofix" => 'Check `debian/rules` and build log for unknown parameters being passed to `debhelper` commands and fix them.',
		},
		{
			"title"    => 'The `dh_makeshlibs` command will run `dpkg-gensymbols` on all shared libraries it generated a `shlibs` file for',
			"howtofix" => 'Probably the package will be unaffected. But passing `-X` to `dh_makeshlibs` to exclude a library might needed.',
		},
		{
			"title"    => 'The `dh` command requires the sequence name to be the first parameter',
			"is_relevant" => sub { return _uses_dh()},
			"howtofix" => 'Check `debian/rules` and see if the `dh` command line might need to be reordered.',
		},
		{
			"title"    => 'The `dh_auto_*` commands will prefer the `perl_build` over `perl_makemaker` when both are an option',
			"howtofix" => 'Validate that the resulting binary is still as expected. Pass `-Sperl_makemaker` to relevant commands to revert to the previous behavior',
		},
	],
	8 => [
		{
			"title"    => 'Multi-arch support: The multi-arch variant of `--libdir` + `--libexecdir` is passed to various build systems',
			"howtofix" => 'Can cause build failures, when packaging assumes `/usr/lib` rather than the multi-arch directory or when search paths are not used. No generic fix available.',
		},
		{
			"title"    => 'The `dh` command will now properly recurse into `debian/rules` if it defines a target',
			"is_relevant" => sub { return _uses_dh()},
			"howtofix" => 'Can cause build failures, if a stray `build` (or similar target) remains in `debian/rules`. Test the package correctly builds after this check and ensure content is not missing.',
		},
		{
			"title"    => 'The `dh_strip` command will now compress debugging symbols to reduce installed size of `-dbg` packages',
			"is_relevant" => sub {return 0;},
			"howtofix" => 'Generally a non-problem as the majority of the Debian packages already use compressed debug symbols. No new problems are expected at this point.',
		},
		{
			"title"    => 'The `autoconf` build system no longer includes the source package name in the `--libexecdir` parameter',
			"howtofix" => 'Ensure the package and relevant dependencies can cope with the new package layout if libexecdir is used by the package at all',
		},
		{
			"title"    => '[NOT RELEVANT] The `python-support` sequence is not enabled by default any more',
			"is_relevant" => sub {return 0;},
			"howtofix" => "This entry is here only here for the sake of being 1:1 with the docs. The item became obsolete when the `python-support` sequence was removed in `debhelper/10.3`, so it is no longer possible to use it at all in any compat level.",
		},
		{
			"title"    => 'The `dh` and `dh_auto_*` commands now set flags from `dpkg-buildflags` and passes them to the underlying build systems where possible',
			"howtofix" => "Ensure the package still works when rebuild. For some, this is unproblematic. For other packages, the hardening flags may cause the package to crash since bugs gets detected at runtime. The latter will require patching up the upstream code to resolve.",
		},
		{
			"title"    => 'The `dh_strip` command uses build-id for the path of debug symbols',
			"is_relevant" => sub {return scalar(grep { m/^-dbg$/} getpackages()) > 0;},
			"howtofix" => 'Most packages should not be affected by this, since `dh_strip` handles this behind the scenes. Listed for the sake of the checklist being exhaustive more than anything else.',
		},
		{
			"title"    => 'Executable config files in `debian` are now often run and their output used as configuration when the helper supports it',
			"howtofix" => 'Ensure files in `debian` does not needlessly have the `x` bit set. Some custom code in `debian/rules` might now be replaced by this feature.',
		},
	],
	9 => [
		{
			"title"    => 'The `dh_installinit` command will no longer use `debian/<PACKAGE>` as the name of an init script',
			"is_relevant" => sub {for my $p (getpackages()) {return 1 if _has_file("debian/${p}");} return 0;},
			"howtofix" => 'Rename the file to `debian/<PACKAGE>.init`.',
		},
		{
			"title"    => 'The `dh_installdocs` command will now error out when `--link-doc` is used in an incompatible manner',
			"howtofix" => "If `dh_installdocs` reacts to the use of `--link-doc`, remove the `--link-doc` and remember to perform the relevant `symlink_to_dir` conversion (e.g., via `dh_installdeb`'s `maintscript` file)",
		},
		{
			"title"    => 'The `dh_installwm` command is now more strict about missing man page',
			"is_relevant" => sub {return _has_pkgfile("wm");},
			"howtofix" => "If the `dh_installwm` command errors out during build, check that the package provides the relevant man page required for a window manager.",
		},

		{
			"title"    => 'All build systems that support parallel now default to parallel builds',
			"howtofix" => "If the build becomes unstable or fail, you may need `--no-parallel` or `--max-parallel=<LIMIT>` passed to `dh` or relevant `dh_auto_*` command. Note the failure might be due to missing dependencies in upstream's build system rules.",
		},
		{
			"title"    => '[NOT RELEVANT] The `dh` command no longer accepts "manual sequence control" parameters (such as `--before`)',
			"is_relevant" => sub { return 0; },
			"howtofix" => "This entry is here only here for the sake of being 1:1 with the docs. The item became obsolete when the `dh` removed support for these options in `debhelper/12.4` regardless of compat level.",
		},
		{
			"title"    => 'The `dh` command no longer tracks commands being run via "log files"',
			"howtofix" => "Might affect the package if commands are using `dh_foo` outside the `override_dh_foo` target. Especially if combined with `dh_foo --remaining-packages`. Validate if the package is still built as expected.",
		},
		{
			"title"       => 'The `dh_installdeb` command now ensures parameters to `dpkg-maintscript-helper` are properly shell escaped',
			"is_relevant" => sub {return _has_pkgfile("maintscript")},
			"howtofix"    => 'If the package relied on shell-constructs, then the generated code may no longer work. Check the files for shell constructs and verify the resulting maintainer scripts',
		},
		{
			"title"       => 'The `dh_installinit` command now defaults to `--restart-after-upgrade`',
			"howtofix"    => 'If the previous behavior was desired, please override the command and pass `--no-restart-after-upgrade.',
		},
		{
			"title"       => 'The `autoreconf` and `systemd` sequence are now active by default',
			"howtofix"    => 'Pass `--without autoreconf` or/and `--without systemd` to `dh` to revert to the previous behavior. Explicit `--with` for these sequences can now be removed. Note the `systemd` sequence is removed in compat 11+.',
		},
		{
			"title"    => '[NOT RELEVANT] The `dh` command no longer creates the package build directory when skipping debhelper commands',
			"is_relevant" => sub { return 0; },
			"howtofix" => "This entry is here only here for the sake of being 1:1 with the docs. The item became obsolete when became apparent that the compatibility code never worked in the first place.",
		},
	],
	10 => [
		{
			"title"       => 'The `dh_installinit` command no longer installs `service` or `tmpfile` files, nor does it generate maintainer script snippets for those files',
			"is_relevant" => sub { return _has_hook_target_for_cmd("dh_installinit"); },
			"howtofix"    => 'These features are now handled by a new command  called `dh_installsystemd`. If custom settings were passed to `dh_installinit`, they may be relevant to `dh_installsystemd`as well.',
		},
		{
			"title"       => 'The `dh_systemd_enable` and `dh_systemd_start` commands have been replaced by `dh_installsystemd`',
			"is_relevant" => sub { return _has_hook_target_for_cmd("dh_systemd_enable") || _has_hook_target_for_cmd("dh_systemd_start"); },
			"howtofix"    => 'Determine if some of the parameters passed to these commands should move to `dh_installsystemd` instead',
		},
		{
			"title"       => 'The `dh_installdirs` no longer creates `debian/<PACKAGE>` unless it has to create a subdir inside it',
			"is_relevant" => sub { return 0; },
			"howtofix"    => 'No packages seem to have been adversely affected by this change, since `debhelper` commands creates parent directories as necessary.',
			"validate"    => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"       => 'The `makefile` build system now passes `INSTALL="install --strip-program=true"` to `make`',
			"is_relevant" => sub { return 0; },
			"howtofix"    => 'Other than slightly more noisy build logs, there are no known instances where this change caused issues.',
		},

		{
			"title"       => 'The `autoconf` build system now passes `--runstatedir=/run` to `./configure`',
			"howtofix"    => 'The `./configure` script may need to be regenerated to support the option.',
		},

		{
			"title"       => 'The `cmake` build system now passes `-DCMAKE_INSTALL_RUNSTATEDIR=/run` to `cmake`',
			"is_relevant" => sub { _uses_build_system('cmake'); },
			"howtofix"    => 'No known issues has been recorded for this change. However, if needed, override `dh_auto_configure` and pass `-DCMAKE_INSTALL_RUNSTATEDIR=...` with the relevant path to temporarily restore the previous behavior.',
		},
		{
			"title"       => 'The `dh_installman` command now guesses the man page language from path over extension if possible',
			"howtofix"    => 'Validate the man pages are still installed in the correct directory. The `--language` option can be used to disable the language guessing.',
		},
		{
			"title"       => 'The `dh_auto_install` command now only creates the destination directory if it needs to',
			"howtofix"    => 'Should be a non-issue. But if needed be, use `dh_installdir` or a hook target to create the necessary directory.',
			"validate"    => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"       => 'The `dh_installdocs`, `dh_installexamples`, `dh_installinfo`, and `dh_installman` now errors out if a glob pattern does not match anything',
			"is_relevant" => sub  { _has_pkgfile("docs") || _has_pkgfile("examples") || _has_pkgfile("info") || _has_pkgfile("manpages"); },
			"howtofix"    => 'Ensure the commands are not processing globs that do not match anything. An error will generally fail the build.',
			"validate"    => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"       => 'The `dh_installdocs`, `dh_installexamples`, `dh_installinfo`, and `dh_installman` now accepts `--sourcedir`',
			"howtofix"    => 'If the package passes `--sourcedir` to any of these helpers or `dh`, then they might now use the "wrong" source directory for their search. Check if the build is successful and the correct documentation is installed.',
		},

		{
			"title"       => 'The `perl` build systems (`perl-makemaker` and `perl-build`) no longer pass `-I,` to `perl`',
			"howtofix"    => "Setting and exporting `PERL5LIB=.` in `debian/rules` might be needed if upstream's build system relies on the behavior",
		},

		{
			"title"       => 'The `PERL_USE_UNSAFE_INC` environment variable is no longer set by `dh` or `dh_auto_*`',
			"howtofix"    => "Setting and exporting `PERL5LIB=.` in `debian/rules` might be needed if upstream's build system relies on the behavior",
		},

		{
			"title"       => 'The `dh_makeshlibs` command now fails if the `objdump` command fails or returns non-zero',
			"is_relevant" => sub { return 0; },
			"howtofix"    => "No known issues to date. But if it did occur, then ensure relevant ELF binaries can be processed by `objdump` or exclude the files from `dh_makeshlibs`.",
		},

		{
			"title"       => 'The `dh_installdocs` and `dh_installexamples` now respects the `doc-main-package` concept',
			"howtofix"    => "In some cases, packages might have a different on what the `doc-main-package` should be for some documentation. Pass `--doc-main-package` to the commands as relevant.",
		},

		{
			"title"       => 'The `dh_strip` and `dh_shlibdeps` no longer uses `file` to determine if a file is an ELF file',
			"howtofix"    => "This change may cause more ELF binaries to be detected by these helpers. Use `-X` to skip files if that becomes a problem.",
		},
	],
	11 => [
		{
			"title"    => 'The `dh_makeshlibs` tool now generate `shlibs` with versioned dependencies by default (`-V` is the new default)',
			"howtofix" => 'Most packages are unaffected, since this is a safer default. If needed, the previous behavior can be requested via `-VNone`.',
		},
		{
			"title"    => 'The `-s` / `--same-arch` option is now removed',
			"howtofix" => 'Check `debian/rules` for these options and replace them with `-a` or `--same-arch`.',
			"validate" => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"    => 'The `dh_clean` command no longer accepts `-k`',
			"howtofix" => 'Check `debian/rules` for `dh_clean` being passed `-k`. The command + option should be replaced by `dh_prep`.',
			"validate" => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"    => 'The `dh_installinit` command no longer accepts `--no-restart-on-upgrade`',
			"howtofix" => 'Check `debian/rules` for `dh_installinit` being passed `--no-restart-on-upgrade`. The option should be replaced by `--no-stop-on-upgrade`.',
			"validate" => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"    => 'Third-party provided `dh_*` commands might fail with a `command-not-found` because they assume the `doit` functions accept shell in a special-case.',
			"howtofix" => 'If you experience this problem, file a bug against the command in question and await its fix before upgrading.',
			"validate" => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"    => 'The `dh_install` command no longer accepts `--list-missing` nor `--fail-missing`',
			"howtofix" => 'Check `debian/rules` for `dh_install` being passed `--list-missing` or `--fail-missing`. If so, remove them and instead rely on `dh_missing` for this functionality',
			"validate" => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"       => 'The `dh_installinit` command no `upstart` configuration. A `rm_conffile` might be needed',
			"is_relevant" => sub {return _has_pkgfile("upstart")},
			"howtofix"    => 'If there are any `debian/<PACKAGE>.upstart` files, ensure the package cleans them up with `rm_conffile` and then remove the offending files.',
		},
		{
			"title"       => 'The `dh_installdeb` command now validates the `maintscript` file during package build',
			"is_relevant" => sub {return _has_pkgfile("maintscript")},
			"howtofix"    => 'Run `dh_installdeb` and handle any errors it might report for the `maintscript` files in `debian/`',
			"validate"    => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"    => 'The `dh_missing` command now defaults to `--list-missing` (will become `--fail-missing` in compat 13)',
			"howtofix" => 'Check the build log for warnings from `dh_missing` and fix them. Alternatively, override `dh_missing` to get the desired behavior',
		},
		{
			"title"    => 'The `dh_makeshlibs` tool will now only pass ELF binaries to `dpkg-gensymbols` if they have a `SONAME` containing `.so`',
			"howtofix" => 'Most packages are unaffected, since this is the common convention for shared ELF libraries.',
		},
		{
			"title"    => 'The `dh_compress` command no longer compressed any file under the `examples` folder',
			"howtofix" => 'Check if any paths/references might be updated since the paths are no longer compressed.',
		},
		{
			"title"    => 'The default `dh` sequence now includes `dh_dwz`, `dh_installinitramfs`, `dh_installsystemduser`',
			"is_relevant" => \&_uses_dh,
			"howtofix" => 'Remove the explicit `dh` add-ons for them where used. Also check for hook targets used to manually invoke the commands',
		},
		{
			"title"    => 'The `meson` and `autoconf` build systems no longer explicitly sets the `libexecdir`',
			"howtofix" => 'Check that relevant binaries till end up in `/usr/libexec`. If not , override `dh_auto_configure` and pass the relevant option to the underlying build sysem',
		},
		{
			"title"       => '[NOT RELEVANT] The `dh_installdeb` command no longer processes the `debian/<PACKAGE>.conffiles` file',
			"is_relevant" => sub {return 0;},
			"howtofix"    => "There is nothing to fix as item is no longer applicable. This entry is here only here for the sake of being 1:1 with the docs. The item was undone due to `dpkg`'s `remove-on-upgrade` feature.",
		},
		{
			"title"       => 'The `dh_installsystemd` command no longer relies on `dh_installinit` for `systemd` services',
			"is_relevant" => sub {_has_hook_target('dh_installinit') || _has_hook_target('dh_installsystemd');},
			"howtofix"    => 'Check if `dh_installsystemd` might need to be passed some different options (as an example `--no-start` might also need to be passed to `dh_installsystemd` if it was previously used with `dh_installinit`).',
		},
		{
			"title"    => 'The third-party `dh_golang` now defaults to honoring `DH_GOLANG_EXCLUDES` also when installing',
			"howtofix" => 'If the package uses `dh_golang` and `DH_GOLANG_EXCLUDES`, check if the resulting `.deb` is as expected. Set `DH_GOLANG_EXCLUDES_ALL` to `false` to revert to the previous behavior.',
			'docs'     => [
				"man:Debian::Debhelper::Buildsystem::golang(3)",
			],
		},
		{
			"title"       => 'The `python-distutils` build system is now removed',
			"is_relevant" => sub {_uses_build_system('python-distutils');},
			"howtofix"    => 'Consider replacing it with the the third-party `pybuild` build system instead.',
		},
	],
	12 => [
		{
			"title"       => 'The `meson+ninja` build system now invokes `meson test` instead of `ninja test` during `dh_auto_test`',
			"is_relevant" => sub {return _uses_build_system('meson+ninja') && _has_hook_target('override_dh_auto_test')},
			"howtofix"    => 'Check the override target for `dh_auto_test` for parameters passed to `ninja test` and replace them with `meson test` compatible options',
		},
		{
			"title"    => 'Abbreviated options are no longer supported',
			"howtofix" => 'Check long options passed to `dh` or `dh_*` tools in `debian/rules` to ensure they match the documented spelling. Be extra careful when `-O` or passing arguments to `dh` are involved as they can silently discards unknown options (`dh` passes most options on via `-O`. Check the build logs).',
		},
		{
			"title"    => 'The ELF related helpers (such as `dh_strip`) are no longer run for arch:all packages',
			"howtofix" => 'Most packages will be unaffected. But check that hook targets and the resulting debs are as expected. Previous behavior can be restored by adding `dh-sequence-elf-tools` to `Build-Depends`.',
		},
		{
			"title"       => 'The third-party build system `gradle` handler now runs upstream test suite during `dh_auto_test`',
			"is_relevant" => sub {return _uses_build_system('gradle')},
			"howtofix"    => 'If the package uses gradle, then the build may now fail if the tests do not succeed. Previous behavior can be restored by adding an empty `override_dh_auto_test:` target to `debian/rules`',
			"validate"    => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"       => 'The `dh_installman` tool will now abort the build if it sees conflicting definitions of a man page',
			"is_relevant" => sub {return _has_pkgfile('manpages')},
			"howtofix"    => 'Often, the offending line can be removed from the `debian/<PACKAGE>.manpages. This problem typically occurs when upstream build system and `dh_installman` (via `debian/<PACKAGE>.manpages`) tries to install the same man page but one installs the compressed and the other installs the uncompressed variant of the man page.',
			"validate"    => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"    => 'The `dh_auto_*` tools now reset the environment variable `HOME` + `XDG_*`',
			"howtofix" => 'Typically, packages are unaffected as these variables are not writable on the Debian build servers.',
		},

		{
			"title"       => 'The `dh` command now errors out on hook targets for obsolete commands such as `override_dh_systemd_enable`',
			"is_relevant" => sub {return _has_hook_target_for_cmd('dh_systemd_enable') || _has_hook_target_for_cmd('dh_systemd_start')},
			"howtofix"    => 'Remove the obsolete hook targets',
			"validate"    => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"    => 'The `dh_missing` command now defaults to `--fail-missing`',
			"howtofix" => 'Ensure the package builds, adding paths to `debian/not-installed` if they are not relevant. Alternatively, override `dh_missing` and request the desired behavior.',
			"validate" => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"       => 'The `dh_installtmpfiles` is now run by default and replaces the tmpfiles handling from `dh_installsystemd`',
			"is_relevant" => sub {return _has_hook_target('override_dh_installsystemd')},
			"howtofix"    => 'Any overrides for `dh_installsystemd` might need to be reapplied to `dh_installtmpfiles`',
		},
		{
			"title"       => 'The `dh_installtmpfiles` expects `debian/<PACKAGE>.tmpfiles` rather than `debian/<PACKAGE>.tmpfile`',
			"is_relevant" => sub {return _has_pkgfile('tmpfile')},
			"howtofix"    => 'Rename the files to match the new naming convention.',
		},
		{
			"title"    => 'Many of the `dh_*` tools now support limited variable expansion via `${foo}`',
			"howtofix" => "Some uses of `dh-exec` can be replaced by this feature. Note: filtering and renaming support still requires `dh-exec`.",
		},
		{
			"title"       => 'The `dh` command will now skip hook targets for `dh_auto_test`, `dh_dwz`, and `dh_strip` if the relevant `DEB_BUILD_OPTIONS` is set (`nocheck` + `nostrip`)',
			"is_relevant" => sub {return _has_hook_target('dh_auto_test') || _has_hook_target('dh_dwz') || _has_hook_target('dh_strip')},
			"howtofix"    => "Ensure none of the hook targets for these commands are relevant when they would be skipped. If they are relevant, move them to a different hook target (such as `execute_after_dh_build`).",
		},
		{
			"title"       => 'The `cmake` build system now passes `-DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=ON` to `cmake`',
			"is_relevant" => sub {return _uses_build_system('cmake')},
			"howtofix"    => "This can affect the installation step (such as `dh_auto_install`). Previous behavior can be restored by overriding `dh_auto_configure` with `dh_auto_configure -- -DCMAKE_SKIP_INSTALL_ALL_DEPENDENCY=OFF ...`",
		},
	],
	13 => [
		{
			"title"       => "The `dh_installmodules` command moved dest path from /etc to /usr/lib/modprobe.d.",
			"howtofix"    => "If the package uses `dh_installmodules`, then `rm_conffile` migration is necessary (see `man:dh_installdeb(1)`). Otherwise, it is done.",
			"is_relevant" => sub {return _has_pkgfile('modprobe') || _has_hook_target_for_cmd('dh_installmodules')},
			"careful"     => "Orphaned `conffiles`.",
		},
		{
			"title"       => "The `dh_installpam` command moved dest path from /etc to /usr/lib/pam.d.",
			"howtofix"    => "If the package uses `dh_installpam`, then `rm_conffile` migration is necessary (see `man:dh_installdeb(1)`). Otherwise, it is done.",
			"is_relevant" => sub {return _has_pkgfile('pam') || _has_hook_target_for_cmd('dh_installpam')},
			"careful"     => "Orphaned `conffiles`.",
		},
		{
			"title"            => "The order of `dh_strip_nondeterminism`, `dh_compress`, and `dh_fixperm` has changed.",
			"is_relevant"      => \&_uses_dh,
			"howtofix"         => "Do a rebuild and validate everything behaves as expected - including checking the generated `.deb` files. Be extra careful of unexpected permissions changes or third-party add-ons no longer working as expected.",
			"careful"          => "Silent misbuilds (invalid permissions)",
		},
		{
			"title"       => "The `dh_installsysusers` tool is now included in the default sequence.",
			"is_relevant" => \&_uses_dh,
			"howtofix"    => "Remove any manual activation of the `installsysusers` sequence. If you have hook targets that call the helper, they may no longer be necessary.",
		},

		{
			"title"            => "The `dh_installalternatives` tool is now run after `dh_link`",
			"howtofix"         => "Do a rebuild plus install test to validate everything behaves as expected.",
			"is_relevant"       => sub {return _uses_dh() && _has_pkgfile('alternatives')},
		},
		{
			"title"            => "The `dh_dwz` is no longer included in the default sequence",
			"howtofix"         => "If still needed, add `dh-sequence-dwz` to `Build-Depends-Arch`. Otherwise, remove any hook targets for the command. Note, this change will cause a lot of noise in the diffoscope output if it used when validating the upgrade.",
			"is_relevant"       => sub {
				return 1 if _has_hook_target_for_cmd('dh_dwz');
				for my $p (getpackages()) {
					return _uses_dh() if not package_is_arch_all($p);
				}
				return 0;
			},
		},
		{
			"title"       => "Hook targets for `dh_gconf` will now cause an error",
			"howtofix"    => "Remove any lingering hook targets. A re-build will catch the issues.",
			"is_relevant" => sub {return _has_hook_target_for_cmd('dh_gconf')},
			"validate"    => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
		{
			"title"    => "New helper `dh_computeautosubstvars` has been introduced to the default sequence.",
			"is_relevant" => sub {return _has_hook_target('execute_before_dh_gencontrol') || _has_hook_target('override_dh_gencontrol')},
			"howtofix" => "Ensure nothing in the package changes between `dh_computeautosubstvars` and `dh_gencontrol`. Move affected hooks to `execute_after_dh_installdeb` (as an example).",
		},
		{
			"title"       => "The `dh_auto_install` default for `--destdir` changed for single binary source packages without `single-binary` add-on.",
			"is_relevant" => sub {return _is_single_binary_addon_candidate_pending_opt_in() || (_is_single_binary_package() && _has_hook_target("override_dh_auto_install"))},
			"howtofix"    => "Add `dh-sequence-single-binary` to `Build-Depends` (keep previous behavior with no overrides of `dh_auto_install`) or pass `--without single-binary` to `dh` (accept new behavior or overriding of `dh_auto_install`).",
		},
		{
			"title"       => "The `dh` sequencer will (with a warning) default to activating the `single-binary` sequence for single binary source packages.",
			"is_relevant" => sub {return _is_single_binary_addon_candidate_pending_opt_in()},
			"howtofix"    => "Add `dh-sequence-single-binary` to `Build-Depends` (keep previous behavior and no overrides of `dh_auto_install`) or pass `--without single-binary` to `dh` (accept new behavior or overriding of `dh_auto_install`).",
		},
		{
			"title"    => "The `dh_installsystemduser` tool now enables and starts/stops user level services by default.",
			"howtofix" => "If the package has user level `systemd` services, validate that the new default works for the services in question.",
			"careful"  => "Silent misbuilds (user services behaving differently that desired)",
		},
		{
			"title"    => "The `dh_gencontrol` will now apply relationship variables automatically.",
			"howtofix" => 'For most packages, this requires no changes other than cleaning up cases of `Depends: ${misc:Depends}, ${shlibs:Depends}`. But if the package demotes substvars (`Recommends: ${misc:Depends}`), then they will have to adapt (see docs).',
			"docs"     => [
				"<https://lists.debian.org/debian-devel/2024/02/msg00230.html>",
				"<https://lists.debian.org/debian-devel/2024/03/msg00030.html>",
			],
			'lintian'  => '#1067653',
		},
		{
			"title"       => 'The `dh_gencontrol` will now default to using `${shlibs:Pre-Depends}` for packages that are `Essential: yes`',
			"is_relevant" => sub {
				for my $p (getpackages()) {
					return 1 if package_is_essential($p);
				}
				return 0;
			},
			"howtofix"    => 'Instances of `Pre-Depends: ${shlibs:Depends}` can now be removed since relationship variables are applied automatically, and `Essential: yes` makes `dh_shlibdeps` use `${shlibs:Pre-Depends}` by default.',
			"docs"     => [
				"<https://lists.debian.org/debian-devel/2024/02/msg00230.html>",
				"<https://lists.debian.org/debian-devel/2024/03/msg00030.html>",
			],
			'lintian'     => '#1067653',
		},
		{
			"title"    => 'The underlying build system of `dh_auto_install` command can now ensure minimal permissions (`chmod -R u+rwX`).',
			"howtofix" => 'Third-party build systems will need a code change to support this. For `debhelper` provided build systems that **supports** `install` (such as `autoconf`, `meson`, `cmake`), this is done by default and any `execute_after_dh_auto_install` to run `chmod -R u+rwX` can be removed.',
		},
		{
			"title"               => 'The `debhelper` configuration files without a package prefix (`debian/install`) will now cause a warning for source packages that build 2+ binary packages. Will become an error in compat 15.',
			"is_relevant"         => sub {return not _is_single_binary_package();},
			"auto_migration"      => "debputy migrate-from-dh --migration-target=dh-package-prefixed-config-files",
			"auto_migration_deps" => ['debputy (>= 0.1.73~)', 'debhelper (>= 13.26~)'],
			"howtofix"            => "Rename files like `debian/install` to `debian/<PACKAGE>.install` (etc.). Notable exceptions are `debian/changelog`, `debian/NEWS` and `debian/copyright`.",
		},
		{
			"title"       => 'The `debhelper` configuration files using "name"-segment and without a package prefix (`debian/install`) will now cause a warning. Will become an error in compat 15.',
			"is_relevant" => \&_uses_name,
			"howtofix"    => "Rename files like `debian/bar.service` to `debian/<PACKAGE>.bar.service` (etc.) where you have `dh_command --name bar`.",
		},
		{
			"title"    => 'The `debhelper` configuration files no longer support "name"-segment and architecture restrictions by default. Helpers must explicitly request support.',
			"howtofix" => 'Most packages will be unaffected. However, if the package uses a "name"-segment (`dh_foo --name ...`) or architecture restrictions in the filename, then the helper may no longer support it. Approach the maintainer of the tool and request support if it is relevant.',
		},
		{
			"title"       => 'The `cmake` build system now passes `-DCMAKE_BUILD_RPATH_USE_ORIGIN=ON`',
			"is_relevant" => sub {return _uses_build_system('cmake');},
			"howtofix"    => 'Most packages will be unaffected. However, check that the package still works as expected if it relies on `RPATH`.',
			"careful"     => "Silent misbuilds (might build successful, but the binary may fail at runtime due to `RPATH` changes)",
		},
		{
			"title"       => 'The `cmake` build system now passes `ASFLAGS` from `dpkg-buildpackage` as `ASMFLAGS`',
			"is_relevant" => sub {return _uses_build_system('cmake');},
			"howtofix"    => 'Most packages will be unaffected as the default for `ASFLAGS` is empty. However, depending on the value of various `DEB_*` variables, it might be non-empty and will now be picked up by `cmake`. Additionally, you may now be able to remove manual passing of `ASFLAGS` to `cmake`.',
			"careful"     => "Silent misbuilds (might build successful, but the binary may fail at runtime due to `ASMFLAGS` containing flags thát affects runtime behavior)",
		},
		{
			"title"       => 'The `cmake` build system now uses `cmake --install` rather than `make install` in `dh_auto_install`',
			"is_relevant" => sub {return _uses_build_system('cmake') && _has_hook_target('override_dh_auto_install')},
			"howtofix"    => 'Check the override target for `dh_auto_install` for parameters passed to `make install` and replace them with `cmake --install` compatible options',
		},
		{
			"title"       => 'The `meson` build system now passes `--auto-features=enabled`',
			"is_relevant" => sub {return _uses_build_system('meson')},
			"howtofix"    => 'Check if any `meson` features need to be explicitly disabled.',
		},
		{
			"title"       => 'The `meson+ninja` build system now invokes `meson install` instead of `ninja install` during `dh_auto_install`',
			"is_relevant" => sub {return _uses_build_system('meson+ninja') && _has_hook_target('override_dh_auto_install')},
			"howtofix"    => 'Check the override target for `dh_auto_install` for parameters passed to `ninja install` and replace them with `meson install` compatible options',
		},
		{
			"title"       => 'The `debian/compat` file has been replaced by `X-DH-Compat`.',
			"is_relevant" => sub {return _has_file('debian/compat')},
			"howtofix"    => 'Replace `debian/compat` with `debhelper-compat (= 14)` in `Build-Depends` for stable compat levels. For experimental ones, use the new `X-DH-Compat` field instead',
			"validate"    => "A successful rebuild is sufficient to confirm whether this item is a problem.",
			'lintian'     => '#1072741',
		},
		{
			"title"    => 'The `dh_installtmpfiles` now passes `--remove` on package removal and `--purge` on package purge to `systemd-tmpfiles.',
			"howtofix" => 'Most packages should be unaffected by this. The purge side is conditionally guarded on the `--purge` (`systemd` v256 or later).',
		},
		{
			"title"    => 'The `dh_lintian` no longer accepts architecture specific `lintian-overrides` files for `Multi-Arch: same` packages.',
			"is_relevant" => sub { return _has_pkgfile("lintian-overrides"); },
			"howtofix" => "If affected, merge the `lintian-overrides` files into a single `lintian-overrides` file that uses `lintian`'s architecture specific overrides",
			"validate" => "A successful rebuild is sufficient to confirm whether this item is a problem.",
		},
	],
	14 => [
		{
			"title"       => "The `single-binary` add-on is no longer activated implicitly.",
			"is_relevant" => sub {return _is_single_binary_addon_candidate_pending_opt_in()},
			"howtofix"    => "Ensure the resulting binary package is not missing content. Any `--without single-binary` passed to `dh` can now be removed without triggering the warning from compat 14.",
			"careful"     => "Rebuild might cause files to be missing in the resulting binary package.",
		},
		{
			"title"       => 'The `debhelper` configuration files without a package prefix (`debian/install`) will now cause an error for source packages that build 2+ binary packages.',
			"is_relevant" => sub {return not _is_single_binary_package();},
			"howtofix"    => "Rename files like `debian/install` to `debian/<PACKAGE>.install` (etc.). Notable exceptions are `debian/changelog`, `debian/NEWS` and `debian/copyright`.",
		},
		{
			"title"       => 'The `debhelper` configuration files using "name"-segment and without a package prefix (`debian/install`) will now cause an error.',
			"is_relevant" => \&_uses_name,
			"howtofix"    => "Rename files like `debian/bar.service` to `debian/<PACKAGE>.bar.service` (etc.) where you have `dh_command --name bar`.",
		},
	]
);

sub _linkify {
	my ($arg) = @_;
	if ($arg =~ m/^man:(\S+)[(]([^)]+)[)]$/) {
		my ($name, $section) = ($1, $2);
		return "[${arg}](https://manpages.debian.org/${name}.${section})";
	}
	if ($arg =~ m/^#(\d+)$/) {
		return "[${arg}](https://bugs.debian.org/$1)";
	}
	return $arg;
}

sub _process_upgrade_items {
	my ($upgrade_items) = @_;
	my (@relevant, @irrelevant);
	for my $item (@{$upgrade_items}) {
		my @template = (
			"#### $item->{title}",
			'',
			'Checklist:',
			'',
			' * [ ] Reviewed if this item is relevant.',
			' * [ ] Performed the relevant migration (if this item is relevant and anything was needed).',
			'',
		);
		if (defined(my $auto_migration = $item->{'auto_migration'})) {
			my $auto_migration_deps = $item->{'auto_migration_deps'};
			my @commands;
			if (defined($auto_migration_deps)) {
				my $deps = escape_shell(join(", ", @{$auto_migration_deps}));
				push(@commands, "apt satisfy ${deps}");
			}
			push(@commands, $auto_migration);
			push(@template,
				'Tool-assisted migration:',
				'',
				'```shell',
				'',
				# We need an extra newline for proper formatting with `markdown`
				(map { "    $_\n" } @commands),
				'```',
				'',
			);
		}
		if (defined(my $howtofix = $item->{'howtofix'})) {
			push(@template, "Manual migration: $howtofix", '');
		}
		if (defined(my $careful = $item->{'careful'})) {
			push(@template, "**Risk** if not processed correctly: ${careful}", '');
		}
		if (defined(my $validate = $item->{'validate'})) {
			push(@template, "How to validate if this item is relevant: ${validate}", '');
		}
		if (defined(my $lintian = $item->{'lintian'})) {
			my $link = _linkify($lintian);
			push(@template, "Lintian: ${link}", '');
		}
		if (defined(my $docs = $item->{'docs'})) {
			push(@template, "Related docs:", '');
			for my $doc (map { _linkify($_) } @{$docs}) {
				push(@template, " * ${doc}");
			}
			push(@template, '');
		}
		my $has_heuristic = exists($item->{"is_relevant"}) ? 1 : 0;
		my $is_relevant_heuristic = $item->{"is_relevant"} // sub { return 1; };
		my $is_relevant = $is_relevant_heuristic->();
		if ($has_heuristic) {
			my $result = $is_relevant ? "Manual review needed" : "Probably irrelevant to this package";
			push(@template, "Heuristic-Result: ${result}");
		} else {
			push(@template, "Heuristic-Result: N/A, manual review required");
		}
		push(@template, '');

		my $processed_item = join("\n", @template);
		if (not $has_heuristic or $is_relevant) {
			push(@relevant, $processed_item);
		} else {
			push(@irrelevant, $processed_item);
		}
	}
	return (\@relevant, \@irrelevant);
}


sub compat_upgrade_checklist {
	_assert_debian_control_exists();
    _allow_unsafe_execution();
    require Getopt::Long;
    Getopt::Long::config('no_ignore_case');
	my $highest_stable = Debian::Debhelper::Dh_Lib::HIGHEST_STABLE_COMPAT_LEVEL;
	$highest_stable //= Debian::Debhelper::Dh_Lib::MAX_COMPAT_LEVEL;
	my $target_compat = $highest_stable;
	my %options = (
		"target-compat=i" => \$target_compat,
	);
	my (undef, $declared_compat, undef) = Debian::Debhelper::Dh_Lib::get_compat_info();
    Getopt::Long::GetOptionsFromArray(\@ARGV, %options)
        or error("Could not parse the arguments");
	if (@ARGV) {
        my $value = $ARGV[0];
        error("$COMMAND: No non-options supported - please remove ${value}");
    }
	if ($target_compat > Debian::Debhelper::Dh_Lib::MAX_COMPAT_LEVEL) {
		my $max_level = Debian::Debhelper::Dh_Lib::MAX_COMPAT_LEVEL;
		warning("The compat level ${target_compat} is higher than the max level (${max_level}) supported by this version of debhelper. ");
		exit(0);
	}
	if ($target_compat <= $declared_compat) {
		if ($target_compat != $declared_compat) {
			error("Going from compat ${declared_compat} to ${target_compat} would be a downgrade, which is not supported");
		}
		warning("The package is already at ${target_compat}.");
		exit(0);
	}
	if ($declared_compat < Debian::Debhelper::Dh_Lib::MIN_COMPAT_LEVEL and not exists($UPGRADE_CHECKLIST_WHEN_UPGRADING_FROM{$declared_compat})) {
		error("The compat level ${declared_compat} is obsolete and has no upgrade checklist. Please review `man 7 debhelper-obsolete-compat` for a checklist.");
	}
	my $source = sourcepackage();
	my $DH_TOOL_VERSION = "(unknown; git checkout)";
	eval {
		require Debian::Debhelper::Dh_Version;
		$DH_TOOL_VERSION = $Debian::Debhelper::Dh_Version::version;
	};

	my @checklist = (
		"# Upgrade checklist for ${source}\n",
		'',
		"This is an auto-generated `debhelper` compat upgrade checklist for ${source}.",
		"It was generated by `dh_assistant` version ${DH_TOOL_VERSION}",
		'',
		"The upgrade checklist will attempt to filter out irrelevant items. However, the",
		"detection code is not 100% reliable. Be careful with trusting it blindly.",
		'',
		'This checklist is based on the full checklist in ' . _linkify('man:debhelper-compat-upgrade-checklist(7)') . '.',
		'',
		"Target compat was: ${target_compat}",
		'',
		'[man:debhelper-compat-upgrade-checklist(7)]: https://manpages.debian.org/unstable/debhelper/debhelper-compat-upgrade-checklist.7.en.html',
		'',
	);
	for my $compat (($declared_compat+1..$target_compat)) {
		my $prev_compat = $compat - 1;
		my $items = $UPGRADE_CHECKLIST_WHEN_UPGRADING_FROM{$prev_compat};
		my $compat_warning = "";
		$compat_warning = " [EXPERIMENTAL]" if $compat > $highest_stable;
		push(@checklist,
			"## Upgrading from ${prev_compat} to ${compat}${compat_warning}",
			'',
		);
		if (not defined($items)) {
			push(
				@checklist,
				"Sorry, no upgrade checklist generator was created for ${prev_compat} to ${compat}.",
				'Please review [man:debhelper-compat-upgrade-checklist(7)] for the checklist.',
				'Patches/contributions to replace this placeholder with a proper upgrade checklist is welcome.',
				'',
			);
			next;
		}
		my ($relevant_items, $irrelevant_items) = _process_upgrade_items($items);

		if (@{$relevant_items}) {
			push(
				 @checklist,
				"### Items that requires manual review",
				'',
				'The items listed here are items that introspection found "likely" to be relevant',
				"to `${source}` OR there was no automated way of telling the package was affected.",
				'Please review the items, confirm whether they apply and then fix them',
				'',
				@{$relevant_items}
			);
		}
		if (@{$irrelevant_items}) {
			push(
				 @checklist,
				"### Items that might not be relevant",
				'',
				'The items listed here are items that introspection found "unlikely" to be relevant',
				"to `${source}`. However, `dh_assistant`'s ability to introspect correctly is limited",
				"and may be inaccurate. Please skim the list to see if any of the items might be relevant.",
				'',
				@{$irrelevant_items}
			);
		}
	}

	print(join("\n", @checklist) . "\n");
	return;
}


sub detect_unknown_hook_targets {
    _assert_debian_control_exists();
    _allow_unsafe_execution();
    my $distance_func = _load_levenshtein();
    require Getopt::Long;
    Getopt::Long::config('no_ignore_case');
    require Debian::Debhelper::SequencerUtil;
    my $output_format = "text";
    my (@addon_requests, %all_overrides, %unknown_hooks);
    my $lint_exit = 1;
    my %options=(
        "output-format=s"                      => \$output_format,
        "linter-exit-code!"                    => \$lint_exit,
        "with=s" => sub {
			my ($option, $value) = @_;
			push(@addon_requests, map { "+${_}" } split(",", $value));
		},
		"without=s" => sub {
			my ($option, $value) = @_;
			push(@addon_requests, map { "-${_}" } split(",", $value));
		},
	);

    Getopt::Long::GetOptionsFromArray(\@ARGV, %options)
        or error("Could not parse the arguments");
    if ($output_format ne 'text' and $output_format ne 'json') {
        error("--output-format must be either text or json\n");
    }
    if (@ARGV) {
        my $value = $ARGV[0];
        error("$COMMAND: No non-options supported - please remove ${value}");
    }
    my $explicit_targets = _load_hook_targets();
    my %missing_targets = map {
        $_ => 1
    } grep {
        $_ ne 'debhelper-fail-me' and !m{^(?:debian/rules|create-stamp)}
    } keys(%{$explicit_targets});

    my ($activate_commands, $disabled_commands, $unloadables) = _all_sequence_commands(1, @addon_requests);
    my @hook_targets_for_disabled_commands;
    my @all_commands = (@{$activate_commands}, keys(%{$disabled_commands}));
    for my $command (@all_commands) {
        for my $variant (_hook_target_variants($command)) {
            $all_overrides{$variant} = 1;
            if (exists($missing_targets{$variant}) and exists($disabled_commands->{$command})) {
                push(@hook_targets_for_disabled_commands, [$variant, $disabled_commands->{$command}]);
            }
            delete($missing_targets{$variant});
        }
    }
    my @variants = sort(keys(%all_overrides));
    for my $target (keys(%missing_targets)) {
        my @closest_variants;
        my $closest_variant_distance = 9999;
        for my $variant (@variants) {
            next if abs(length($target) - length($variant)) > 3;
            my $dist = $distance_func->($target, $variant);
            next if $dist > $closest_variant_distance or $dist > 3;
            if ($dist < $closest_variant_distance) {
                $closest_variant_distance = $dist;
                @closest_variants = ();
            }
            push(@closest_variants, $variant);
        }
        next if not @closest_variants and $target !~ m{^(?:override|execute_before|execute_after)_};
        @closest_variants = sort(@closest_variants);
        $unknown_hooks{$target} = \@closest_variants;
    }

    if ($output_format eq 'json') {
        my (@hook_target_data, @disabled_targets_data);
        for my $target (sort(keys(%unknown_hooks))) {
            my $options = $unknown_hooks{$target};
            my (undef, $filename) = @{$explicit_targets->{$target}};
            push(@hook_target_data, {
                'target-name' => $target,
                'filename'  => $filename,
                'candidates'  => $options,
            });
        }
        for my $rm_data (@hook_targets_for_disabled_commands) {
            my ($target, $removed_by_sequence) = @{$rm_data};
            my (undef, $filename) = @{$explicit_targets->{$target}};
            my $data =  {
                'target-name' => $target,
                'filename'    => $filename,
            };
            $data->{'removed-by'} = $removed_by_sequence if $removed_by_sequence;
            push(@disabled_targets_data, $data);
        }
        my %result = (
            "unknown-hook-targets"               => \@hook_target_data,
            "hook-targets-for-disabled-commands" => \@disabled_targets_data,
        );
        if (@{$unloadables}) {
            my @issues;
            for my $addon (@{$unloadables}) {
                push(@issues, {
                    "issue" => "load-addon",
                    "addon" => $addon,
                });
            };
            $result{'issues'} = \@issues;
        }
        _output(\%result);
    } elsif ($output_format eq 'text') {
        for my $target (sort(keys(%unknown_hooks))) {
            my $options = $unknown_hooks{$target};
            my (undef, $filename) = @{$explicit_targets->{$target}};
            my $help = '';
            if (@{$options}) {
                if (scalar(@{$options}) == 1) {
                    my $name = $options->[0];
                    $help = " Likely a typo of ${name}";
                } else {
                    my $names = join(', ', @{$options});
                    $help = " Likely a typo of one of ${names}";
                }
            }
            print("The hook target ${target} in ${filename} does not seem to match any known commands. ${help}\n");
        }
        if (@{$unloadables}) {
            my $addon_names = join(" ", @{$unloadables});
            print("\n");
            warning("Incomplete result. The following sequence add-ons could not be loaded: $addon_names");
        }
    } else {
        error("Internal error: Missing case for ${output_format}");
    }
    if ($lint_exit && (%unknown_hooks or @{$unloadables})) {
        exit(EXIT_CODE_LINT_ISSUES_FOUND);
    }
    exit(0);
}

sub detect_hook_targets {
    if (@ARGV) {
        error("$COMMAND: No arguments supported (please remove everything after the command)");
    }
    _assert_debian_control_exists();
    _allow_unsafe_execution();
    my $explicit_targets = _load_hook_targets();
    my (%result, @targets, @unverifiable_commands, %seen_cmds);
    while (my ($target, $rule_details) = each(%{$explicit_targets})) {
        next if $target !~ m{^(?:execute_before_|execute_after_|override_)(\S+?)(-indep|-arch)?$};
        my ($command, $archness) = ($1, $2);
        my $param;
        if ($archness) {
            $param = ($archness eq '-arch') ? '-a' : '-i' ;
        }
        my ($non_empty, $filename) = @{$rule_details};

        my $target_info = {
            'target-name'           => $target,
            'command'               => $command,
            'package-section-param' => $param,
            'is-empty'              => $non_empty ? JSON::PP::false : JSON::PP::true,
            'filename'              => $filename,
        };
        push(@targets, $target_info);
        push(@unverifiable_commands, $command) if not exists($seen_cmds{$command}) and not _in_path($command);
        $seen_cmds{$command} = 1;
    }
    $result{'hook-targets'} = \@targets;
    $result{'commands-not-in-path'} = \@unverifiable_commands;
    _output(\%result);
}

sub dh_assistant_restore_file_on_clean {
    init(inhibit_log => 1);
    if (not @ARGV) {
        error("At least one file name is required");
    }
    for my $file (@ARGV) {
        lstat($file);
        if ( ! -f _ ) {
            error("The path ${file} was a symlink. It must be a file; not a symlink to a file") if -l _;
            error("The path ${file} does not exist") if not -e _;
            error("The path ${file} was not a file and this command only supports files");
        }
        if ($file =~ m{[.][.]}) {
            # Someone can provide a patch when there is a use-case for "..foo".
            # Said patch will need to ensure the file is inside the package root dir.
            error("Files containing \"..\" (which ${file} does) are not supported.");
        }
        if ($file =~ m{^/}) {
            error("Files must be relative to the package root (which ${file} was not)")
        }
        if ($file =~ m{^\.} or $file =~ m{/CVS/} or $file =~ m{/\.}) {
            error("Cowardly refusing to track hidden files / version control files (${file}).");
        }
        Debian::Debhelper::Dh_Lib::restore_file_on_clean($file)
    }
}

sub log_installed_files_cmd {
    my $on_behalf_of = 'manually-via-dh_assistant';
    init(
        options => {
            'on-behalf-of-cmd=s' => \$on_behalf_of,
        },
        inhibit_log => 1,
    );
    if (index($on_behalf_of, '/') >= 0) {
        error('The value for --on-behalf-of-cmd must not contain slashes');
    }
    if (@{$dh{DOPACKAGES}} != 1) {
        error('The log-installed-files command must act on exactly one package (use -p<pkg> to define which)');
    }
    my $package = $dh{DOPACKAGES}[0];
    for my $arg (@ARGV) {
        $arg =~ tr:/:/:s;
        if (! -e $arg) {
            warning("The path ${arg} does not exist - double check it is correct. Note: it will recorded anyway.");
        }
    }
    log_installed_files({
        'package'   => $package,
        'tool_name' => $on_behalf_of,
    }, @ARGV);
}

sub supports {
    my ($command, @more) = @ARGV;
    if (@more or not defined($command)) {
        error("$COMMAND: Please provide exactly one argument");
    }
    exit(0) if exists($COMMANDS{$command});
    exit(2);
}

if (not defined($COMMAND)) {
    error('Usage: ' . basename($0) . ' <command>');
}
my $handler = $COMMANDS{$COMMAND};
if (not defined($handler)) {
    warning("Arguments/options must not be the first argument (except for --help)")
        if $COMMAND =~ m/^-/;
    my $available_cmds = join(' ', sort(grep { $_ ne '-h' and $_ ne '--help' and $_ ne 'help' } keys(%COMMANDS)));
    error("Unknown command: $COMMAND. Use \"help\" or \"--help\" as first argument for usage. Available commands: ${available_cmds}");
}

$handler->();

=head1 SEE ALSO

L<debhelper(7)>

This program is a part of debhelper.

=cut

1;