coderef

Regex-driven references in source code — resolved, click-opened, and
verified identically from VSCode and from CI. A .coderef.jsonc config
declares the patterns; the same engine runs inside the editor (via WASM,
in-process) and inside the Rust CLI binary (for pre-commit and CI).

The working specification is DESIGN.md; this README is
the elevator pitch.

# Click-to-open in VSCode; verified by pre-commit; same regex engine in both.
#
# TODO(@marcus): swap to argon2id — JIRA(SEC-87) tracks it.
# DOCREF(/docs/security/hashing) explains the threat model.
# RFC(8259) is the JSON spec.

# IfChange / ThenChange enforces co-modification across files:
# IfChange('hash-params')
HASH_PARAMS = {"memory_kib": 19456, "iterations": 2, "parallelism": 1}
# ThenChange(/docs/security.md:hash-params, /tests/test_auth.py:hash-params)

Patterns declare their regex, the URL or local-file they resolve to,
how they're verified, what category they belong to, and what should
happen on hover. Same regex flavour, same semantics, in both hosts.

Planning horizon

Version	Theme
v0.1	Minimum viable: pattern engine + HTTP verifier + click-to-open. WASM-shared core (no engine divergence between editor and CLI).
v0.2	Coupled-change (`IfChange`/`ThenChange`) + categories + references browser + commit-message linting + anchor verification for in-repo Markdown + block-on-marker (`DO NOT COMMIT` / `NOCOMMIT` source guards via `kind: "block"`).
v0.3	Multi-target references + full network profiles + auto-upgrade codemod (`coderef upgrade`) + visual config editor + external-URL anchor verification.
v0.4	LSP server mode + composable coupled-change IDs + git-submodule pass-through.

Anything past v0.4 is deliberately not planned in detail (see
DESIGN.md §20.5). The full per-version scope is in
DESIGN.md §20.

Repo layout

DESIGN.md — the working spec. Source of truth.
AGENTS.md — conventions every contributor (human or
AI agent) follows. Includes the markdown table-alignment rule and a
pointer to the script that enforces it.
CLAUDE.md — entry-point for Claude Code; redirects
to AGENTS.md.
tools/align-md-tables.py — the
table-alignment script.
.coderef.jsonc — the project's own coderef
config; the engine dogfoods against this on every CI run.
LICENSE — Apache 2.0.

Pre-commit hooks (v0.1)

The .pre-commit-hooks.yaml declares the hook shape consumers
will install once the npm wrapper ships a binary (v0.2). For v0.1
the dogfood-able path is language: system against a locally-built
binary; see .pre-commit-config.yaml
for the working example used by this repo's own CI:

- id: coderef-doctor
  entry: cargo run --quiet --release --bin coderef -- doctor --no-scan .
  language: system

- id: coderef-check
  entry: cargo run --quiet --release --bin coderef -- check .
  language: system

What `coderef` is not

Not a TODO tracker — it resolves the references you put in source,
it doesn't manage them.
Not a tag-uniqueness enforcer (tagref
already covers that niche).
Not a generic markdown link checker
(lychee covers that).
Not an AST-aware refactoring tool — coderef upgrade is regex-only
by design; for AST work, use jscodeshift / ast-grep / comby.

See DESIGN.md §23 for the full out-of-scope list and
the reasoning.

License