docs: linking javascript documentation - #4

Issues from the review (#1, #2, #3, #6, #7, #8 in review numbering;
#4 deferred to a follow-up).

#1 — convert() regression: when a global ruleDataProvider is set, the
previous `if (goalRule || this._ruleDataProvider)` always entered the
rule-eval block and hit `if (!goal?.rules) return`, silently dropping
every rule-less goal conversion. Gate on `goal.rules` first; preserve
the pre-PR contract that an explicit `goalRule` on a rule-less goal
still returns undefined.

#2 — Per-change marker IDs now scoped by experience + variation +
change id (conv-chg-${experienceId}-${variationId}-${change.id}-…)
instead of just `change.id`. Defense against future ID-semantics
changes or two configs merged on one page.

#3 — Validate ruleDataProvider at DataManager construction. A
provider missing the `name: 'RuleData'` discriminator would fall
through RuleManager's flat-key branch and silently return false for
every rule, breaking all audience matching with no error surfaced.
Warn and ignore the provider so the misconfiguration is visible.
Also introduces a proper `RuleDataProvider` interface in
@convertcom/js-sdk-types replacing the raw `Record<string, any>` on
Config.ruleDataProvider, so consumers get type guidance.

#6 — Replace `(change as any).data` access in runVariation with a
structural type assertion narrowed to the css/js/custom_js subset.

#7 — Delete the no-op "Should store ruleDataProvider on the
DataManager instance" test; the next test covers the same behavior.

#8 — Add four missing tests:
- runVariation execution order (global_css → global_js → per-change
  css → js → custom_js) verified via appendChild monkey-patch
- runVariation warn-and-continue when options.experience is omitted
  and the experienceKey isn't in config
- convert() fires for a rule-less goal when ruleDataProvider is set
  (regression guard for #1)
- DataManager warns and ignores a provider missing the `name`
  discriminator (regression guard for #3)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Three issues from the follow-up review (issue #3 in that review,
about the types.gen.ts manual override, deferred per request).

Review #1 — `runExperience` honors `experienceTypes` filter.
The singular path silently ignored the option even though
BucketingAttributes advertised it. Wire `experienceTypes` through
`Context.runExperience` and `ExperienceManager.selectVariation`/
`selectVariationById`: short-circuit to `null` when the experience
type isn't in the filter. Brings parity with `runExperiences`,
`runFeature`, and `runFeatures`.

Review #2 — Flip `ruleDataProvider` precedence and document.
Previous behavior: the globally-configured provider always won over
per-call args (`provider || arg`). That's the opposite of how
config-vs-args APIs normally layer and silently discarded an
explicit `goalRule` on `trackConversion`. Flipped to `arg || provider`
at all four DataManager rule-eval call sites
(site_area locations, selectLocations, filterMatchedRecordsWithRule,
convert). Also broadened the two outer `if (visitorProperties)` /
`if (locationProperties)` guards so the provider remains reachable
when the caller omits the per-call arg.

Updated tests: the original "provider beats per-call props" test
becomes "provider is used when no per-call props are supplied", plus
a new "per-call props win over provider" test guarding the flip.
Precedence is now documented on `Config.ruleDataProvider` and in
`RuleDataProvider.ts`.

Review #4 — `experienceTypes: []` means "no matches", not "all".
Previously `if (!typeFilter?.length)` treated `[]` the same as
`undefined`. Empty array now correctly means "zero types allowed —
no experiences match", matching standard array-filter intuition.
`undefined` and omission still mean "no filter applied". Behavior is
documented on `BucketingAttributes.experienceTypes` and the
`selectVariations` source. New test asserts empty-array → empty
result.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…tion

Two remaining items from the Gemini review on the prior commit:

#3 — `runVariation` Visual Editor check used `c?.data?.['js']` bracket
access while the rest of the body uses dot access (`data.css`, `data.js`,
`data.custom_js`). Align via a narrow structural cast,
`(c as {data?: {js?: string}})?.data?.js`. No behavior change.

#4 — `experienceId` falls back to `'unknown'` when both `experience.id`
and `bucketedVariation.experienceId` are missing, so DOM marker IDs
never interpolate the string `'undefined'` (which would collide with
any other change whose ids were also undefined). Degenerate-config
guard; should never trigger with a valid config.

SonarCloud duplication on new code — the new mocha tests in
`data-manager.tests.ts` and `experience-manager.tests.ts` each
repeated the same `server.on('request', …)` boilerplate 4-5 times,
pushing new-code duplication to 4.9% (gate is ≤3%). Extracted an
`awaitTrackRequest(server, accountId, projectId, done, assertFn)`
helper in each file and refactored only the NEW blocks added by this
PR. Pre-PR blocks left untouched to keep the diff minimal.

`yarn lint --fix` additionally removed three now-unused
`eslint-disable-next-line mocha/no-hooks-for-single-case` directives
on hook blocks that gained a second test case during this PR. Tests:
mocha 352/352 passing locally, Playwright 45/45 passing (including 9
runVariation tests).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

…tion

Two remaining items from the Gemini review on the prior commit:

#3 — `runVariation` Visual Editor check used `c?.data?.['js']` bracket
access while the rest of the body uses dot access (`data.css`, `data.js`,
`data.custom_js`). Align via a narrow structural cast,
`(c as {data?: {js?: string}})?.data?.js`. No behavior change.

#4 — `experienceId` falls back to `'unknown'` when both `experience.id`
and `bucketedVariation.experienceId` are missing, so DOM marker IDs
never interpolate the string `'undefined'` (which would collide with
any other change whose ids were also undefined). Degenerate-config
guard; should never trigger with a valid config.

SonarCloud duplication on new code — the new mocha tests in
`data-manager.tests.ts` and `experience-manager.tests.ts` each
repeated the same `server.on('request', …)` boilerplate 4-5 times,
pushing new-code duplication to 4.9% (gate is ≤3%). Extracted an
`awaitTrackRequest(server, accountId, projectId, done, assertFn)`
helper in each file and refactored only the NEW blocks added by this
PR. Pre-PR blocks left untouched to keep the diff minimal.

`yarn lint --fix` additionally removed three now-unused
`eslint-disable-next-line mocha/no-hooks-for-single-case` directives
on hook blocks that gained a second test case during this PR. Tests:
mocha 352/352 passing locally, Playwright 45/45 passing (including 9
runVariation tests).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>