[dduugg]

Summary

pks list-references prints, as JSON, every reference from one pack to a constant that another pack defines, with the violations pks check finds in it. Each violation gives its type, whether it's strict, and whether a package_todo.yml records it. A reference that the packs' rules allow, such as one covered by a declared dependency or to a public constant, is listed with an empty violations list.

check reports only the references that break a rule, so today nothing shows how packs use each other where the rules allow it. Tools that read package_todo.yml files, such as query_packwerk, see only the recorded violations. This is the pks half of rubyatscale/query_packwerk#8. A References collection in query_packwerk would be built from this output.

$ pks list-references --defining-pack packs/bar
{"references":[{"file":"packs/foo/app/services/foo.rb","line":3,"column":4,"constant_name":"::Bar","referencing_pack_name":"packs/foo","defining_pack_name":"packs/bar","violations":[{"violation_type":"dependency","strict":false,"recorded":false},{"violation_type":"privacy","strict":false,"recorded":false}]}]}

• --defining-pack and --referencing-pack limit the list to references to or from the packs they name. Each can be repeated. An unknown pack is an error, and a trailing slash is accepted, as in rm.
• It exits 0 whether or not references have violations.
• schema/list-references-output.json describes the output, as schema/check-output.json does for check -o json.

This PR doesn't bump the version. The entry goes under ## Unreleased.

Design notes

• References within a pack, and to constants that no pack defines (a gem's, say), are left out.
• Several definitions. The experimental parser can resolve a constant to more than one file in a pack, and then the reference has a copy for each file. The copies are listed as one reference with every violation any of them makes, which is what check reports. Taking one copy's violations would drop a privacy violation whenever that copy's file was public, and which copy comes first varies between runs.
• ERB. pks keeps no source positions in ERB and reports line 0 there, so an ERB reference has a null line and column, and an ERB file's references to one constant are listed once. check -o json reports these as "line": 0, which its own schema forbids (minimum: 1). That's left for a follow-up, along with keeping positions through the ERB-to-Ruby conversion.
• Output goes through a BufWriter, since a large app produces tens of MB of JSON.
• The sort and the checker loop run in parallel, as check's checkers do. par_chunk_by needs rayon 1.10, so Cargo.toml's requirement goes up from 1.7; Cargo.lock isn't tracked, so nothing else guarantees it.
• get_checkers becomes pub(crate) so the new module can run the checkers itself. check_all and pks rm's reference search are unchanged.

Who this affects

• pks list-references is new. Nothing else changes.

Test plan

• tests/list_references_test.rs checks every output against the schema. It covers: the full output for simple_app; strict and recorded flags in every combination (uses_strict_mode_partially_recorded, contains_package_todo); every violation type; both filters, combined, and --defining-pack repeated and with a trailing slash; an unknown pack for each filter; leaving out a reference within a pack; several uses of a constant in one file, and one at line 1, column 0; the order of files; ERB, with two constants and two files; and, under the experimental parser, a constant with a public and a private definition, and one that two packs define.
• Each of these makes a test fail on every run: keeping references within a pack, not merging copies, reporting ERB's line 0, leaving out the sort, leaving any field out of the key that merges copies, or taking only one copy's violations.
• On a large Rails monolith, without a cache, it takes about as long and as much memory as pks check. Its unrecorded violations match check -o json's violations exactly, line and column included. Every reference matches the schema, and none repeats.
• cargo test, cargo fmt --check, and cargo clippy --all-targets --all-features with -Dwarnings. Locally, test_gitignore_negation_patterns fails on main too when the global gitignore has *.log, and it passes without one.