check:test-source-alias cannot read a template-literal alias replacement, so two packages that DO alias spec subpaths to source are still recorded as unaliased

[hotlong]

Filing unassigned; found while implementing #7991 (the packages/qa/downstream-contract source alias). Not fixed there — the card's ruling is that a problem surfaced by aliasing is a finding in its own right, and this one changes a shared gate's semantics plus two other packages' registry entries.

The fact, measured

scripts/check-test-source-alias.mjs reads an alias replacement with asPath(), which takes the last string literal in the expression:

function asPath(raw) {
 const strings = [...raw.matchAll(/(['"`])((?:[^\\]|\\.)*?)\1/g)].map((m) => m[2]);
 ...
 return strings[strings.length - 1];
}

For the path.resolve(__dirname, '../../spec/src/index.ts') form that is the whole answer. For the template-literal form — the one the gate's own two reference configs use for subpath rules —

{ find: /^@objectstack\/spec\/([a-z-]+)$/,
 replacement: `${path.resolve(__dirname, '../../spec/src')}/$1/index.ts` }

the only string literal delimiter reached is the backtick, so asPath returns the entire template body, ${path.resolve(__dirname, '../../spec/src')}/$1/index.ts. pointsAtSource() looks for a src path segment and there is none in that text (spec/src' is followed by a quote, not a separator), so a config that aliases every namespace correctly reads to the gate as aliasing nothing.

Evidence: changing only the SPELLING moves the verdict

packages/services/service-knowledge and packages/plugins/plugin-audit both alias spec subpaths to source with the template form today. Rewriting only the spelling — same resolution, no behaviour change:

replacement: path.join(path.resolve(__dirname, '..', '..'), 'spec/src/$1/index.ts')

makes the gate declare their registry entries stale:

 x @objectstack/plugin-audit: registry entry is STALE — no longer unaliased: @objectstack/spec.
 Narrow the entry to exactly: ["@objectstack/objectql"]
 x @objectstack/service-knowledge: registry entry is STALE — no longer unaliased: @objectstack/spec.
 Narrow the entry to exactly: ["@objectstack/objectql"]

So @objectstack/spec sits in both entries because of how the replacement is written, not because anything resolves through dist. (Both experiments were reverted; nothing in PR for #7991 touches those two configs.)

Direction, and why it still matters

Fail-closed. The gate never reads an unaliased package as safe, so its core guarantee is intact and this is not a #7991-shaped false green. What it does cost:

1. The shrink-only registry over-states the remaining work — at least two of the 62 entries name a dependency that is already aliased.
2. A dev dispatched to remediate either package finds the aliases already correct and the gate still red, with the failure text prescribing the alias they already have. The only thing that moves it is a spelling change; nothing in the message says so.
3. It quietly penalises the one-rule-for-all-namespaces form. That form exists because hand-listing namespaces goes stale, and both configs carry a paragraph explaining why they use it.

Fix options (not chosen here)

• A — teach asPath the template form: concatenate the literal chunks and treat each ${...} as an opaque prefix, so the tail /$1/index.ts joins the spec/src chunk. Keeps every existing config as written; the two entries then shrink to ['@objectstack/objectql'] in the same PR (the gate audits both directions, so it names them).
• B — prescribe the readable spelling in the gate header and convert the two configs; same registry shrink, no gate change.

A is the contract-first shape: the configs are correct, the reader is what cannot see them. Either way the change is one PR and its own card — it edits a shared gate plus two packages' entries, so it should not ride a per-package alias fix.

Prior art (searched before filing)

• A package with unit tests and no vitest.config.ts lets a stale @objectstack/core dist decide its verdicts — #7668 fixed one, nothing stops the next #7849 / PR ci(test-alias): gate that a unit test judges source, not a sibling's dist #7966 — the gate and the registry.
• packages/qa/downstream-contract — the repo's backward-compatibility gate for @objectstack/spec reports 14/14 green against a spec change that breaks its own fixture, because it reads spec/dist #7991 — the card this was found under; its config uses the path.join spelling deliberately, with a comment pointing here.
• attach-requires-parent-edit c3: #4757 multi-delete pin can't execute against the prebuilt @objectstack/core (stale-dist / CI) #7668 / PR test(service-storage): resolve @objectstack/core from source so a stale dist can't decide a pin (#7668) #7778 — the anchored-regex constraint the template form implements.

---

Generated by Claude Code

[hotlong]

Triage: lands in scripts/check-test-source-alias.mjs plus the two registry entries it names → domain:devx (shared gate, general test-resolution tooling); queued pm:queue.

Route suggestion (input, not a ruling): option A — teach asPath the template-literal form — is the contract-first shape: the configs are correct, the reader is what cannot see them, and B would penalise the one-rule-for-all-namespaces form both configs deliberately use. Shrink the two registry entries (plugin-audit, service-knowledge → exactly ["@objectstack/objectql"]) in the same PR, since the gate audits both directions and will name them.

Priority: normal — the gate is fail-closed today, so the cost is over-stated remediation work and a misleading failure text, not a false green.

---

Generated by Claude Code

[hotlong]

Claim: PM loop round 5
Session: session_01PaiisQMhsYxwa5ZX6Mfmv2
Branch: claude/issue-8020-template-literal-alias-reader
Worktree: objectstack-issue-8020
Domain: domain:devx
File surface: scripts/check-test-source-alias.mjs (reader + its registry entries) (stop on breach; explain in the report)
Container & model: M, mode:cloud, model: opus
Serial constraints cleared: ⚠️ scripts/check-test-source-alias.mjs is this lane's hottest serial file — #7991 and the other 62 remediation cards each delete their own registry entry. None is dispatched or in flight right now, so this goes first; whoever takes a remediation card next must re-derive rather than reuse a stale registry read. Sibling card #8024 claimed the same round is scripts/check-skill-frame-freshness.mjs — different file.

This is a defect in what this seat shipped ~4 hours ago (PR #7966, card #7849). Following it through is this seat's responsibility, not a new lane's.

Premise verified on origin/main, exactly as filed:

package	alias line	in registry as unaliased?
@objectstack/plugin-audit	vitest.config.ts:39 — replacement: `${path.resolve(__dirname, '../../spec/src')}/$1/index.ts`	yes (wrongly)
@objectstack/service-knowledge	vitest.config.ts:23 — same template-literal form	yes (wrongly)

Those are the only two files in the repo using the template-literal replacement form, and both are recorded as still resolving spec through dist/. They do not.

⭐ These two packages are the repo's alias-parsing canary — twice over

The same two packages defeated my own census this morning, by a different mechanism: I grepped objectstack/core and missed them because the anchored-regex form writes the bytes objectstack\/core with an escaped slash. Now the shipped gate misses them because their spec-subpath alias uses a template-literal replacement.

Two independent readers, two different parsing assumptions, the same two packages wrong both times. They are the ones whose alias spellings are unusual enough to break naive readers, which makes them the natural fixture for any tool that reads vitest aliases. Carried into the dispatch as a required test case rather than a nice-to-have.

---

Generated by Claude Code

[hotlong]

Registry before/after — the full delta

Measured with --list on both sides of the change. diff reports exactly two rows; every other line is byte-identical.

	before	after
@objectstack/plugin-audit	['@objectstack/objectql', '@objectstack/spec']	['@objectstack/objectql']
@objectstack/service-knowledge	['@objectstack/objectql', '@objectstack/spec']	['@objectstack/objectql']
registry entries	63	63 — unchanged; both packages keep objectql, so neither entry is deleted
package-dependency pairs	312	310

No package was reclassified that nobody suspected. The dispatch flagged that a reader newly parsing a form might surface more — it did not: the template-literal replacement appears in exactly two files repo-wide (10 of the 12 replacements in 15 alias-bearing configs are plain path.resolve(…) calls; zero use +), so the blast radius is the two entries predicted and nothing else.

Block 3 — evaluate the config, or keep parsing source text?

Measured before choosing, and the answer was decisive: stay with source-text parsing. There is no node_modules in this repo as the gate reaches it — ls node_modules fails at the repo root and in the worktree — and the gate runs dependency-free in ~3.0s, with a self-test that builds its fixture tree in tmpdir with none either. Every real config here opens with import { defineConfig } from 'vitest/config', so evaluation would trade a bare-checkout gate for one that cannot run before pnpm install, and would turn an alias list the gate merely reads into one it executes. Recorded in the asPath header so it is not re-litigated.

Legal spellings that remain unreadable, all fail-closed, enumerated in that header: + concatenation; a hole or argument with no string literal (${SPEC_SRC}, path.resolve(SRC_ROOT, 'index.ts')); a path that is not the last argument; a template nested inside a ${…} hole. The + form is the same defect one spelling over and is filed as #8108 rather than fixed here.

Reverse verification — direction predicted first, then measured

Predicted: removing the reader's new template branch while the registry stays shrunk flips the failure to the added direction, not STALE — the subpath aliases go invisible again, so @objectstack/spec re-enters the measurement while the registry no longer lists it.

Observed, matching:

 x @objectstack/plugin-audit: NEW unaliased artifact import(s) since this entry was measured: @objectstack/spec.
 x @objectstack/service-knowledge: NEW unaliased artifact import(s) since this entry was measured: @objectstack/spec.

The self-test went red on exactly the three predicted assertions — canary reported, the ${…} hole not failing as unreadable, the canary's both-directions audit — while the dist/ and ENOTDIR template fixtures stayed green, which was also predicted: the old reader happens to answer those two correctly, so they do not discriminate. Fix restored from the commit; tree clean.

{
 "issue": 8020,
 "status": "done",
 "branch": "claude/issue-8020-template-literal-alias-reader",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/8107",
 "premise_still_valid": true,
 "summary": "Taught `asPath` in scripts/check-test-source-alias.mjs the template-literal replacement form: it now splits a template into literal chunks and `${…}` holes, resolves each hole by the same last-string-literal rule, and concatenates, so the `$1` back-reference survives into String.replace and joins the `src` chunk. Both halves landed in one PR — the reader fix, then the registry shrunk to match reality: plugin-audit and service-knowledge each drop `@objectstack/spec`, leaving exactly ['@objectstack/objectql']. Neither packages/**/vitest.config.ts is touched; the configs were correct and the reader was what could not see them. Per the ⭐ clause both canary spellings are pinned together in one self-test fixture — escaped-slash regex `find` AND template-literal `replacement` — plus three fixtures keeping the new branch honest rather than permissive (template to `dist/` still unaliased, template through a file still ENOTDIR, `${…}` hole with no literal still UNREADABLE not empty). No allowlist was added; the registry stays shrink-only, per-package, exact-set, no numeric headroom.",
 "tests": "`node scripts/check-test-source-alias.mjs --self-test` -> 'check-test-source-alias --self-test OK'. `node scripts/check-test-source-alias.mjs` -> 'check-test-source-alias OK — 72 packages with tests scanned; 63 registered as still resolving a workspace dep through `dist/`' (before the fix, same command on the shrunk registry was RED with the two STALE lines the card predicted). `node scripts/check-nul-bytes.mjs` -> 'OK (scanned 7365 text file(s) … no raw ASCII control bytes)', plus a direct `grep -naP` control-byte scan of the changed file: none. `node scripts/pm/dispatch-gates.mjs scripts/check-test-source-alias.mjs` re-derived against the actual changed path -> 'No check family names the given paths in its own source'; check:nul-bytes applies by convention and was run. Reverse verification predicted-then-measured, direction matched (added, not STALE) — detail above. CI status at report time: in_progress; per the dispatch contract the convergence wait is the PM's.",
 "open_questions": [],
 "out_of_scope_findings": [
 "filed as #8108: check:test-source-alias still cannot read a `+`-concatenated alias replacement — semantically identical to the template form, zero occurrences in the repo today, so latent rather than live; filed `finding`, unassigned, no pm:queue"
 ]
}

Scope note: out of scope: #7849 — it stays the tracking anchor for the remaining remediation cards. #7849 remains open.

---

Generated by Claude Code

---

Generated by Claude Code

[hotlong]

ACCEPT — PR #8107. Reviewed against GitHub, not the report's self-description.

check	result
path surface (get_files)	1 file — scripts/check-test-source-alias.mjs. Zero packages/**/vitest.config.ts ⇒ ruling 3 honoured; the configs were right and stayed untouched
registry delta	exactly two entries narrowed, not removed: plugin-audit and service-knowledge each drop @objectstack/spec and keep @objectstack/objectql. Precise — those packages alias spec but genuinely still resolve objectql through dist/
CI	23 checks, zero failures

Both halves landed together per ruling 1: the reader learns the form, then the registry shrinks to match. Neither an allowlist nor a config rewrite — the two shapes ruling 2 and 3 forbade.

It rejected config evaluation with a measurement, which is what Block 3 asked for

I flagged "should the reader evaluate the config rather than pattern-match its source?" as possibly the real fix and possibly too heavy. Measured answer:

this gate runs on a bare checkout with NO node_modules (that is how CI reaches it, and how its own --self-test fixture tree in tmpdir works), while every real config opens with import { defineConfig } from 'vitest/config'. Evaluation would trade a dependency-free ~3s scan for one that cannot run before pnpm install, and would make an alias list the gate cannot see today into one it executes.

A constraint I did not know about, decisive, and it also names the security-shaped reason. Settled.

⭐ It built the canary I asked for, and made it sharper than the ask

Fixture (7) is a byte-for-byte copy of the real shape, pinning both spellings that have now defeated readers of these configs — escaped-slash regex find and template-literal replacement — with the reasoning recorded in place:

Those two packages have now defeated THREE readers of vitest aliases, twice on the same morning, by two different parsing assumptions … Neither spelling is exotic and neither is going away — the escaped slash is forced by the regex literal, the template by the capture group.

It also added the three fixtures that stop "read a template" degrading into "wave a template past": (8) a template landing on dist/ is still unaliased; (9) the ENOTDIR prefix trap is still seen through a template (proving the chunks are really joined); (10) a ${…} hole with nothing literal in it is UNREADABLE, not empty — the fail-closed half. Plus the both-directions audit on the canary, so a now-readable package registered by mistake names itself for deletion.

And it documented the spellings that remain unreadable — + concatenation ("the exact #8020 shape one spelling over"), non-literal holes, a path that is not the last argument, a nested template — each stated as fail-closed, "listed so the next one is looked up rather than rediscovered". That converts an unknown into a known limit, which is the whole difference between a gate you can trust and one you merely hope about.

Note on what this defect cost, since this seat shipped it

Worth recording plainly: check:test-source-alias shipped ~4 hours ago in PR #7966 and was fail-closed throughout — it never green-lit a stale-dist package. What it did was over-state the remediation list and tell two compliant packages to add an alias they already had. Real, worth fixing same-day, and materially less bad than the failure mode the gate exists to prevent. #7849 remains open as the tracking anchor for the remaining remediation surface, which is now two entries smaller and more accurate.

Marking ready and arming auto-merge. Tracked to MERGED with the closed_by_pull_requests check.

---

Generated by Claude Code