docs: record lessons 91 and 92 and two rules #772

Workflow file for this run

	name: CI

	on:
	push:
	branches: [main]
	pull_request:
	# Manual re-run, matching every other workflow in this directory. The
	# `coverage` job is the reason: Codecov compares a PR against the most
	# recent ancestor that has a report, so a push to main that produces
	# no run leaves every later PR silently baselined against an older
	# commit — the diff table then attributes those intervening commits'
	# coverage to whichever PR is open. That happened at d818e306, which
	# carries zero check-runs, and left PR #1223 compared against a base
	# eight commits behind. Without a dispatch trigger the only remedy is
	# to land another commit on main.
	workflow_dispatch:

	# Default to read-only; jobs that need more escalate explicitly.
	permissions:
	contents: read

	# Cancel in-progress runs for the same ref (e.g. PR pushes) but not on
	# main or tag builds — those should always complete.
	concurrency:
	group: ${{ github.workflow }}-${{ github.ref }}
	cancel-in-progress: ${{ github.ref != 'refs/heads/main' && !startsWith(github.ref, 'refs/tags/') }}

	# All `uses:` below are pinned to commit SHAs to eliminate supply-chain
	# risk from action-release spoofing. SHAs sourced from the host-identity
	# reference workflow for parity; bump via Dependabot.
	env:
	CARGO_TERM_COLOR: always
	CARGO_INCREMENTAL: 0
	CARGO_NET_RETRY: 10
	RUSTUP_MAX_RETRIES: 10
	RUSTFLAGS: "-D warnings"
	RUSTDOCFLAGS: "-D warnings"

	jobs:
	# Path-filter detection. Outputs `py: true` when the change set
	# touches the bindings crate, the workflow file itself, mise.toml
	# (toolchain pins), or the root Cargo.toml / Cargo.lock (PyO3 /
	# workspace dep bumps must re-run the python-test matrix even on a
	# Rust-only PR title). On Rust-only PRs the python jobs below are
	# `skipped`, which satisfies the `ci` aggregator's `needs:` without
	# being `failure` or `cancelled`.
	changes:
	name: detect path changes
	runs-on: ubuntu-latest
	timeout-minutes: 5
	outputs:
	py: ${{ steps.filter.outputs.py }}
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dorny/paths-filter@ceb8a2b8f2d89434be7ff52d3de7ec3738c5cc9d # v4
	id: filter
	with:
	filters: \|
	py:
	- 'big-code-analysis-py/**'
	- '.github/workflows/ci.yml'
	- '.pre-commit-config.yaml'
	- 'Makefile'
	- 'mise.toml'
	- 'Cargo.toml'
	- 'Cargo.lock'

	fmt:
	name: rustfmt
	runs-on: ubuntu-latest
	timeout-minutes: 10
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
	with:
	toolchain: stable
	components: rustfmt
	- run: cargo fmt --all -- --check

	clippy:
	name: clippy
	runs-on: ubuntu-latest
	timeout-minutes: 30
	# security-events:write lets the upload-sarif step publish the clippy
	# findings to GitHub code scanning (Security tab + PR annotations).
	# actions:read is required by upload-sarif on private/internal repos
	# (harmless on public ones) and matches codeql.yml's permission set.
	# The workflow-level default is contents:read.
	permissions:
	contents: read
	security-events: write
	actions: read
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
	with:
	toolchain: stable
	components: clippy
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	# clippy-sarif converts cargo's JSON diagnostics into SARIF; sarif-fmt
	# renders the same findings human-readably into the job log. Pinned to
	# 0.8.0 for a reproducible install. taiki-e/install-action has no
	# manifest entry for these crates, so they are compiled from source.
	# Swatinem/rust-cache does not persist ~/.cargo/bin, so cache the built
	# binaries explicitly (keyed on the version pin) to avoid recompiling
	# them — sarif-fmt pulls in syntect — on every run.
	- name: Cache clippy-sarif and sarif-fmt
	id: cache-sarif-tools
	uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
	with:
	path: \|
	~/.cargo/bin/clippy-sarif
	~/.cargo/bin/sarif-fmt
	key: sarif-tools-${{ runner.os }}-0.8.0
	- name: Install clippy-sarif and sarif-fmt
	if: steps.cache-sarif-tools.outputs.cache-hit != 'true'
	run: \|
	cargo install clippy-sarif --version 0.8.0 --locked
	cargo install sarif-fmt --version 0.8.0 --locked
	# Capture clippy's JSON diagnostics to a file (not a pipe) so the SARIF
	# is generated from a complete document — a hard compile-error that
	# aborts clippy mid-stream cannot truncate a piped report.
	# `\|\| clippy_status=$?` records clippy's real exit code without `set -e`
	# aborting first; the final `exit` re-raises it so this step still
	# fails the build on any warning, exactly as the old `-- -D warnings`
	# invocation did. The SARIF file is written before that exit, so the
	# upload step can still publish it via `if: always()`.
	- name: Run clippy (SARIF)
	run: \|
	set -euo pipefail
	clippy_status=0
	cargo clippy --workspace --all-targets --all-features \
	--message-format=json -- -D warnings > clippy.json \|\| clippy_status=$?
	clippy-sarif < clippy.json > rust-clippy-results.sarif
	sarif-fmt < rust-clippy-results.sarif
	exit "$clippy_status"
	# Fork PRs get a read-only GITHUB_TOKEN without security-events scope,
	# so the upload would error; skip it there (and when no SARIF was
	# produced, e.g. clippy never ran). The clippy gate above still fails
	# the build on warnings regardless of this step.
	- name: Upload SARIF to code scanning
	if: always() && hashFiles('rust-clippy-results.sarif') != '' && (github.event_name != 'pull_request' \|\| github.event.pull_request.head.repo.full_name == github.repository)
	uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4.37.9
	with:
	sarif_file: rust-clippy-results.sarif
	category: clippy

	docs:
	name: rustdoc
	runs-on: ubuntu-latest
	timeout-minutes: 20
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
	with:
	toolchain: stable
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	# Delegate to the Makefile so the strict-doc gate lives in one
	# place. `make doc-check` appends `-D warnings` to the workflow-
	# level RUSTDOCFLAGS rather than replacing it.
	- run: make doc-check
	# Gate-effectiveness test: inject a known broken intra-doc link
	# on a `pub` item and assert `make doc-check` FAILS. Mirrors the
	# `enums-check` sabotage step further down — catches regressions
	# where `-D warnings` is silently dropped from the recipe, the
	# `_pc-doc-check` / `_ci-doc-check` wiring breaks, or rustdoc's
	# broken-intra-doc-links lint gets demoted. The trap restores
	# the file even if the assertion fails. See lesson 21 in
	# docs/development/lessons_learned.md on dedicated-gate parity.
	- name: doc-check gate-effectiveness test
	run: \|
	set -eu
	test_file=src/lib.rs
	cp "$test_file" "$test_file.bak"
	trap 'mv "$test_file.bak" "$test_file"' EXIT
	# shellcheck disable=SC2016 # backticks inside the literal rustdoc payload are intentional
	printf '\n/// Sabotage broken link: [`NonExistentDocCheckGateTarget`]\npub fn _doc_check_gate_sabotage() {}\n' >> "$test_file"
	if make doc-check > /tmp/doc-sabotage.log 2>&1; then
	echo "FAIL: doc-check did not reject the broken intra-doc link"
	tail -40 /tmp/doc-sabotage.log
	exit 1
	fi
	# Confirm the failure was caused by this sabotage (not some
	# unrelated pre-existing rustdoc warning, a network glitch, or
	# a cargo-side error). Without this check the gate could
	# appear effective while silently skipping the injected
	# payload.
	if ! grep -q 'NonExistentDocCheckGateTarget' /tmp/doc-sabotage.log; then
	echo "FAIL: doc-check exited non-zero but not because of the injected payload"
	tail -40 /tmp/doc-sabotage.log
	exit 1
	fi
	echo "PASS: doc-check correctly rejected the broken intra-doc link"

	test:
	name: test (${{ matrix.os }})
	runs-on: ${{ matrix.os }}
	timeout-minutes: 45
	# checks:write lets action-junit-report create the test-report check run;
	# pull-requests:write lets it annotate failing tests on the PR. The
	# workflow-level default is contents:read.
	permissions:
	contents: read
	checks: write
	pull-requests: write
	strategy:
	fail-fast: false
	matrix:
	os: [ubuntu-latest, macos-latest, windows-latest]
	steps:
	# Integration snapshots live in the big-code-analysis-output
	# submodule under tests/repositories/; tests require it.
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: recursive
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
	with:
	toolchain: stable
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	- uses: taiki-e/install-action@37f7c5781271959fb65b6b35224e28652ff2b63d # v2.87.0
	with:
	tool: cargo-nextest
	# nextest runs the lib / bins / integration tests and writes the JUnit
	# report to target/nextest/ci/junit.xml (see .config/nextest.toml). It
	# does not run doctests — those are covered by the next step.
	- name: cargo nextest run
	run: cargo nextest run --profile ci --all-features --workspace --locked
	# Doctests, matching the Makefile's `test` / `test-doc` split. nextest
	# cannot run these, so dropping this step would silently stop
	# exercising the workspace's documentation examples.
	- name: cargo test --doc
	run: cargo test --doc --all-features --workspace --locked
	# Publish the JUnit XML as an artifact regardless of outcome — this
	# works even on fork PRs, where the check-run API used below is not
	# available.
	- name: Upload JUnit report
	if: always()
	uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
	with:
	name: junit-${{ matrix.os }}
	path: target/nextest/ci/junit.xml
	if-no-files-found: warn
	# Render the JUnit report as a check run + PR annotations + job summary.
	# nextest already gates the job, so fail_on_failure stays off to avoid
	# masking the real exit code under `if: always()`. Skipped on fork PRs,
	# whose read-only token cannot create check runs.
	- name: Publish test report
	if: always() && (github.event_name != 'pull_request' \|\| github.event.pull_request.head.repo.full_name == github.repository)
	uses: mikepenz/action-junit-report@a9170d5795813c01ab4901ffb045b52bab4ab09d # v6.5.0
	with:
	report_paths: target/nextest/ci/junit.xml
	check_name: test report (${{ matrix.os }})
	detailed_summary: true
	include_passed: false
	fail_on_failure: false

	# The exact ancestor-chain assertion (#1122). `Ancestors::checked` keeps
	# only an O(1) approximation on by default, because the exact
	# `chain.last() == node.parent()` form costs Node::parent's O(depth) per
	# node and makes every debug-build walk quadratic. This lane restores it
	# so a walker whose truncate/push bookkeeping desynchronises still fails
	# a build rather than silently feeding predicates a wrong ancestor.
	#
	# ubuntu-only and lib-scoped: the assertion lives in the library's walks,
	# so the per-OS matrix and the CLI / web / integration tiers would re-pay
	# the quadratic cost without covering anything the lib tests do not.
	chain-audit:
	name: chain audit
	runs-on: ubuntu-latest
	timeout-minutes: 45
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
	with:
	toolchain: stable
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	- name: cargo test --lib with --cfg chain_audit
	env:
	# Replaces the workflow-level RUSTFLAGS rather than extending
	# it — a step `env` key shadows the workflow one — so `-D
	# warnings` is repeated here deliberately. Keep the two in
	# step if the workflow-level value ever gains a flag.
	RUSTFLAGS: "-D warnings --cfg chain_audit"
	run: cargo test -p big-code-analysis --lib --all-features --locked

	coverage:
	name: coverage
	runs-on: ubuntu-latest
	timeout-minutes: 45
	steps:
	# Coverage instruments and runs the full test suite, so it needs the
	# big-code-analysis-output submodule exactly like the test job above.
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: recursive
	# llvm-tools-preview supplies llvm-profdata/llvm-cov for source-based
	# coverage instrumentation.
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
	with:
	toolchain: stable
	components: llvm-tools-preview
	# Coverage builds carry -C instrument-coverage, so their artifacts are
	# incompatible with the regular build cache; a distinct key keeps the
	# two from thrashing each other.
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	with:
	key: coverage
	- uses: taiki-e/install-action@37f7c5781271959fb65b6b35224e28652ff2b63d # v2.87.0
	with:
	tool: cargo-nextest,cargo-llvm-cov
	# nextest is the same runner the `test` job uses, so instrumenting it
	# keeps the coverage numbers aligned with what CI actually exercises.
	# --no-report defers reporting so the same profile data can be emitted
	# in two shapes below (Codecov upload + human-readable job summary).
	#
	# Doctests are intentionally excluded: `cargo llvm-cov --doc` requires
	# nightly, and pairing nightly with the workflow-wide `-D warnings`
	# would red-X CI on unrelated new nightly lints. The `test` job still
	# runs doctests for correctness — only their coverage is omitted.
	- name: Run tests with coverage instrumentation
	run: cargo llvm-cov --no-report nextest --all-features --workspace --locked
	# Codecov's native format preserves region coverage (lcov would drop to
	# line-only).
	- name: Generate Codecov report
	run: cargo llvm-cov report --codecov --output-path codecov.json
	# Per-file coverage table in the run's Summary tab, so reviewers can
	# read coverage without leaving GitHub or waiting on the Codecov PR
	# comment.
	- name: Write coverage to job summary
	run: \|
	{
	echo '### Coverage'
	echo ''
	echo '```'
	cargo llvm-cov report
	echo '```'
	} >> "$GITHUB_STEP_SUMMARY"
	# token authenticates same-repo runs; fork PRs fall back to Codecov's
	# tokenless upload for public repos (the secret resolves empty there).
	# fail_ci_if_error stays off so a Codecov outage or a credential-less
	# fork PR cannot red-X the merge gate — coverage is informational.
	- name: Upload coverage to Codecov
	uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
	with:
	files: codecov.json
	flags: rust
	token: ${{ secrets.CODECOV_TOKEN }}
	fail_ci_if_error: false

	msrv:
	name: msrv (1.94)
	runs-on: ubuntu-latest
	timeout-minutes: 30
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # 1.94
	with:
	toolchain: "1.94"
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	# Build only — MSRV is a compile-time promise; dev-deps may
	# require a newer toolchain.
	- run: cargo build --all-features --workspace --locked

	feature-matrix:
	name: features (${{ matrix.name }})
	runs-on: ubuntu-latest
	timeout-minutes: 30
	strategy:
	fail-fast: false
	matrix:
	include:
	- name: default (lib)
	flags: -p big-code-analysis
	- name: no-default-features (lib)
	flags: --no-default-features -p big-code-analysis
	# Per-language feature subset (issue #252). Locks in the
	# "minimal grammar set" guarantee: dropping default features
	# and re-enabling only the languages the caller cares about
	# must still produce a working library. `rust` + `typescript`
	# is the canonical subset because it exercises both a
	# single-feature grammar (`tree-sitter-rust`) and a shared-
	# crate grammar (`tree-sitter-typescript`, also used by the
	# `Tsx` variant).
	- name: minimal-langs (lib)
	flags: --no-default-features --features rust,typescript -p big-code-analysis
	- name: default (cli)
	flags: -p big-code-analysis-cli
	- name: no-default-features (cli)
	flags: --no-default-features -p big-code-analysis-cli
	- name: default (web)
	flags: -p big-code-analysis-web
	- name: no-default-features (web)
	flags: --no-default-features -p big-code-analysis-web
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
	with:
	toolchain: stable
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	# `cargo check --all-targets` exercises bins, tests, and examples,
	# so a cfg-gated test file that only compiles under default features
	# does not slip through the no-default-features matrix leg.
	- run: cargo check --all-targets ${{ matrix.flags }} --locked

	deny:
	name: cargo-deny
	runs-on: ubuntu-latest
	timeout-minutes: 10
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: EmbarkStudios/cargo-deny-action@3c6349835b2b7b196a839186cb8b78e02f7b5f25 # v2.1.1
	with:
	command: check advisories bans licenses sources

	license-audit:
	name: license-audit
	runs-on: ubuntu-latest
	timeout-minutes: 20
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
	with:
	toolchain: stable
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	- uses: taiki-e/install-action@37f7c5781271959fb65b6b35224e28652ff2b63d # v2.87.0
	with:
	tool: cargo-about@0.8.4
	# Fails if any dep in either binary crate's transitive closure
	# resolves to a license not in `about.toml` `accepted`. Dependabot
	# PRs that introduce an unapproved license now fail here instead of
	# silently slipping into the release.
	# Render to a file (rather than /dev/null) and sanity-check the
	# output. A regression in about.hbs that yielded an empty render
	# would otherwise pass silently — exit 0 from cargo-about does not
	# imply non-empty output.
	- name: Render attribution bundle for big-code-analysis-cli
	run: \|
	cargo about generate --locked \
	--manifest-path big-code-analysis-cli/Cargo.toml \
	about.hbs > cli-thirdparty.md
	grep -q '^## Crates' cli-thirdparty.md
	test "$(wc -l < cli-thirdparty.md)" -gt 50
	- name: Render attribution bundle for big-code-analysis-web
	run: \|
	cargo about generate --locked \
	--manifest-path big-code-analysis-web/Cargo.toml \
	about.hbs > web-thirdparty.md
	grep -q '^## Crates' web-thirdparty.md
	test "$(wc -l < web-thirdparty.md)" -gt 50

	lint:
	name: lint (make lint)
	runs-on: ubuntu-latest
	timeout-minutes: 20
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	# `rustfmt` is here for the rustfmt-bail gate, which shells out to
	# it directly. The toolchain action installs the minimal profile,
	# and the gate skips cleanly when rustfmt is missing — so leaving
	# it out would disable the check in CI without failing anything.
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
	with:
	toolchain: stable
	components: clippy, rustfmt
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
	with:
	python-version: "3.x"
	# rumdl is the Markdown linter (replaced markdownlint-cli2). The
	# prebuilt binary is not in taiki-e/install-action's manifest, so
	# we fetch the upstream release tarball directly with a pinned
	# SHA256, mirroring the actionlint and checkmake patterns below.
	# Bump RUMDL_SHA256 in lockstep with `RUMDL_VERSION` (and with the
	# `rumdl = …` pin in `mise.toml`). To regenerate the SHA256 after
	# a version bump:
	# curl -fsSL https://github.com/rvben/rumdl/releases/download/v${RUMDL_VERSION}/rumdl-v${RUMDL_VERSION}-x86_64-unknown-linux-gnu.tar.gz.sha256
	- name: Install rumdl
	env:
	RUMDL_VERSION: "0.2.2"
	RUMDL_SHA256: "d38ad81c51221990d5e0204b4746f8c980a77de235aa875c2f30f02f9a19bb1a"
	run: \|
	set -euo pipefail
	url="https://github.com/rvben/rumdl/releases/download/v${RUMDL_VERSION}/rumdl-v${RUMDL_VERSION}-x86_64-unknown-linux-gnu.tar.gz"
	curl -fsSL -o /tmp/rumdl.tgz "$url"
	echo "${RUMDL_SHA256} /tmp/rumdl.tgz" \| sha256sum -c -
	tar -xzf /tmp/rumdl.tgz -C /tmp rumdl
	install -m 0755 /tmp/rumdl /usr/local/bin/rumdl
	rumdl --version
	- uses: taiki-e/install-action@37f7c5781271959fb65b6b35224e28652ff2b63d # v2.87.0
	with:
	tool: taplo-cli@0.10.0,shellcheck@0.10.0,shfmt@3.12.0
	# actionlint 1.7.12's prebuilt binary is not yet in
	# taiki-e/install-action's manifest, and cargo-binstall has no
	# fallback for it. Fetch the upstream release tarball directly,
	# mirroring the checkmake step below. Bump SHA256 in lockstep
	# with `ACTIONLINT_VERSION`.
	- name: Install actionlint
	env:
	ACTIONLINT_VERSION: "1.7.12"
	ACTIONLINT_SHA256: "8aca8db96f1b94770f1b0d72b6dddcb1ebb8123cb3712530b08cc387b349a3d8"
	run: \|
	set -euo pipefail
	url="https://github.com/rhysd/actionlint/releases/download/v${ACTIONLINT_VERSION}/actionlint_${ACTIONLINT_VERSION}_linux_amd64.tar.gz"
	curl -fsSL -o /tmp/actionlint.tgz "$url"
	echo "${ACTIONLINT_SHA256} /tmp/actionlint.tgz" \| sha256sum -c -
	tar -xzf /tmp/actionlint.tgz -C /tmp actionlint
	install -m 0755 /tmp/actionlint /usr/local/bin/actionlint
	actionlint -version
	# checkmake is not in taiki-e/install-action's manifest; fetch the
	# pinned upstream release binary directly. The SHA256 below comes
	# from the upstream `checksums.txt` published alongside the
	# 0.2.2 release; bump it in lockstep with the version pin.
	- name: Install checkmake
	env:
	CHECKMAKE_VERSION: "0.2.2"
	CHECKMAKE_SHA256: "bedd033b06f2563809855ec2a9950c7a81acea6cd82937fd2f124e2c1c5fc3d5"
	run: \|
	set -euo pipefail
	url="https://github.com/mrtazz/checkmake/releases/download/${CHECKMAKE_VERSION}/checkmake-${CHECKMAKE_VERSION}.linux.amd64"
	curl -fsSL -o /tmp/checkmake "$url"
	echo "${CHECKMAKE_SHA256} /tmp/checkmake" \| sha256sum -c -
	install -m 0755 /tmp/checkmake /usr/local/bin/checkmake
	checkmake --version
	- name: make lint
	run: make lint
	# Defensive: `make lint` invokes the snapshot-anchors recipe, but
	# `make lint`'s file-finding helpers depend on a glob fix tracked
	# under #160; until that lands, run the snapshot-anchor gate
	# explicitly so a regression in `make lint` cannot silently disable
	# this check.
	- name: snapshot anchors (explicit)
	run: python3 utils/check-snapshot-anchors.py
	# Run the gate's own unittests as their own explicit step, for the
	# same reason as the rustfmt-bail twin below: a refactor that
	# breaks the script must not be able to disable the gate silently.
	- name: snapshot-anchors self-tests (explicit)
	run: python3 -m unittest -q utils/check-snapshot-anchors-test.py
	# Defensive twin for the rustfmt-bail gate (#1136): a comment
	# inside a match pattern makes rustfmt emit the whole match
	# verbatim while `cargo fmt --check` exits 0, so the fmt job
	# cannot catch it. `make lint` already runs this gate; pinning it
	# here keeps it enforced even if a future refactor drops it from
	# the aggregate recipe.
	- name: rustfmt-bail (explicit)
	run: python3 utils/check-rustfmt-bail.py
	# Run the gate's own unittests as their own explicit step
	# so a refactor that breaks the script can't disable the
	# gate without surfacing the regression in CI.
	- name: rustfmt-bail self-tests (explicit)
	run: python3 -m unittest -q utils/check-rustfmt-bail-test.py
	# Defensive twin to the snapshot-anchors gate above: `make lint`
	# already invokes check-versions, but pinning it here guarantees
	# the lockstep version invariant is enforced even if a future
	# refactor drops it from the aggregate recipe.
	- name: check-versions (explicit)
	run: python3 utils/check-versions.py
	# Defensive twin for the man-page packaging gate (#446): a bca
	# subcommand man page that drops out of the hand-maintained
	# deb/rpm asset lists ships an artifact without its page (the
	# #444 bug class). `make lint` already runs this gate; pinning
	# it here guarantees enforcement even if a future refactor drops
	# it from the aggregate recipe.
	- name: check-manpage-assets (explicit)
	run: python3 utils/check-manpage-assets.py
	# Defensive twin for the man-page drift gate's self-tests
	# (#1249). The gate itself runs in the `manpage` job, which
	# invokes the script directly and so cannot be dropped by a
	# refactor of the `make lint` aggregate — but the tests that
	# prove the gate still catches an untracked page can be, and a
	# gate that has silently stopped gating is indistinguishable
	# from a clean tree. That is the failure this pair exists for.
	- name: check-manpage-drift-test (explicit)
	run: python3 -m unittest -q utils/check-manpage-drift-test.py
	# Defensive twin for the diagnostic-prefix gate (#1199): a
	# capitalised `Warning:` / `Error:` / `Note:` baked into a string
	# literal bypasses the one-helper-per-crate severity ladder and
	# reads as correct in review. Its self-tests run as their own
	# step because a source-scanning gate that stops matching
	# reports a clean tree.
	- name: check-diagnostic-prefix (explicit)
	run: python3 utils/check-diagnostic-prefix.py
	- name: check-diagnostic-prefix self-tests (explicit)
	run: python3 -m unittest -q utils/check-diagnostic-prefix-test.py
	# Defensive twin for the safety-doc pin gate (#1057): the
	# module doc of big-code-analysis-py/src/node.rs is the
	# canonical soundness argument for this workspace's only
	# sanctioned `unsafe` block, and it reasons about a named
	# tree-sitter release. A bump that leaves the literal behind
	# leaves an argument that reads as verified against a crate
	# nobody compiles. Its self-tests run as their own step for the
	# usual reason: a source-scanning gate that stops matching
	# reports a clean tree.
	- name: check-safety-doc-pin (explicit)
	run: python3 utils/check-safety-doc-pin.py
	- name: check-safety-doc-pin self-tests (explicit)
	run: python3 -m unittest -q utils/check-safety-doc-pin-test.py
	# Defensive twin for the grammar-marker-sync gate (#400): bumping
	# the notification-only marker in tree-sitter-{mozjs,mozcpp}/
	# Cargo.toml without re-running the matching generate-*.sh
	# ships a marker that lies about the bundled grammar version.
	# Invokes the script directly (matching the snapshot-anchors
	# and check-versions defensive twins above) so a regression
	# in the `make lint` aggregate cannot silently disable this
	# check.
	- name: grammar-marker-sync (explicit)
	run: python3 utils/check-grammar-marker-sync.py
	# Run the gate's own unittests as their own explicit step
	# so a refactor that breaks the script can't disable the
	# gate without surfacing the regression in CI.
	- name: grammar-marker-sync self-tests (explicit)
	run: python3 -m unittest -q utils/check-grammar-marker-sync-test.py
	# Defensive twin for the workspace-exclusion gate (#1145, #1151):
	# an excluded crate that roots no workspace of its own breaks
	# `cargo fmt --all` inside every git worktree, and an unpinned
	# tree-sitter dependency lets `cargo update` move a grammar
	# silently. `make lint` already runs this gate; invoking it here
	# (matching the twins above) keeps it enforced even if a future
	# refactor drops it from the aggregate recipe.
	- name: check-excluded-manifests (explicit)
	run: python3 utils/check-excluded-manifests.py
	# Run the gate's own unittests as their own explicit step
	# so a refactor that breaks the script can't disable the
	# gate without surfacing the regression in CI.
	- name: check-excluded-manifests self-tests (explicit)
	run: python3 -m unittest -q utils/check-excluded-manifests-test.py
	# Defensive twin for the ruff-lockstep gate (#1230): the
	# ruff-pre-commit `rev:`, `uv.lock`, and the hash-pinned
	# `requirements/dev.txt` export CI installs from must name one
	# version. They had already drifted once, silently, because a
	# comment was the whole mechanism — so this gate in particular
	# must not be able to disappear from the aggregate unnoticed.
	- name: check-ruff-lockstep (explicit)
	run: python3 utils/check-ruff-lockstep.py
	# Run the gate's own unittests as their own explicit step
	# so a refactor that breaks the script can't disable the
	# gate without surfacing the regression in CI.
	- name: check-ruff-lockstep self-tests (explicit)
	run: python3 -m unittest -q utils/check-ruff-lockstep-test.py
	# Defensive twin for the enums-codegen-drift gate (#405):
	# running any grammar regen previously regenerated
	# `src/c_langs_macros/*.rs` to a pre-optimization form
	# silently. The gate diffs codegen output against
	# checked-in files; running it explicitly here guards
	# against `make lint` ever dropping it from the aggregate.
	- name: enums-codegen-drift (explicit)
	run: bash utils/check-enums-codegen-drift.sh
	# Run the gate's own unittests as their own explicit step
	# so a refactor that breaks the script can't disable the
	# gate without surfacing the regression in CI.
	- name: enums-codegen-drift self-tests (explicit)
	run: python3 -m unittest -q utils/check-enums-codegen-drift-test.py
	# Defensive: the prior `make lint` step already runs enums-check
	# as part of its aggregate. Repeating it here protects against a
	# regression to that aggregate (e.g., enums-check accidentally
	# dropped from the `lint` recipe), which is precisely the failure
	# mode #164 was filed against — `[workspace].exclude` had hidden
	# the crate from every workspace-scoped lint until the gate
	# existed. The redundant invocation is cheap (cargo cache is warm)
	# and pins the gate at the workflow level.
	- name: enums-crate check (explicit)
	run: make enums-check
	# Gate-effectiveness test: inject a known unused-variable warning
	# into enums/src/main.rs and assert `make enums-check` FAILS.
	# Catches regressions where RUSTFLAGS is silently dropped, the
	# recipe stops failing on warnings, or `--all-targets` is
	# removed. The trap restores the file even if the assertion
	# fails. This step runs only in CI — locally, a developer who
	# changes the gate should re-verify with the same maneuver.
	- name: enums-check gate-effectiveness test
	run: \|
	set -eu
	test_file=enums/src/main.rs
	cp "$test_file" "$test_file.bak"
	trap 'mv "$test_file.bak" "$test_file"' EXIT
	printf '\nfn _enums_check_gate_sabotage() { let unused_x = 1u32; }\n' >> "$test_file"
	if make enums-check > /tmp/sabotage.log 2>&1; then
	echo "FAIL: enums-check did not reject the injected warning"
	tail -40 /tmp/sabotage.log
	exit 1
	fi
	echo "PASS: enums-check correctly rejected the injected warning"

	# Python bindings — lint + type-check. Single Linux job; the heavier
	# cross-platform matrix lives in `python-test` below. Both jobs are
	# gated by `needs.changes.outputs.py == 'true'` so Rust-only PRs skip
	# them entirely (verified by the `ci` aggregator job's tolerance for
	# `skipped` results).
	python-lint:
	name: python-lint
	needs: changes
	if: needs.changes.outputs.py == 'true'
	runs-on: ubuntu-latest
	timeout-minutes: 15
	steps:
	# The bindings tests use the local fixtures under
	# big-code-analysis-py/tests/fixtures/, not the
	# big-code-analysis-output submodule (that's the Rust integration
	# snapshot store). Skip recursive submodules to avoid pulling
	# ~hundreds of MB of unused fixtures and to avoid blocking on a
	# missing/force-pushed submodule SHA.
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable
	with:
	toolchain: stable
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	with:
	# Share the cache key with the ubuntu-latest/py3.12 leg of
	# the python-test matrix below — both jobs build the same
	# bindings crate against the same toolchain on the same OS,
	# so a populated target/ from one job warms the other.
	shared-key: "python-bindings-ubuntu-latest-3.12"
	- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
	with:
	python-version: "3.12"
	cache: "pip"
	# Create the venv inside big-code-analysis-py/ to match
	# pyrightconfig.json's venvPath="." + venv=".venv" pair (relative
	# to pyrightconfig.json's location). A repo-root venv would leave
	# pyright unable to resolve the maturin-built _native module.
	# requirements/dev.txt is the hash-pinned export of uv.lock's
	# `dev` extra (regenerated by `make py-relock`), so this job
	# installs the exact resolved set `make py-bootstrap` uses
	# locally — no floor-vs-lockfile drift — and `--require-hashes`
	# pins the supply chain (OpenSSF Scorecard Pinned-Dependencies).
	# The ruff-pre-commit `rev:` in .pre-commit-config.yaml is held in
	# lockstep with the ruff version resolved there by the
	# `check-ruff-lockstep` gate in the `lint` job (#1230), so this is
	# no longer something a reviewer has to remember.
	- name: Create venv + install Python toolchain
	working-directory: big-code-analysis-py
	run: \|
	python -m venv .venv
	source .venv/bin/activate
	pip install --require-hashes -r requirements/dev.txt
	# maturin develop must precede mypy / pyright so the _native
	# extension is resolvable from the venv. Both type checkers
	# treat the .pyi stub as authoritative, but they still need to
	# import the package without ModuleNotFoundError. Use the
	# default (debug) profile to match the local `make py-typecheck`
	# / `make py-test` invocations — local-CI parity matters more
	# than build speed at the lint job (debug is faster anyway).
	- name: maturin develop
	working-directory: big-code-analysis-py
	run: \|
	source .venv/bin/activate
	maturin develop
	- name: ruff format --check
	working-directory: big-code-analysis-py
	run: \|
	source .venv/bin/activate
	ruff format --check .
	- name: ruff check
	working-directory: big-code-analysis-py
	run: \|
	source .venv/bin/activate
	ruff check .
	- name: mypy --strict
	working-directory: big-code-analysis-py
	run: \|
	source .venv/bin/activate
	mypy --strict python tests examples
	- name: pyright
	working-directory: big-code-analysis-py
	run: \|
	source .venv/bin/activate
	pyright

	# Python bindings — wheel build + pytest, Linux/macOS/Windows
	# × Python 3.12/3.13. The cargo `test` job already builds the
	# bindings crate's Rust side; this job is additive, verifying that
	# the maturin-produced wheel actually loads under CPython on each
	# platform (which cargo cannot do).
	python-test:
	name: python-test (${{ matrix.os }}, py${{ matrix.python }})
	needs: changes
	if: needs.changes.outputs.py == 'true'
	runs-on: ${{ matrix.os }}
	timeout-minutes: 45
	strategy:
	fail-fast: false
	matrix:
	os: [ubuntu-latest, macos-latest, windows-latest]
	python: ["3.12", "3.13"]
	steps:
	# Submodules unnecessary — bindings tests use the local fixtures
	# at big-code-analysis-py/tests/fixtures/. The
	# big-code-analysis-output submodule is for Rust integration
	# snapshots and would otherwise gate this matrix on its
	# availability.
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable
	with:
	toolchain: stable
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	with:
	# Per-matrix-leg cache key so Linux / macOS / Windows do not
	# trample each other's target/ directories. The
	# ubuntu-latest+3.12 leg shares its key with python-lint so
	# they reuse each other's build artifacts.
	shared-key: "python-bindings-${{ matrix.os }}-${{ matrix.python }}"
	- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
	with:
	python-version: ${{ matrix.python }}
	cache: "pip"
	# Cross-platform venv inside big-code-analysis-py/ (matches
	# pyrightconfig.json + the python-lint job + the local Makefile
	# convention). bash on Linux/macOS, PowerShell on Windows.
	# requirements/dev.txt is the hash-pinned export of uv.lock's
	# `dev` extra (regenerated by `make py-relock`): exact resolved
	# versions with `--require-hashes` supply-chain pinning (OpenSSF
	# Scorecard Pinned-Dependencies). It carries a few lint-only
	# tools this job does not run (ruff / mypy / pyright) — the cost
	# of installing them is preferred over maintaining a second,
	# driftable pin set.
	- name: Create venv + install deps (Unix)
	if: runner.os != 'Windows'
	working-directory: big-code-analysis-py
	run: \|
	python -m venv .venv
	.venv/bin/pip install --require-hashes -r requirements/dev.txt
	- name: Create venv + install deps (Windows)
	if: runner.os == 'Windows'
	working-directory: big-code-analysis-py
	shell: pwsh
	run: \|
	python -m venv .venv
	.venv\Scripts\python.exe -m pip install --require-hashes -r requirements/dev.txt
	# maturin develop uses the default (debug) profile to match the
	# local `make py-test` recipe — same .so layout end-to-end, so
	# local-CI parity issues surface in CI rather than only on a
	# contributor's machine.
	- name: maturin develop (Unix)
	if: runner.os != 'Windows'
	working-directory: big-code-analysis-py
	run: \|
	source .venv/bin/activate
	maturin develop
	- name: maturin develop (Windows)
	if: runner.os == 'Windows'
	working-directory: big-code-analysis-py
	shell: pwsh
	run: \|
	.venv\Scripts\Activate.ps1
	maturin develop
	- name: pytest (Unix)
	if: runner.os != 'Windows'
	working-directory: big-code-analysis-py
	run: \|
	source .venv/bin/activate
	python -m pytest --cov=big_code_analysis --cov-report=xml --cov-report=term-missing
	- name: pytest (Windows)
	if: runner.os == 'Windows'
	working-directory: big-code-analysis-py
	shell: pwsh
	run: \|
	.venv\Scripts\Activate.ps1
	python -m pytest
	# Python-side coverage measures the pure-Python surface
	# (python/big_code_analysis/_flatten.py + __init__.py); the Rust
	# extension is measured by the `coverage` job. Collected on a single
	# matrix leg because pure-Python coverage is identical across OS /
	# interpreter — uploading from all six legs would only race parallel
	# uploads to Codecov. flags:python keeps it distinct from the Rust
	# upload; fail_ci_if_error stays off for the same reason as the Rust
	# job (informational, fork-PR-safe).
	- name: Upload coverage to Codecov
	if: runner.os == 'Linux' && matrix.python == '3.12'
	uses: codecov/codecov-action@fb8b3582c8e4def4969c97caa2f19720cb33a72f # v7.0.0
	with:
	files: big-code-analysis-py/coverage.xml
	flags: python
	token: ${{ secrets.CODECOV_TOKEN }}
	fail_ci_if_error: false

	# Execute examples/jupyter_quickstart.ipynb end-to-end so a notebook
	# cell that drifts away from the bindings API (renamed kwarg, removed
	# function) breaks CI before it can rot in the documentation. The
	# job stays single-OS / single-Python because the notebook exercises
	# the public Python surface and pandas / matplotlib — both of which
	# the `python-test` matrix already covers across OS / Python combos.
	# A second matrix axis would only re-prove pandas works on Windows.
	#
	# Gated by `needs.changes.outputs.py == 'true'` same as the other
	# python-* jobs; Rust-only PRs see `skipped` (not `failure`) so the
	# aggregator's tolerance for skipped dependents continues to hold.
	python-examples-nbconvert:
	name: python-examples-nbconvert
	needs: changes
	if: needs.changes.outputs.py == 'true'
	runs-on: ubuntu-latest
	timeout-minutes: 20
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable
	with:
	toolchain: stable
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	with:
	# Share with the python-lint / ubuntu-latest+3.12 python-test
	# legs so the maturin develop step warms from a populated
	# target/ rather than rebuilding from scratch.
	shared-key: "python-bindings-ubuntu-latest-3.12"
	- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
	with:
	python-version: "3.12"
	cache: "pip"
	- name: Create venv + install notebook + maturin deps
	working-directory: big-code-analysis-py
	run: \|
	python -m venv .venv
	source .venv/bin/activate
	# requirements/examples.txt is the hash-pinned export of
	# uv.lock's [examples] extra (regenerated by `make
	# py-relock`) — installing it directly (no `pip install -e
	# .`) avoids a maturin PEP 517 build on top of the explicit
	# `maturin develop` below, and `--require-hashes` pins the
	# supply chain (OpenSSF Scorecard Pinned-Dependencies).
	pip install --require-hashes -r requirements/examples.txt
	- name: maturin develop
	working-directory: big-code-analysis-py
	run: \|
	source .venv/bin/activate
	maturin develop
	- name: Execute jupyter_quickstart.ipynb
	working-directory: big-code-analysis-py
	run: \|
	source .venv/bin/activate
	# `--inplace` writes the executed outputs back to the file,
	# but we deliberately do not commit them — CI just needs the
	# exit code. Using `--to notebook` keeps the format stable;
	# `--ExecutePreprocessor.timeout=120` caps a hung kernel.
	# `MPLBACKEND=Agg` keeps matplotlib headless on the runner.
	MPLBACKEND=Agg jupyter nbconvert \
	--to notebook \
	--execute \
	--inplace \
	--ExecutePreprocessor.timeout=120 \
	examples/jupyter_quickstart.ipynb

	manpage:
	name: man pages up to date
	runs-on: ubuntu-latest
	timeout-minutes: 15
	steps:
	- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
	with:
	fetch-depth: 1
	submodules: false
	- uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # stable tip
	with:
	toolchain: stable
	- uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
	- name: Regenerate man pages
	run: cargo xtask
	# Fails on every direction the regenerated tree can differ from
	# the committed one — modified, deleted, and added pages. The
	# added direction needs `git ls-files --others`: the page xtask
	# writes for a brand-new subcommand is untracked, and `git diff`
	# alone passed green over it until #1249. The check lives in the
	# script rather than inline here so this step and
	# `make manpages-check` cannot drift apart; the `::error::`
	# annotation is emitted by the script when GITHUB_ACTIONS is set.
	- name: Verify no drift
	run: python3 utils/check-manpage-drift.py

	# Single required status check for branch protection — depends on
	# every gating job. Passing this one check guarantees the full matrix
	# passed.
	ci:
	name: ci
	if: always()
	needs:
	- changes
	- fmt
	- clippy
	- docs
	- test
	- chain-audit
	- coverage
	- msrv
	- feature-matrix
	- deny
	- license-audit
	- lint
	- manpage
	- python-lint
	- python-test
	- python-examples-nbconvert
	runs-on: ubuntu-latest
	timeout-minutes: 5
	steps:
	- name: Fail if any dependency failed or was cancelled
	if: contains(needs..result, 'failure') \|\| contains(needs..result, 'cancelled')
	run: exit 1

Navigation Menu

docs: record lessons 91 and 92 and two rules #772

Workflow file

docs: record lessons 91 and 92 and two rules #772

Uh oh!

Workflow file for this run