Recent commits to derivepassphrase.git (8154b0ff2bedbc2a7ec7d812091067084555aa31)

Add an actual derivepassphrase-vault(1) manpage, plus better manpage contents

2024-12-25T20:55:45+01:00

The barebones HTML "manpage" for `derivepassphrase` was essentially an
HTML-ized version of the help text.  In particular, the option
descriptions only contained the one-line help text, and many typical
sections (FILES, ENVIRONMENT, EXAMPLES, DIAGNOSTICS, AUTHOR, BUGS) were
missing.

This commit contributes a proper manpage, in `*roff`/`mdoc` format.  It
was authored using guidance from the `groff_mdoc` documentation, the
only sensible-appearing authoritative source on manpage style issues.
(Perl's `perlpodstyle`, `groff_man` and `groff_man_style` were also
consulted, but ultimately disregarded.)  The content changes were also
folded back into the HTML version, save for some styling choices that
aren't possible in the `*roff` version.  In particular, both versions
are hand-written, and manually synchronized with each other.

The manpages use the option group headings "Passphrase generation" and
"Compatibility and extension options" instead of "Password generation"
and "Options concerning compatibility with other tools", for better text
flow.  Accordingly, this phrasing has been adapted in
`derivepassphrase_vault` as well.
</pre>

Make the mutually exclusive options helper function print the correct parameter name

2024-12-25T18:59:32+01:00

The `click.Parameter.human_readable_name` attribute yields the metavar
for arguments, and the function parameter name for options.  The
documentation calls the latter the "name" for the option, perhaps under
the assumption that you would never pass an explicit parameter name to
the option decorator.  I disagree with this, it is horrible design:
sometimes the value is usable as a function parameter (options),
sometimes it isn't (arguments), and vice versa for constructing
a command-line, so it is neither usable as a command-line parameter
display name nor as a function parameter name.

So what *is* it even good for...?

Include our own logic to select an appropriate display name for our
options.  This requires querying `click.Parameter` attributes that
should be public, but are internal.  Why...?!
</pre>

Add small fixes to changelog, docstrings and variable names

2024-12-25T17:15:23+01:00

</pre>

Instruct `coverage` to record the test function for each covered line

2024-12-21T01:02:34+01:00

Enable the standard dynamic context setting `test_function` for
`coverage`.  This is immensely helpful for debugging whether and which
tests trigger or don't trigger a certain branch of code in
a multi-branch block (`if`/`elif`/`else`, `match`/`case` blocks,
dispatch tables, etc.).
</pre>

Fix formatting, some coverage pragmas and some linting rules in tests

2024-12-21T00:57:49+01:00

Aside from formatting fixes, disable the E501/line-too-long and
C419/unnecessary-comprehension-in-call linting rules in tests, where
they hinder debuggability of the tests.  (See embedded comments for full
rationale.)  Furthermore, make `coverage` recognize `@overload` lines
automatically as lines that should not be included in coverage, like
`assert False` and friends.
</pre>

Support exporting the `vault` configuration as a POSIX shell script

2024-12-21T00:23:33+01:00

When exporting `vault` configurations via `--export`, a new option
`--export-as=FORMAT` allows selecting the export format (defaulting to
`json`).  Setting `FORMAT` as `sh` selects the new POSIX shell script
export format, which yields a sh(1)-compatible script to reimport the
existing configuration as a series of calls to the `derivepassphrase`
command.

Because the output is very regular, the test suite also includes an
interpreter specifically for the sh(1) subset emitted during an `sh`
export, on top of the usual adaptations to existing tests for the new
functionality.
</pre>

Allow unsetting settings when configuring `vault`

2024-12-20T17:00:48+01:00

When configuring a `vault` service, or the global settings, a new
configuration option `--unset FIELD` will unset the specified `FIELD`
from the service or global settings prior to and addition to applying
the requested settings changes.  This way, the user can update all
settings on the command-line (except for the "notes") without manually
editing and reimporting a configuration export.  (It is permissible to
only unset settings, without applying any other configuration changes.)
</pre>

Rework `ConfigManagementStateMachine` rules for higher data generation success rates

2024-12-20T15:06:20+01:00

Lower the failure/retry rate for data generation by moving all data
generation into initialization rules and by removing data restrictions
on rule inputs as far as possible, turning the rule effectively into
a no-op if necessary.

The only currently remaining operation with notable retry rate is the
top-level rule selection.
</pre>

Fix empty key handling in `vault` config, and harmonize warning text

2024-12-20T11:39:45+01:00

Correctly handle empty `key` settings in the `vault` configuration: if
at the global level, it is equivalent to eliding the setting, but at the
service level, it explicitly disables key usage (even if a global key is
set).  This implies that both cases need different cleanup steps.

Harmonize the warning message for ineffective passphrases for services:
always include the affected service name.

If during configuration import we find a key shadowing a passphrase,
issue the same ineffective passphrase warning as would happen during
interactive configuration or interactive use.

(The tests need minor modifications and reparametrization to continue to
cover all warning cases.)
</pre>

Rewrite incompatible option checking for more readability

2024-12-19T15:47:42+01:00

</pre>