Rename an idea and watch every pin fail

Disclosure: I build Reqlan. This is what happens on a tiny repo when you rename a requirement, including one pin that should have failed and didn't.

Names drift. Halfway through a project "cart" becomes "basket", someone renames the requirement to match, and every bit of code and test that pointed at the old name is now pointing at nothing. In a repo where an agent did the wiring, you won't remember where all those pointers are.

Here's what Reqlan does about it. Every command below was run on reqlan CLI 0.10.0, then again on 0.14.0 with the same output.

1. The tiny repo

repo/
  .reqlan/          # created by `reqlan init .`
  spec.rq
  src/cart.ts
  src/cart.test.ts
  src/shipping.ts
  docs/checkout.md

spec.rq has two ideas, and free_shipping depends on cart_total by name:

cart_total {
    The cart total is the sum of line prices times quantities.
    implemented in ["./src/cart.ts"]
    proven by ["./src/cart.test.ts"]
    @status in-progress
}

free_shipping {
    Orders over 50 pounds ship free.
    Depends on [cart_total].
    implemented in ["./src/shipping.ts"]
    @status in-progress
}

src/cart.ts and src/cart.test.ts both start with the same pin back to the idea:

// rq:["../spec.rq".cart_total]

docs/checkout.md pins itself the Markdown way:

<!-- rq:["../spec.rq".cart_total] -->
The basket total is shown before shipping is added.

Starting point:

$ reqlan check
No issues.

2. Rename the idea, and only the idea

I change the first line of spec.rq from cart_total { to basket_total { and touch nothing else:

$ reqlan check
## Issues (3)

../spec.rq.cart_total
- src/cart.test.ts:1 [comment_link]
- src/cart.ts:1 [comment_link]

cart_total
- spec.rq:10 free_shipping [references]

It exits 1, so CI goes red. Both code pins and the Depends on [cart_total] inside the spec itself are listed, grouped under the name they're still looking for. That grouping is the useful bit: one heading per stale name, then every place that still uses it.

3. The same list, one line per issue

For a script or a CI log, --pipe flattens it:

$ reqlan check --pipe
src/cart.test.ts:1 [comment_link] ../spec.rq.cart_total
src/cart.ts:1 [comment_link] ../spec.rq.cart_total
spec.rq:10 free_shipping [references] cart_total

Each line is a file, a line number and the name it can't find, which is roughly a to-do list for the fix.

4. Fix the pins

I update the two rq: comments to basket_total and change Depends on [cart_total] to Depends on [basket_total]:

$ reqlan check
No issues.

Green again. Reqlan doesn't do the rename for you (there's no rename command in the CLI), it just tells you where the old name is still in use.

5. The pin that never failed

I almost stopped there. Then I grepped:

$ grep -rn cart_total --include=*.md --include=*.rq --include=*.ts .
./docs/checkout.md:3:<!-- rq:["../spec.rq".cart_total] -->

The Markdown pin still says cart_total, and check never mentioned it. It turns out it was never linked in the first place:

$ reqlan analyse -f docs/checkout.md
## Ideas in file
(none)

## Referencing ideas
(none)

## Comment-linked ideas
(none)

## Folder-referencing ideas
(none)

The reqlan.com docs show <!-- rq:[...] --> as the way to pin a Markdown doc, but on CLI 0.10.0 and 0.14.0 the index doesn't pick that comment up, so it can't go stale as far as check is concerned. A //-style rq: line inside a .md file does get checked, which suggests it's the HTML-comment form that isn't recognised. I've logged it as a bug for us to fix. Until it's fixed, don't count on a Markdown pin to catch a rename.

What it won't do

• It catches names that point at nothing. It won't tell you the renamed idea still means what the code does.
• It doesn't run your tests. cart.test.ts can pass, fail or assert 1 == 1 and check says the same thing. For test quality, use mutation testing alongside it.
• It doesn't rename anything. You fix each pin yourself (or grep and replace), then re-run check.
• Markdown <!-- rq: --> pins aren't checked on 0.10.0 or 0.14.0, as above. //-style comment pins and bracket refs inside .rq files are.

Takeaway

Rename the idea, run reqlan check, and every code pin and spec reference still using the old name shows up as a failure with a file and line. The Markdown case is a gap today, so grep for the old name once before you call it done.

Docs: https://reqlan.com. (Unrelated to SPARQL, which also uses .rq.)

Reproduce it: ./replay.sh in this folder runs every step against repo/ and prints the output above (saved in output.txt; output-0.14.txt is the same run on CLI 0.14.0).