-copyright More...

Detailed Description

-copyright

-since-version

Gate: one canonical copyright + SPDX attribution, same place in every file.

Two forms, because this tree has two comment conventions and the attribution
belongs where each convention already puts its metadata.

C family (a Doxygen ``@file`` block)
------------------------------------
The attribution lives INSIDE the file-header block, as its closing tag group,
never in a separate comment above it::

    /**
     * @file foo.c
     * @brief ...
     * @details ...
     *
     * @author Brighton Sikarskie          <- kept when present
     * @date 2026-04-29                    <- kept when present
     * @copyright Copyright (c) 2026 Brighton Sikarskie
     * SPDX-License-Identifier: MIT
     * @since 0.1.0                        <- kept when present
     */

``@copyright`` immediately followed by the SPDX line is the invariant this
gate enforces, placed as the closing group of the block (before ``@since``
when the file carries one). ``@author`` / ``@date`` / ``@since`` are PRESERVED
exactly as written and are never invented: 2190 of the 2297 C-family files
have never carried ``@author`` or ``@date``, and manufacturing them would be
fabricated provenance, not a header standard.

A standalone ``/* SPDX ... */`` block above the ``@file`` block is a
violation, and ``--fix`` merges it back into the block rather than leaving the
attribution split across two comments.

Linker scripts use a plain (non-Doxygen) leading block, so they carry the bare
``Copyright`` line followed by the SPDX line at the end of that block.

Hash-comment files (shell, python, cmake, just, yaml)
-----------------------------------------------------
No doc-comment convention to live inside, so the attribution leads the file,
immediately after the shebang when there is one::

    #!/usr/bin/env bash
    # SPDX-License-Identifier: MIT
    # Copyright (c) 2026 Brighton Sikarskie

Security-pinned shell and Python entry points put their exact
``SHEBANG-SECURITY`` rationale immediately after this pair. The licence pair
does not move: the combined preamble is shebang, SPDX, copyright, rationale.

Scope is derived from ``lint_targets`` (``git ls-files``), so a new top-level
directory is covered the day it lands. Vendored SOUP, generated tables and
build output are out of scope; ``.md`` is documentation, not code.

Run::

    check-copyright.py FILE [FILE ...]   # named files (pre-commit hook)
    check-copyright.py --all             # every first-party file (gate)
    check-copyright.py --fix --all       # rewrite headers to canonical form
    check-copyright.py --selftest        # prove the rules fire and stay quiet

Exit 0 clean, 1 on a violation or failing selftest, 2 on a collapsed scan.

Enforce ``@since`` Doxygen tags and check their values against VERSION.

Both halves matter: a missing tag is a documentation gap, and a tag naming a
version the project never released is worse, because it looks authoritative.

Two checks combined:

  1. **Presence**: every public declaration in a `.h` under
     ``libs/ra8_*/inc/`` (i.e. every ``ra8_*`` function or static
     inline accessor) must be preceded within the previous 30
     lines by a ``@since`` tag inside its Doxygen block.

  2. **Value**: every ``@since`` tag in any source / header /
     example / test file must use the exact version string in
     the project's top-level ``VERSION`` file. The tolerated
     variants are::

         @since 0.1.0
         @since Version 0.1.0   (legacy STAR-style; still accepted)

     Any other value is flagged.

Usage:

    # explicit file list (used by pre-commit hook):
    python3 scripts/checks/check-since-version.py path/to/file.h ...

    # full repo sweep (CI):
    python3 scripts/checks/check-since-version.py --all

The script always reads ``VERSION`` from the repo root, so a
single bump there propagates everywhere.

Exit code:
    0  no issues
    1  presence or value mismatch found
    2  CLI usage error