Skip to content

chore: AI ruleset, quality check, Vitest and smoke tests of the built bundles - #223

Merged
TobiasDuelli merged 3 commits into
masterfrom
chore-ai-ruleset
Nov 18, 2026
Merged

TobiasDuelli merged 3 commits into
masterfrom
chore-ai-ruleset

Conversation

@TobiasDuelli

@TobiasDuelli TobiasDuelli commented Nov 18, 2026 •

Copy link
Copy Markdown
Collaborator

The AI-coding kit that Frontend and Server have, adapted to an SDK that runs on customers' pages, plus a test setup: Vitest instead of Jest, and Playwright smoke tests of the built bundles. The shipped bundles are byte-identical to master.

The kit

Piece File Adapted how
Agent guide AGENTS.md, CLAUDE.md (@AGENTS.md) How the SDK ships (CDN latest on every merge, npm on tags, the Messenger frame), commands, Done, Public API rules, Stop and ask, Production. Every command and path checked. There was no CLAUDE.md before.
Code conventions .claude/rules/code-conventions.md No React/Tailwind/UI. PascalCase modules, named exports (src/index.js keeps its default), frozen-object constants, JSDoc, and a one-job-one-system table of the SDK's own helpers (storage, cookies, nonce, frames, postMessage, links, API requests, selectors, idle work, masking).
Code on the host page .claude/rules/host-page.md New: one global, teardown, never throw into the page, CSP and Trusted Types, frames and messages, privacy, load time and size, browsers. From the research below.
Testing .claude/rules/testing.md Vitest, node by default, jsdom by docblock, smoke tests for what only a real browser shows, fakes only at the edges.
Hooks .claude/settings.json, .claude/hooks/* Edit hook as Frontend. Stop hook: quality check, npm run typecheck (the typings) and vitest related.
Test writer .claude/agents/test-writer.md Vitest, smoke tests, host-page checks.
Review .claude/commands/review.md Server/Messenger format; checks are public API, host page, CSP, messages, privacy, size.
Push hook .githooks/pre-push, .githooks/install.sh Byte-identical to Frontend (default branch is master here too). Installed by prepare and by the setup script.
Quality check tools/quality/*, .github/workflows/quality.yml Core byte-identical to Frontend, see below. config.mjs: src/**/*.js, not tests, *.generated.* or the vendored src/unique-selector; PascalCase file names; <Name>.test.js candidates; JS-flavoured fix texts. check.test.mjs runs the shared core cases plus this config's cases under Vitest (268 tests).
CI .github/workflows/ci.yml Unit tests, typings, build, smoke tests, npm pack --dry-run. Same job name as before. Actions pinned by SHA like Frontend.
Setup scripts/setup-worktree.sh Push hook, npm ci (puts the rebuilt build/ back), Playwright's Chromium. Copies no .env.

Quality core: the fix "find the default branch instead of assuming origin/master" is not on Frontend's master yet. The core here is copied from fix-quality-core-default-branch at b2deefd0d2 (draft GleapSDK/Frontend#3079), core.sha256 08c8424e…. If that PR changes before it merges, copy the core again.

Two adaptations so the shared core cases pass in a JavaScript repo: the stop hook always runs npm run typecheck (here a few seconds for index.d.ts), and the "new runtime package" check lives in a smoke test instead of a banned import. A config-level ban collided with a core case.

Research: what was adopted, and what was rejected

Adopted:

Topic Rule Source
Public API Never remove or rename in a minor. Deprecate with @deprecated, a CHANGELOG entry and the behaviour kept. Typings updated in the same PR. Options object from the 3rd parameter. A smoke test checks index.d.ts against window.Gleap. semver, Node packages
Size A budget per bundle, brotli as served, enforced in CI and raised only with a reason (the size-limit idea, without the dependency). size-limit
Globals One global and no prototype changes. Wrappers of fetch, XHR or console restore only their own patch. Passive listeners, and every listener has a teardown. MDN addEventListener
CSP / Trusted Types No eval or string timers. Nonce on every script and style. No style attributes or cssText. No new HTML sinks with outside text. MDN style-src, Trusted Types, policy containers
Messages frameTargetOrigin out. event.source or an exact origin in. Unknown names are ignored. MDN postMessage, HTML web messaging
Browsers ES2020 targets as babel.config.js states them, feature detection, no polyfills. browserslist, Babel 8 migration
Load time Nothing runs at load. Idle work goes through runWhenIdle. Tasks stay under 50 ms. third-party JS, long tasks
Privacy Cookie and storage helpers, gleap- keys that are never renamed, masking at capture time, no fingerprinting. MDN cookies, W3C fingerprinting guidance
Testing Vitest and a separate Playwright test of the built bundle: browser mode would test the sources, not what customers load. Vitest migration from Jest, Playwright route

Rejected, with reasons:

  • api-extractor: heavy TypeScript tooling for one hand-written .d.ts; the smoke test covers the contract.
  • bundlewatch (needs a hosted service); webpack performance hints (uncompressed size only).
  • A default Trusted Types policy: it belongs to the customer.
  • Enforcing Trusted Types now: 46 existing innerHTML uses.
  • sandbox on our frames: they are same-origin and need scripts.
  • Lazy webpack chunks: with latest, an entry and its chunks can come from different versions.
  • Partitioned cookies: these are first-party cookies.
  • A consent UI in the SDK: the customer's consent manager owns consent.
  • Polyfills.
  • publint/attw in CI: a good next step, but publint flags the exports order, which would change the package's metadata. Left as an open point.

Test setup

Vitest, not Jest. It matches Frontend and NativeApp, and the research found no strong reason against it here: no Babel is needed for tests, it runs ESM natively, and it supports the docblock environments. Versions:

  • Vitest 4.1, not 5. Frontend is on 4.1, and Vitest 5 drops Node 25, which is this machine's Node.
  • jsdom 26, not Frontend's 29. jsdom 27 and later serialize !important margins with an extra shorthand, and jsdom 29 computes overflow-x from an overflow shorthand as visible. Both are wrong against real browsers, and 11 existing assertions caught them. jsdom 26 is also what Jest 30 ships.
master (Jest 29, jsdom 20) this branch (Vitest 4.1, jsdom 26)
Test files 42 42
Tests 767 passed 767 passed
expect() calls 1691 1691
Test names — 1:1. Only 16 parametrised titles render their value differently: quotes and escapes.

31 files changed mechanically (jest. → vi., the vitest import, the @vitest-environment docblock). 11 changed by hand, and no assertion changed:

  • GleapCSPNonce, GleapClickListener: isolateModules + require → vi.resetModules() + await import().
  • GleapCaptureLogs: requireActual → importOriginal.
  • GleapThemeManager: the real config manager comes from the module the test already imports.
  • GleapScreenRecorder: requireMock → import.
  • GleapSession: require('./Gleap') → import.
  • GleapFrameManager: the mock lists GleapCaptureManager: undefined, because Vitest throws on a missing mock export where Jest returned undefined.
  • GleapAdminOrigins, GleapHelper, GleapMessageSecurity, GleapReplayRecorder: test titles only (%p does not exist in Vitest; a %% bug).

Also: jsdom URL http://localhost/ as in Jest, and Node 25's own localStorage switched off in workers, as in Frontend.

New, npm run test:smoke (Playwright, Chromium headless shell, every request answered or aborted in the browser):

  • The CDN bundle adds only window.Gleap, with no error.
  • Every function index.d.ts declares exists on window.Gleap, except setLiveSite, which is declared but missing (open point).
  • initialize under script-src 'nonce-…' 'strict-dynamic'; style-src 'nonce-…' with the API unreachable: no CSP violation and no page error.
  • The ESM bundle exports the same Gleap.
  • The npm entry points load in Node without a DOM (SSR).
  • Size budgets: CDN bundle ≤ 180 KB brotli (170.7 today), survey-embed.js ≤ 2 KB.
  • src imports only the declared runtime packages.

Checked against mutations: a leaked global and a <style> without a nonce fail it, and so does import 'rrweb'.

New, npm run typecheck: tsc --strict on index.d.ts.

The shipped SDK is unchanged

Built with each tree's own npm ci (Node 25.8.1): a clean master checkout (0296b6b) against this branch.

File master branch
build/browser/index.js 49c08a4096ae3f84 same
build/browser/index.js.map 6db5d88cb9546d35 same
build/cjs/index.js cbebe2511da78648 same
build/cjs/index.js.map a5e80a71f308b336 same
build/esm/index.mjs 95a9016ed95e69c3 same
build/esm/index.mjs.map 96dfe72f0740a453 same
build/embed/survey-embed.js 6f3feabe32d14c4b same
  • published/19.8.1/ is identical.
  • The npm tarballs differ only in package.json (scripts and devDependencies).
  • sdk.gleap.io/latest/index.js today has the same SHA-256 as both builds, so the CDN build is reproducible.
  • No runtime dependency changed. Of the build packages (Babel, webpack, terser, browserslist, caniuse-lite) none moved in the lockfile; only source-map-js went 1.2.1 → 1.2.2 (postcss, CSS only), and the output is unchanged.

Dependencies

Added (dev): vitest ^4.1.12, jsdom ^26.1.0, @playwright/test ^1.65.1, typescript ^5.9.3 (quality check and typings check). Removed (dev): jest, jest-environment-jsdom, and with them scripts/testMock.js. Runtime: none.

Other file changes:

  • release.yml: npm test -- --ci → npm test, because Vitest refuses --ci and the next release would fail. This is the only change there.
  • prepare also installs the push hook; it fails silently when that is not possible.
  • .gitignore: Playwright's output folders.

Repo hygiene (lists only, nothing changed)

  • Auto-delete branches after merge: off (Server: on).
  • Secret scanning and push protection: off. They are free for public repos.
  • master protection compared with Server: the same in effect. The org ruleset gives 1 approval, no force push and no deletion; Server also has a classic rule that only duplicates it. Neither has a required status check, so CI is not a merge gate.
  • Open PRs older than 30 days:
  • Branches: 125 fully merged into master. 14 more are squash-merged PR heads, also safe. Unmerged work without a PR:
  • Dependabot: no dependabot.yml; 165 open alerts. All 3 criticals are dev-only (webpack-dev-server). The 9 runtime-scope alerts (postcss, nanoid, source-map-js via rrweb-snapshot; fflate via @rrweb/packer) do not reach the CDN bundle. Proposal below.
  • Secrets: GitHub secret scanning is off (404). gitleaks over the full history (1764 commits, build/ and published/ included) found nothing in the code, the bundles or config, and no .env, .npmrc or key file was ever committed. It found 2 expired third-party tokens with personal data in old commits of a demo file. Details went to the maintainers privately, not into this public PR.
  • Archive candidates:
    • 12.4 MB of unreferenced demo/ media
    • demo/index.js, demo/appwidget.* and demo/index.min.css from 2022
    • swa-cli.config.json (Azure, unused)
    • scripts/getPackageJson.js (unused)
    • deploy:staging (no staging env in wrangler.jsonc)
    • The committed build/ and published/latest/ are stale at 19.4.1 and unused by releases.
Proposed .github/dependabot.yml
version: 2
updates:
  - package-ecosystem: npm
    directory: /
    schedule:
      interval: weekly
      day: monday
    open-pull-requests-limit: 5
    cooldown:
      default-days: 7
    ignore:
      # Majors are planned by hand (bundle size, browser support, build config).
      - dependency-name: "*"
        update-types: ["version-update:semver-major"]
    groups:
      security:
        applies-to: security-updates
        patterns: ["*"]
      runtime:
        dependency-type: production
        update-types: [minor, patch]
      dev:
        dependency-type: development
        update-types: [minor, patch]
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
      day: monday
    open-pull-requests-limit: 2
    groups:
      actions:
        patterns: ["*"]
125 branches fully merged into master

v3.1.10 2021-01-27

new-screenshot-capture 2021-03-13

network-intercepter 2021-03-25

Readme-Update 2021-03-26

Replays 2021-04-27

fix 2021-07-13

v5.0 2021-07-20

v5.0-app-ui 2021-08-16

Gleap 2021-08-30

Outbound-Actions 2021-11-02

randomize-multiple-choice 2022-01-24

capturewidget 2022-01-27

v8-movedtofixed 2023-01-09

bot 2023-04-06

v8 2023-06-19

v12.0.0 2023-09-30

Banner-z-index 2023-10-05

Tooltips 2024-03-27

tooltipsnew 2024-04-22

tooltip-mute-fix 2024-07-29

show-back-button-refactor 2024-09-09

chore/remove_ds_store 2025-03-05

Checklist-component 2025-04-07

engagement-tooltip-fix 2025-04-24

modal-action-button-url 2025-05-13

url-match-regex-fix 2025-09-25

screen-recorder-audio-fix 2025-10-06

url-regex-fix 2025-10-08

Added-AI-chatbar 2025-10-14

region-access 2025-10-29

checklist-producttour-action 2025-12-04

video-call-permissions 2025-12-09

red-dot-video-call 2025-12-12

checklist-callback-events 2025-12-15

checklist-event-updates 2025-12-17

complete-checklist-data 2026-01-08

hide-tooltip-on-click 2026-01-12

collapse-button-clickable 2026-02-02

default-cookie-set 2026-03-02

fix-child-repositions 2026-03-17

imp/default-font 2026-03-18

fix-flickering-tours 2026-03-19

fix-stale-activeelement 2026-03-26

fix-radix-pointer-events-conflict 2026-04-27

gleap-code/69ef75836eac35243fb454d8-7c4cb684-74fa-4f6a-9d41-b983f4770708 2026-04-27

ai-agents 2026-05-06

aichatbar-hiding-fix 2026-05-07

observe-aichat-style-change 2026-05-07

page-filter-or-operator 2026-05-08

aichatbar-agent-name 2026-05-08

fix-product-tour-selector-anchor 2026-05-12

iframe-optimization 2026-05-21

iframe-tracking-workaroung 2026-05-21

info-card-loading-fix 2026-05-21

firefox-loading-fix 2026-05-21

ai-chatbar-mobile-style 2026-06-23

ai-chatbar-rework 2026-06-29

start-agent-method 2026-06-30

agent-frontend-tool 2026-07-02

fixed-chatbar-url 2026-07-06

replay-improvements 2026-07-14

conversation-read-notification-clear 2026-07-16

widget-home-v4 2026-07-16

feature/company-identification 2026-07-21

tour-selector-autofill-fix 2026-07-22

loading-background 2026-07-24

gleap/141665-marker-scroll-drift 2026-07-24

gleap/141852-checklist-link-nested-target 2026-07-26

141887-widget-version-opt-in 2026-07-27

gleap/143124-openfeaturerequests-backbutton 2026-08-07

gleap/143226-csp-block-console-warning 2026-08-10

gleap/143352-preserve-identity-transient-session-failures 2026-08-10

gleap/modal-max-height 2026-08-12

gleap/143745-screencapture-animations-quadratic 2026-08-13

gleap/notification-card-redesign 2026-08-17

fix-145001-cobrowse-tour-audio-state 2026-08-24

gleap-145754-cobrowse-bubble-linebreaks 2026-09-01

gleap/146130-modal-blank-fallback 2026-09-03

kai/kai-alert-blocking-asset-creatio-88e84a07 2026-09-09

feat/widget-realtime-domain 2026-09-14

gleap/147158-corp-headers 2026-09-15

v18-regions 2026-09-18

feat/authenticated-conversation-files 2026-09-21

gleap/147738-bounded-replay-buffer 2026-09-21

chore/bump-18.0.1 2026-09-21

codex/public-repo-messaging-ai-domain 2026-09-23

readme-types-react-requirement 2026-09-24

gleap/148186-env-data-filter 2026-09-25

claude/screenshot-blocked-content 2026-09-26

release-18.1.1 2026-09-26

claude/blocked-placeholder-layout 2026-09-26

claude/logs-v2 2026-09-27

feature/messenger-expand-window 2026-09-29

kai/auto-detect-host-app-dark-light--a815aa69 2026-09-30

ci/release-automation 2026-09-30

claude/tour-popover-flex-gap 2026-10-01

claude/capture-requests 2026-10-01

release/19.1.0 2026-10-01

fix-admin-origin-gleap-ai 2026-10-06

kai/inline-banner-not-working-in-app-2679e2e9 2026-10-08

feat/surveys-v2 2026-10-08

feat/survey-skip-known 2026-10-08

release/19.2.1-js 2026-10-08

release/19.2.2-js 2026-10-09

kai-code/4dc7f75eadb0e18f71944376-36e00863-dbe0-4adf-9e7c-3f64884716b3 2026-10-09

fix-websocket-close-code 2026-10-11

feat/capture-ui-v2 2026-10-12

fix-e2e-live-20261012 2026-10-13

fix-e2e1013-capture 2026-10-13

fix-e2e1013-postmessage-security 2026-10-13

fix-e2e-release-20261013 2026-10-13

chore/release-19.3.1 2026-10-14

fix-screenshot-iframes 2026-10-14

feat/custom-action-data 2026-10-19

feat/adopt-session 2026-10-19

chore/release-19.3.5 2026-10-21

fix-225880-clear-identity-notification-cache 2026-10-21

fix-disable-cached-notifications-20261022 2026-10-22

gleap/226492-contact-lang-update 2026-10-27

chore/release-19.3.6-with-226492 2026-10-27

fix-226629-226620-tooltips 2026-10-28

chore/version-19.8.0 2026-11-09

kai-code/6afb09cb89dd294a61737312-addb9dd0-e586-40d7-80dd-0c08d96f8b8f 2026-11-16

types/missing-declarations 2026-11-16

shadow-dom-tours 2026-11-17

Open points

  1. Versioned CDN URLs 404: sdk.gleap.io/19.5.0, 19.6.x, 19.7.0 and 19.8.0 return 404, and 19.8.1 will too after the next release. Since 19.5.0 no published/<version>/ folder is committed, and the Workers build adds only the current version. Decide: commit version folders again in each release, or store them elsewhere (R2). AGENTS.md states the mechanism and leaves releases to people.
  2. Gleap.setLiveSite is declared in index.d.ts but does not exist, so TypeScript callers get a runtime TypeError. Remove it from the typings or add it. The smoke test lists it as the one known gap.
  3. unique-selector is a runtime dependency nobody imports (the vendored copy in src/unique-selector is used). Every npm consumer installs it.
  4. Required status check: make Test, build and pack and quality required on master.
  5. Unused or old dev dependencies: nothing references eslint 8 with @babel/eslint-parser (no config), uglify-js, babel-preset-minify or @node-minify/*; wrangler 3 is a major behind and has a high alert. No lint step in this PR: there is no ESLint config to adopt.
  6. publint flags types last in exports. Fixing it changes package metadata, so it was left out here.
  7. Secrets in history: the 2 tokens above (reported privately) need a decision: inform the owner, confirm revocation, decide whether to rewrite history. Turning on secret scanning and push protection costs nothing on a public repo.
  8. Quality core: re-copy if GleapSDK/Frontend#3079 changes before it merges.

🤖 Generated with Claude Code

TobiasDuelli and others added 3 commits November 18, 2026 14:34
AGENTS.md, rules for code conventions, code on the customer's page and tests,
the edit and stop hooks, the test-writer agent, the review command, the
pre-push hook, the setup script, and the quality check that judges only what a
branch adds, with its CI workflow. The quality core is byte-identical to
Frontend's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The 767 unit tests run on Vitest 4.1 with jsdom 26, unchanged in what they
assert. Playwright loads the built bundles in Chromium: one global, every
function index.d.ts declares, a strict nonce CSP, the ESM build, Node without
a DOM, size budgets and the declared runtime packages. npm run typecheck checks
index.d.ts. CI runs all of it; release.yml drops Jest's --ci flag, which
Vitest refuses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Copied from Frontend's fix-quality-core-default-branch (b2deefd0d2, draft PR
GleapSDK/Frontend#3079), which is not on Frontend's master yet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@TobiasDuelli
TobiasDuelli marked this pull request as ready for review November 18, 2026 14:00
@TobiasDuelli
TobiasDuelli merged commit e5308a6 into master Nov 18, 2026
2 checks passed
@TobiasDuelli
TobiasDuelli deleted the chore-ai-ruleset branch November 18, 2026 20:31
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants