`registerFunction` JSDoc uses one name for two entities — the `evaluateExpression` method and the module-level export

[os-sales]

Filed during PM review of PR #5578 (card #5363). Not a defect — every statement in that block is true, and TypeScript rejects the wrong reading at the call site. Recorded because the imprecision sits in a doc block whose entire subject is a name that does not behave the way it reads.

What is there

packages/core/src/evaluator/ExpressionEvaluator.ts exports two things spelled evaluateExpression:

entity	line	signature	on failure
method on ExpressionEvaluator	:142	evaluateExpression(expression, { sanitize? }) — takes a bare expression, no ${...} wrapper	throws Failed to evaluate expression "..."
module-level export	:368	evaluateExpression(expression, context, options) — delegates to evaluator.evaluate(...)	fail-soft; returns defaultValue ?? expression

PR #5578's new JSDoc on registerFunction refers to both, under the one spelling, four lines apart:

• the prose — "{@link evaluateExpression} is the throwing sibling, and reports 'formatCurrency' is not a function" — resolves, per TSDoc, to the method. Correct.
• the final @example line — evaluateExpression('${formatCurrency(price)}', { formatCurrency: fmt, price: 1234.5 }); // '$1,234.50' — is the module-level export: second parameter is a context bag, and the ${...} wrapper only resolves on the evaluate path. Also correct.

Why it is worth recording rather than fixing in place

Bound to the method instead, that example line does not merely return something else — it throws, because a bare ${formatCurrency(price)} is not a valid JS expression. The two lines above it establish evaluator. as the receiver, and a .d.ts hover carries no import statement to disambiguate.

The harm is bounded, which is why this is a finding and not a rework: the method's second parameter is typed { sanitize?: boolean }, so passing a context bag is a compile error, not a silent wrong answer. The reader is corrected by the compiler at the moment of the mistake.

Shape of a fix

Qualify both references in that block — {@link ExpressionEvaluator.evaluateExpression} for the method, and a receiver or a comment marking the example's last line as the module-level helper. One line, no behaviour, no test.

Refs

• finding(core): ExpressionEvaluator.registerFunction upper-cases the name, so a lower-case call in an expression renders its own ${...} source #5363 / PR docs(core): state the registerFunction case-fold on the method itself #5578 — where the block was added
• packages/core/src/evaluator/ExpressionEvaluator.ts:142 (method) and :368 (export)
• the merge order that makes the example's claim true: const mergedContext = { ...formulaObj, ...contextObj } at :160 — context is spread last, so context entries win over formulas and keep their exact spelling

[huangyiirene]

Triage (first-touch grading): promoted finding → pm:queue, domain:ui, type Task. Rationale: one-line doc qualification in a published .d.ts hover surface where the ambiguity is real (two exported entities share the spelling four lines apart, and the wrong binding of the example line throws rather than returns) — but the harm is compiler-bounded, so this is the smallest tier of queue work, not urgent. Fix shape is already specified on the card: qualify the prose link as {@link ExpressionEvaluator.evaluateExpression} and mark the example's last line as the module-level helper. No behaviour, no test.

Dispatch note: S mechanical, sonnet floor acceptable; good batch-filler alongside any other packages/core docs touch — fold-or-serial answer owed only if an in-flight PR is editing the same JSDoc block (PR #5578 authored it; confirm merged before claiming).

---

Generated by Claude Code

[os-sales]

Claim: PM loop round 11
Session: session_012u2pRjcqAYtoEjgr3wwhnK
Branch: claude/issue-5580-evaluateexpression-jsdoc
Worktree: objectui-5580
Domain: domain:ui (execution seat)

File surface: packages/core/src/evaluator/ExpressionEvaluator.ts (JSDoc only). ⛔ OUT: packages/core/src/actions/** — #5611 has an open draft there, held pending a contract review.

Clause ②: no — prose only, no declaration moves, no behaviour.

This is a PROSE-ONLY card, which scopes one criterion. The dist/*.d.ts heuristic applies here and only here: expect dist/**/*.d.ts to move (JSDoc is emitted into declarations) and dist/**/*.js to be byte-identical. That prediction is worth stating and then measuring — it is the cheap check that tells you whether the change reached the published surface at all. On a behaviour card it inverts, which is why it must never be carried across.

Nonetheless check-changeset-presence.mjs is the authority on whether a changeset is owed. Run it; do not reason from the .d.ts result.

⛔ --removeComments proves zero program semantics — it is INVALID as evidence for any shipped-bytes claim.

---

Generated by Claude Code

[os-sales]

Claim amendment — file surface +1 (same round), and a correction to the card's premise.

Session: session_012u2pRjcqAYtoEjgr3wwhnK · Branch: claude/issue-5580-evaluateexpression-jsdoc

Added to the declared surface:

• packages/core/src/evaluator/__tests__/registerFunction-jsdoc-links.test.ts (new)

Still ⛔ OUT and untouched: packages/core/src/actions/** (#5611's draft).

Why the extra file. The dispatch asked that the corrected {@link} bindings be made checkable rather than asserted — "a TSDoc {@link} that still binds to the wrong entity looks identical in source to one that binds right." Nothing in this repo resolves link targets: no lint rule, no runtime observation. The only thing that performs the binding is the TypeScript checker, so the new test asks the checker directly, over the source file (no dist in the loop). It follows the existing house pattern for compiler-driven pins (packages/core/src/utils/__tests__/freeze-schema.types.test.ts), including that precedent's built-in discrimination leg.

Correction to the card — one sub-claim is measured false. The card states the prose {@link evaluateExpression} "resolves, per TSDoc, to the method. Correct." and concludes "Not a defect — every statement in that block is true." Measured with checker.getSymbolAtLocation on the pre-fix source:

@link line 370: "evaluateExpression" -> ExpressionEvaluator.ts:405 [FunctionDeclaration]

That is the module-level export — the fail-soft one — inside a sentence that calls it "the throwing sibling." So the block did contain a false statement, and this is a small real defect rather than pure imprecision. After qualification:

@link line 371: "ExpressionEvaluator.evaluateExpression" -> ExpressionEvaluator.ts:142 [MethodDeclaration]

The neighbouring {@link evaluate} binds to the method only because no module-level evaluate exists to outrank it — so "unqualified links resolve to the enclosing class's member" is false here, which is exactly the reading the card relied on. The card's :368 line number was also stale (PR #5578 shifted the export to :405); :142 still holds.

Scope unchanged otherwise: no behaviour, no declaration moves.

---

Generated by Claude Code

[os-sales]

{
 "issue": 5580,
 "status": "done",
 "branch": "claude/issue-5580-evaluateexpression-jsdoc",
 "pr": "https://github.com/objectstack-ai/objectui/pull/5649",
 "premise_still_valid": true,
 "summary": "Both `evaluateExpression` references in the `registerFunction` JSDoc are now qualified: the prose link became `{@link ExpressionEvaluator.evaluateExpression}` and the `@example`'s last line names the module-level export and shows the import it needs. The card's premise holds and the fix shape was right, but TWO of its assertions are measured false and PM should note both. (1) Line `:368` was stale — PR #5578 shifted the module-level export to `:405`; `:142` still holds. (2) More importantly, the card's central claim that the prose `{@link evaluateExpression}` 'resolves, per TSDoc, to the method. Correct.' and therefore 'Not a defect — every statement in that block is true' is WRONG: the checker resolved it to the module-level FunctionDeclaration at :405 — the FAIL-SOFT one — inside the sentence calling it 'the throwing sibling'. So the block did contain a false statement and this was a small real defect, not pure imprecision. The neighbouring `{@link evaluate}` binds to the method only because no module-level `evaluate` exists to outrank it, so the rule the card relied on does not hold here. Scope: dispatched surface plus ONE declared test file (amended on this issue before it was committed); fence held, `packages/core/src/actions/**` untouched; no behaviour change, no declaration moves.",
 "tests": "All at 3de60fdcd, the branch head; exit codes captured before any pipe, each gate's own verdict line quoted. `pnpm exec vitest run packages/core/` -> CORE_VITEST_EXIT=0, 'Test Files 94 passed (94)' / 'Tests 1950 passed (1950)' (93->94 files and 1945->1950 tests vs PR #5578's figures — exactly the one file and five cases added here). `pnpm exec vitest run packages/core/src/evaluator/` -> EXIT=0, 'Test Files 12 passed (12)' / 'Tests 364 passed (364)'. New pin alone -> EXIT=0, 'Tests 5 passed (5)'. `pnpm --filter @object-ui/core type-check` -> EXIT=0 (script name echoed in output, so not the zero-match silent pass). `pnpm --filter @object-ui/core lint` -> EXIT=0, '513 problems (0 errors, 513 warnings)' = pre-existing baseline unchanged. check-changeset-presence EXIT=1 BEFORE / EXIT=0 AFTER ('2 source file(s) of 1 released package(s) changed, and this change declares 1 changeset(s)') — run as the authority, not inferred from the .d.ts result. check-changeset-fixed EXIT=0, check-changeset-no-major EXIT=0, check-control-bytes EXIT=0 ('scanned 4697 tracked text file(s)'), check-package-self-import EXIT=0 ('0 self-import' across 16132 specifiers — relevant because the new @example line contains `import ... from '@object-ui/core'` INSIDE packages/core). ABLATION, external: source reverted to origin/main, suite re-run -> ABLATED_VITEST_EXIT=1, 'Tests 2 failed | 3 passed (5)'. Direction was predicted before the run and matched: the in-suite ablation case stays GREEN under external ablation (with the source already bare, the mutated copy equals the original), stated rather than counted as evidence. Mutation confirmed ON DISK by anchored `grep -cF` on both removed and injected text — asserted pristine (1/0) BEFORE mutating, inverted (0/1) after — never an editor exit code; script carried `trap ... EXIT INT TERM`; tree verified clean after. REBUILD: every measurement leg was a clean build with `dist/` AND `packages/core/tsconfig.tsbuildinfo` cleared — the build info lives OUTSIDE dist, so clearing dist alone would have skipped emit. Determinism cross-checked both directions: the pre-fix rebuild reproduced the original baseline hashes exactly and the restore rebuild reproduced the post-fix hashes exactly, so the movement is attributable to this edit and no mutated artefact was left in dist. NARROWING DECLARED (repo-wide lint/test left to CI): population read from eslint's own resolution = 186 files for packages/core, count read from --format json, and root eslint.config.js declares no projectService / parserOptions.project so linting is not type-aware and this diff cannot move a verdict in any untouched file. check:published-dist did NOT complete — it hit the container's 10-minute foreground cap (SIGTERM/143); its concern for this diff is answered directly (dist counts unchanged 90/90, no __tests__ dir in dist, no artefact bearing the test file's name), full scan belongs to CI. Known-broken gauges left untouched: check:eager-closure (exits 2), check:doc-snippet-types (exits 1; its population is .md/.mdx and package READMEs, so JSDoc @example in .ts is outside it either way).",
 "dts_js_movement": {
 "method": "All 90 .d.ts and 90 .js emitted files hashed with sha256, clean-built on both legs; dist and tsconfig.tsbuildinfo cleared each time. Hashes compared, not byte counts.",
 "dts_leg": {
 "predicted": "moves",
 "measured": "MOVED — prediction held",
 "files_changed": "exactly 1 of 90 (dist/evaluator/ExpressionEvaluator.d.ts); other 89 unchanged",
 "pre_fix_sha256": "8eb97d485032b3796ba1d950392d4a65c32898c933711a039abfa14104e194d7",
 "post_fix_sha256": "4948e9716473a54b59b92494f8dad7991fde55c3f7664fb32389e0cd0fa3ba08"
 },
 "js_leg": {
 "predicted": "byte-identical",
 "measured": "MOVED — PREDICTION FALSIFIED",
 "files_changed": "exactly 1 of 90 (dist/evaluator/ExpressionEvaluator.js); other 89 unchanged",
 "pre_fix_sha256": "478dcb806a454479aea5b209723a51c10b5ac5d9953e331a1907ac643a4a4f14",
 "post_fix_sha256": "1fcb9ffaf63abcce51eec98c897954562c2f5dc7c12fdb28897ff9c99cfbd5a1",
 "why": "packages/core builds with a bare `tsc`, which PRESERVES COMMENTS in the JS emit. JSDoc therefore reaches BOTH published artefacts, not only declarations. The heuristic as dispatched ('.js byte-identical on a prose card') does not hold for this package and should not be carried to the next prose card without re-measuring the package's build.",
 "semantics_evidence": "The intent behind the prediction still holds and is proven WITHOUT --removeComments: the emitted .js delta is 10 changed lines, of which 0 are non-comment lines, read from a direct textual diff of the two emitted files."
 }
 },
 "binding_checkable_or_asserted": {
 "verdict": "CHECKABLE — not merely asserted.",
 "how": "packages/core/src/evaluator/__tests__/registerFunction-jsdoc-links.test.ts asks the TypeScript checker directly (checker.getSymbolAtLocation on the JSDocLink name nodes) over the SOURCE file by relative path, so no build artefact sits between an edit and a result. Bindings are asserted as declaration kind + owning class ('MethodDeclaration' on 'ExpressionEvaluator' vs 'FunctionDeclaration' at module scope) rather than line numbers, so the pin cannot rot the way the card's :368 did.",
 "can_it_fail": "Measured on two independent mutation legs, not assumed. In-suite, every run: one case recompiles the same source through an in-memory host overlay with the single qualification removed and asserts the link lands back on the module-level FunctionDeclaration. Externally: reverting the source to origin/main turns the suite red (2 failed | 3 passed, exit 1).",
 "residual": "The @example's last line is plain code text inside a fence, not a {@link}, so nothing resolves it — that half remains prose-only and is NOT checkable. It is disambiguated by naming the module-level export and showing the import, and the import's truth was verified against the built package entry (both `evaluateExpression` and `ExpressionEvaluator` are exported from it)."
 },
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code