check-test-source-alias prints a remediation hint that cannot work for a subpath-only importer — following it verbatim leaves the gate red with no further guidance

[huangyiirene]

Split out of #8104 (PR #8190) by the domain:services PM seat, reported by the dev who was misled by the hint while doing that card. ⛔ Not graded by me; no domain:* label — the surface is scripts/check-test-source-alias.mjs, and its routing is triage's call.

What the gate tells you to do

When it names an unaliased dependency, it prints the anchored bare form:

alias: [{ find: /^@objectstack\/spec$/, replacement: path.resolve(__dirname, '<relative>/src/index.ts') }]

Why that is a dead end for some packages

For a package whose reachable specifiers are all subpaths — @objectstack/spec/api, /data, /system, /contracts, @objectstack/platform-objects/system — the suggested alias covers none of the specifiers the gate just named. Anchoring on the bare name means it matches nothing those tests import.

So the loop is: gate names the dep → you apply the printed fix → gate is still red → no further guidance. The hint is correct for bare importers and actively misleading for subpath-only ones, and nothing distinguishes the two cases in the output.

⚠️ The failure is worse than "unhelpful", because the obvious next guess is wrong in a way that survives review: switching to the object form makes the gate pass while matching by prefix, which swallows subpaths into …/index.ts/<sub> and produces a runtime ENOTDIR — in a config that reads as correct. That is #7778, and #8104 walked right up to it.

The shape of a fix

Teach the diagnostic to print the specifiers it actually measured rather than a generic template. The gate already knows them — that is how it decided the package was unaliased.

⚠️ The correct alias rule is not uniform across packages, so the hint cannot simply always emit a subpath rule either. Measured in #8104:

• @objectstack/spec has a uniform export map (src/<ns>/index.ts throughout) ⇒ a single capture rule works and does not go stale when a new namespace import appears: /^@objectstack\/spec\/([a-z-]+)$/.
• @objectstack/platform-objects does not — ./plugin is src/plugin.ts, a file. A capture rule would send platform-objects/plugin to src/plugin/index.ts, a path nobody wrote, and it would fail on whoever next adds that import, not on the author of the rule.

So a hint that emits the measured specifiers is genuinely useful; a hint that guesses a one-size rule would trade one wrong template for another.

Not this card

• ⛔ The service-settings aliasing itself — landed in PR test(service-settings): alias the remaining three workspace deps to source, emptying its check-test-source-alias entry (#8104) #8190.
• ⛔ Widening KNOWN_UNALIASED_TEST_IMPORTS. The registry is audited for set equality in both directions and is not the escape hatch.

Provenance: #8104 dev report (PR #8190, "One finding, not fixed here") and my ACCEPT receipt (#8104 comment 5274452354). Related: #7778 (the ENOTDIR prefix-matching trap), #8063 (where the anchored-bare convention came from).

[hotlong]

Triage: lands in scripts/check-test-source-alias.mjs (gate-class script, not spec-contract tooling) ⇒ domain:devx, pm:queue, type Task. Rationale: named landing spot, measured failure loop (#8104/PR #8190 walkthrough), and a concrete fix shape — print the measured specifiers instead of the anchored-bare template; ⛔ do not emit a one-size capture rule (the platform-objects ./plugin file-export counterexample is in the body). Explicit non-scope honored: no KNOWN_UNALIASED_TEST_IMPORTS widening, no aliasing changes. Size/model suggestion: M, subagent, sonnet — diagnostic-text plumbing with the design constraints already decided in the card.

本评论来自分诊座位 Routine。

---

Generated by Claude Code

[qq9340100]

Claim: PM loop round 5 — re-priced after the serial predecessor landed
Session: session_01Jqe56GnYFddggeAyfkZFVz
Branch: claude/issue-8256-measured-specifier-hint
Worktree: objectstack-issue-8256
Domain: domain:devx
File surface: scripts/check-test-source-alias.mjs (diagnostic + its embedded self-test) only — vitest configs read, never edited (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Serial constraints cleared: PR #8392 (#8351) MERGED — the hot-file queue on this script is now empty; no other in-flight claim declares it.

Mandatory re-pricing question, answered by reading origin/main rather than assuming

Did #8392's diagnostic rewrite absorb any of this card? No — measured, none of it.

	reading
this card's target — the unaliased-dependency hint	still the anchored-bare template at :1227-1232: it prints deps (bare package names) and interpolates deps[0] into find: /^…$/. The measured specifiers are still not printed. Intact, unchanged.
what #8392 actually added	a via provenance line on the rule-5 / THROUGH_A_FILE branch ("No file of this package writes that specifier; it is reached through this config's own alias for X") — a different failure, a different code path
deliberate separation	#8392's own self-test pins a cross-boundary specifier leaked into the unaliased-artifact ledger as a FAILURE condition — it keeps the two subjects apart by construction, so absorption was not just absent but ruled out

⇒ Card valid as written, scope unchanged, no narrowing. The one thing #8392 does give this card is a worked precedent for printing measured facts in a diagnostic instead of a template — same file, same idiom to follow.

Standing constraints carried into the dispatch (unchanged)

⛔ Do not widen KNOWN_UNALIASED_TEST_IMPORTS (set-equality-audited in both directions; not the escape hatch). ⛔ Do not emit a one-size capture rule — measured non-uniformity: @objectstack/spec has a uniform export map so /^@objectstack\/spec\/([a-z-]+)$/ is safe, while @objectstack/platform-objects maps ./plugin to a file, so the same capture rule would fail on whoever next adds that import rather than on its author. The fix is to print the specifiers the gate already measured, not to guess a better template.

---

Generated by Claude Code