Add --strict/-W flag to codelinks analyse command for treating warnings as errors

[m-anderson1313]

Feature Request

Add a command-line flag (e.g., --strict or -W) to codelinks analyse that converts
all warnings into build failures, similar to sphinx-build's -W flag.

Use Case

When integrating codelinks into CI/CD pipelines, warnings should fail the build to
enforce traceability quality gates. Currently, warnings are printed but do not cause
non-zero exit codes, allowing broken markers to pass automated checks.

Current Workaround

I've implemented a grep search to check the log for warnings, and fail the process if warning is found.

[ubmarco]

Proposal: -W / --strict for codelinks analyse

How exit codes work today

codelinks analyse runs standalone (no Sphinx). It never sets an exit code
explicitly, so it inherits the Typer/Click defaults:

Exit code	When
0	Ran to completion — even if warnings were printed
1	Unhandled exception / crash
2	Bad CLI usage or invalid config (typer.BadParameter)

Log levels are not mapped to exit codes. Every warning is printed to stderr
and the command still exits 0; only crashes (1) and config/usage errors
(2) are non-zero. That is exactly why the current workaround is grepping the
log for the word "warning".

Which warnings analyse can emit

There are 11 distinct warning subtypes, in two groups:

git-metadata (often just "you ran outside a git checkout"):
git_root, git_config, git_remote, git_head, git_ref, git_host

marker / one-line quality (the traceability problems this issue targets):
too_few_fields, too_many_fields, newline_in_field,
missing_square_brackets, not_start_or_end_with_square_brackets

Every one already carries a subtype internally, but the surfaced slug is
inconsistent and standalone doesn't expose it at all:

Group	Slug in Sphinx today	Standalone today
git-metadata	codelinks.git_root, …	not surfaced
marker/one-line	need.too_few_fields, …	not surfaced

So a clean, suppressible registry means normalizing everything under one
namespace. Proposed (hierarchical, so a parent silences the whole family):

Subtype	Proposed slug
git_*	codelinks.git.root, codelinks.git.config, codelinks.git.remote, codelinks.git.head, codelinks.git.ref, codelinks.git.host
marker	codelinks.marker.too_few_fields, codelinks.marker.too_many_fields, codelinks.marker.newline_in_field, codelinks.marker.missing_square_brackets, codelinks.marker.not_start_or_end_with_square_brackets

Proposal

1. -W / --strict flag. Without it, behavior is unchanged (exit 0). With
it, if any non-suppressed warning was emitted during the run, analyse exits
1 — mirroring sphinx-build -W.

2. Suppressible slugs (the escape hatch). Because -W covers all
warnings, there must be a way to say "don't fail on codelinks.git.root, I know
I'm running outside a repo." Sphinx already offers this via its native
suppress_warnings; standalone needs an equivalent.

To avoid maintaining two lists, suppression is configured once in the
[codelinks] config that both frontends already read:

[codelinks]
suppress_warnings = ["codelinks.git", "codelinks.marker.too_many_fields"]

• Standalone reads this key and drops matching warnings — not printed, not
  counted (same semantics as Sphinx).
• Sphinx folds these slugs into its own suppress_warnings at
  config-inited, so Sphinx's native suppression and sphinx-build -W honor
  the identical list. conf.py's native suppress_warnings keeps working
  additively for docs-only users.

Matching is hierarchical like Sphinx: codelinks silences everything,
codelinks.git the whole git-metadata family, codelinks.git.root just one.

3. Exit-code contract (this is the "log level → exit code" mapping):

Situation (standalone)	without -W	with -W
Completed, no warnings	0	0
Completed, ≥1 non-suppressed warning	0	1
Uncaught exception / crash	1	1
Usage / config error (BadParameter)	2	2

Backward compatibility

Default behavior is unchanged — no flag means exit 0 as before. -W is
strictly opt-in. The only behavioral change for existing users is the slug
rename (need.* → codelinks.marker.*, codelinks.git_* → codelinks.git.*);
those slugs are effectively undocumented today, so the blast radius is small.

Open for discussion

• Exit 1 vs a dedicated code. This reuses 1 like sphinx-build, so -W
  failures and crashes share a code. A dedicated code (e.g. 3) could
  distinguish "broken markers" from "tool crashed" if CI wants that.
• Ad-hoc CLI override (optional). A repeatable
  --suppress-warning codelinks.git option could layer on top of the config
  list for one-off CI runs, without editing the config file.
• Implementation seam. Route all standalone warnings through the existing
  logging facade (get_logger(...).warning(..., subtype=...)) so a single
  choke point can both count and suppress by slug — today the git warnings drop
  the subtype and the one-line warnings bypass the facade.