Relative-link checker for NON-``.md`` link targets (the class ``tools/link_check.py`` is blind to).
Purpose
-------
``tools/link_check.py`` only validates markdown links whose target ends in ``.md``
(``_is_md_ref``), so it is BLIND to dead relative links pointing at ``.py`` (or any
other non-``.md``) files — exactly the class a code move breaks (e.g. the many
``.py``-target links in ``CONTRACTS.md`` / ``TOOL_CONTRACT.md``). This companion
sweep resolves every relative, non-URL, non-anchor markdown link whose target is a
file with a non-``.md`` extension and reports the ones that do not exist on disk.
Usage: ``python oc_chat/scripts/py_link_check.py [--root DIR] [--json]``. ``--root``
defaults to the repository root inferred from this file's location, so the script
scans the tree it travels with (post-move it is invoked from the monorepo root as
``python oc_chat/oc_chat/scripts/py_link_check.py``). Exit ``0`` when no broken
non-``.md`` relative file links are found; ``1`` otherwise. The §2.2 gate is
baseline-relative: fail only on NEW entries vs the recorded pre-move baseline.
Responsibilities
----------------
- Enumerate ``*.md`` files under a scan root (skipping VCS internals).
- Extract inline-link targets and normalise them (strip titles, fragments,
queries, ``:NN`` line locators, percent-encoding).
- Resolve each non-``.md`` relative file target and report the unresolved ones.
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
L2 - CLI lifecycle (scan start / result)
L3 - per-root resolution details
L4 - per-file / per-link tracing
Contracts
---------
- Imports ONLY ``oc_diagnostics`` (structured logging) — never ``oc_chat`` — so it
is immune to the ``sys.path[0] = scripts/`` ``import oc_chat`` editable-install
shadowing trap (plan 151 §2.3); the scan logic is driven entirely by the ``--root``
filesystem path, not by imports, so it runs identically pre- and post-move.
- Read-only: never writes to the scanned tree.
- Deterministic: results are sorted; identical tree -> identical output.
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
| str | None oc_chat.scripts.py_link_check._clean_target |
( |
str | raw | ) |
|
|
protected |
Normalise a link body to a bare relative file path, or ``None`` to skip.
Strips ``<...>`` wrappers, an optional ``"title"`` suffix, ``#anchor`` /
``?query`` fragments, a trailing ``:NN`` source-line locator, and percent
encoding. Returns ``None`` for URLs, pure anchors, absolute paths, extension-less
targets (directory/section references), and ``.md`` targets (owned by
``tools/link_check.py``).
Definition at line 94 of file py_link_check.py.
1.15.0