justfile

# `default` pipes `just --list` through a small stock-perl filter that clips long recipe
# docs to your terminal width (…) instead of wrapping. Self-contained — no external files;
# falls back to plain `just --list` where perl is absent. Edit the recipes below, not this.
# List available recipes
default:
    @if command -v perl >/dev/null 2>&1; then just --color always --list | perl -CS -Mutf8 -lpe 'BEGIN{($w)=`stty size 2>/dev/null </dev/tty`=~/ (\d+)/; $w||=100; $col=(-t STDOUT && !exists $ENV{NO_COLOR})} s/\e\[[0-9;]*m//g unless $col; (my $v=$_)=~s/\e\[[0-9;]*m//g; if(length($v)>$w){my($o,$n)=("",0); while(length && $n<$w-1){ if($col && s/^(\e\[[0-9;]*m)//){$o.=$1}else{s/^(.)//;$o.=$1;$n++} } $_=$o."…".($col?"\e[0m":"")}'; else just --list; fi

# Build the docgraph binary
[group("build")]
build:
    go build -o docgraph .

# Run the test suite
[group("check")]
test:
    go test ./...

# The exec is LOAD-BEARING, not a smoke test — see the cold-exec footgun in CLAUDE.md:
# a freshly written binary has a new cdhash, so its FIRST exec blocks in dyld for a live
# code-signature assessment (~1s for this binary on macOS). Absorbing it here, where you
# are already waiting on a build, keeps it off the next doc-drift Stop hook.
# Install to the Go bin dir (on PATH), then exec the new binary once
[group("build")]
install:
    #!/usr/bin/env bash
    set -euo pipefail
    go install .
    bin="$(go env GOBIN)"; [ -n "$bin" ] || bin="$(go env GOPATH)/bin"
    "$bin/docgraph" version

# Format all Go files in place
[group("check")]
fmt:
    gofmt -w .

# Non-mutating pre-release gate: gofmt check + vet + tests
[group("check")]
gate:
    #!/usr/bin/env bash
    set -euo pipefail
    unformatted="$(gofmt -l .)"
    if [ -n "$unformatted" ]; then
      echo "✗ gofmt: these files need formatting:" >&2
      echo "$unformatted" >&2
      exit 1
    fi
    go vet ./...
    go test ./...
    echo "✓ gate passed"

# Run on dev with VERSION bumped and committed; the tree must be clean and gate-green.
# NOTES is required and hand-written (default RELEASE_NOTES.md, gitignored). Not `gh
# --generate-notes`: it summarises MERGED PRs, and this repo integrates on the trunk, so it
# emits only a bare "Full Changelog" link — a release with no notes.
# Cut the release for the current VERSION: fast-forward main → tag v<VERSION> → GitHub release
[group("release")]
release notes="RELEASE_NOTES.md":
    #!/usr/bin/env bash
    set -euo pipefail
    version="$(tr -d '[:space:]' < VERSION)"
    tag="v${version}"
    # Check the notes FIRST: everything below this point (tag, push, release) is
    # public and awkward to retract, so a missing notes file must fail before any
    # of it happens, not between the tag push and the release create.
    if [ ! -s "{{notes}}" ]; then
      echo "✗ no release notes at '{{notes}}' — write them, then re-run." >&2
      echo "  Summarise what shipped since the previous tag (features / fixes / docs)," >&2
      echo "  leading with anything that changes how consumers install or invoke docgraph." >&2
      echo "  Pass a different path with: just release <file>" >&2
      exit 1
    fi
    if [ -n "$(git status --porcelain)" ]; then
      echo "✗ working tree is dirty — commit the VERSION bump first" >&2
      exit 1
    fi
    if git rev-parse -q --verify "refs/tags/${tag}" >/dev/null; then
      echo "✗ tag ${tag} already exists — bump VERSION before releasing" >&2
      exit 1
    fi
    if [ "$(git rev-parse HEAD)" != "$(git rev-parse dev)" ]; then
      echo "✗ HEAD is not dev — VERSION is read from this checkout but dev is what ships;" >&2
      echo "  release from an up-to-date dev checkout." >&2
      exit 1
    fi
    just gate
    git push origin dev
    # main only ever fast-forwards to a release commit. Both ref updates are
    # ff-only, so a diverged main (local or remote) fails here instead of being
    # rewound and losing its out-of-band commit.
    if ! git fetch -q origin main:main || ! git fetch -q . dev:main; then
      echo "✗ main is checked out here, or diverged from dev — release from a dev checkout;" >&2
      echo "  if diverged: git merge origin/main on dev, then re-run the release." >&2
      exit 1
    fi
    git push origin main
    git tag -a "${tag}" -m "${tag}" main
    git push origin "${tag}"
    gh release create "${tag}" --target main --title "${tag}" --notes-file "{{notes}}"
    echo "✓ released ${tag}"