v12

.cursorrules

@@ -0,0 +1,2 @@
+- Check AGENTS.md for instructions specifically for AI
+- Check README.md for instructions

.eslintrc.js

@@ -0,0 +1,24 @@
+module.exports = {
+  env: {
+    browser: true,
+    commonjs: true,
+    es6: true,
+    node: true,
+  },
+  extends: "eslint:recommended",
+  ignorePatterns: ["dist/"],
+  globals: {
+    Atomics: "readonly",
+    SharedArrayBuffer: "readonly",
+  },
+  parserOptions: {
+    ecmaVersion: 2020,
+  },
+  overrides: [
+    {
+      files: ["test/**/*.js"],
+      env: { mocha: true },
+    },
+  ],
+  rules: {},
+};

.github/workflows/testing.yml

@@ -0,0 +1,133 @@
+name: Testing Suite
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  NODE_VERSION: 22.16
+
+jobs:
+  linting:
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ env.NODE_VERSION }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Run npm ci
+        run: npm ci
+
+      - name: Run npm prettier
+        continue-on-error: true
+        run: |
+          ./node_modules/.bin/prettier --check . || echo "::warning::Prettier found formatting issues. Fix it locally by running './node_modules/.bin/prettier --write .'"
+
+      - name: Run ESLint
+        run: ./node_modules/.bin/eslint --ext .js .
+
+  unit-tests:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ env.NODE_VERSION }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Run npm ci
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Run unit tests
+        run: npm run test:unit
+        env:
+          CI: true
+          NODE_ENV: test
+
+  build:
+    runs-on: ubuntu-latest
+    needs: unit-tests
+    if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch'
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ env.NODE_VERSION }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Run npm ci
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Commit build changes
+        run: |
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git add dist/
+          git diff --staged --quiet || git commit -m "Update build artifacts [skip ci]"
+          git push
+
+  browserstack:
+    runs-on: ubuntu-latest
+    needs: [unit-tests, linting, build]
+    if: (github.event_name == 'push' && github.ref == 'refs/heads/main') || github.event_name == 'workflow_dispatch'
+
+    steps:
+      - name: "BrowserStack Env Setup"
+        uses: "browserstack/github-actions/setup-env@master"
+        with:
+          username: ${{ secrets.BROWSERSTACK_USERNAME }}
+          access-key: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
+
+      - name: "Start BrowserStackLocal Tunnel"
+        uses: "browserstack/github-actions/setup-local@master"
+        with:
+          local-testing: "start"
+          local-logging-level: "all-logs"
+          local-identifier: "random"
+
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ env.NODE_VERSION }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+
+      - name: Run npm ci
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Run BrowserStack tests
+        run: node ./test/index.js
+        env:
+          CI: true
+          NODE_ENV: test
+          DEBUG: false
+          LOCATION: ${{ secrets.LOCATION }}
+          BROWSERSTACK_USERNAME: ${{ secrets.BROWSERSTACK_USERNAME }}
+          BROWSERSTACK_ACCESS_KEY: ${{ secrets.BROWSERSTACK_ACCESS_KEY }}
+
+      - name: "Stop BrowserStackLocal"
+        uses: "browserstack/github-actions/setup-local@master"
+        with:
+          local-testing: "stop"

.nvmrc

@@ -1 +1 @@
-16.16
+22.16

.prettierrc.json

@@ -0,0 +1,3 @@
+{
+  "trailingComma": "es5"
+}

AGENTS.md

@@ -0,0 +1,21 @@
+# Agent Instructions
+
+This repository contains the public scripts for Simple Analytics. When making changes keep the following points in mind.
+
+## Development
+
+- Use **Node.js 22.16** (see `.nvmrc`).
+- Run `npm run build` to compile the scripts. This generates the files in `dist/` which should be committed.
+- Format code with Prettier before committing. You can run `npx prettier -w .` or validate with `npm run prettier`.
+
+## Testing
+
+- Execute `npm run test:unit` to run the unit tests
+- When adding a new feature or fixing a bug, please add a test.
+- For every change, run `npm run build` to ensure the test uses the latest compiled version.
+- Ignore most files in the `dist/` directory when checking for diffs, just check `dist/latest/latest.dev.js` and `dist/latest/auto-events.js` (whichever is relevant).
+- Only tests in `test/unit/` are relevant for the AI and agents (it can run without internet access).
+
+## References
+
+Most work happens in `src/` with `compile.js` creating the distributable versions. Read `README.md` for more details about contributing and running scripts locally.

README.md

@@ -28,6 +28,10 @@ Just run `npm run watch` and every file will be validated and compiled on save.
 
 The most important file of the repository is [`/src/default.js`](src/default.js)
 
+## Unit tests
+
+Run `npm run test:unit` to execute a small set of tests without BrowserStack.
+
 ## Device testing is sponsored by BrowserStack
 
 We run our public script with more than [50 browsers on many different (real) devices](https://github.com/simpleanalytics/scripts/blob/main/test/helpers/get-browsers.js). We support Internet Explorer 9 (not sure who is still using that) and up. Including many mobile browsers and less common devices. We get amazing sponsorship from [BrowserStack](https://www.browserstack.com/). Thanks, BrowserStack!

compile.js

@@ -3,12 +3,13 @@ const UglifyJS = require("uglify-js");
 const fs = require("fs");
 const esprima = require("esprima");
 const path = require("path");
+const acorn = require("acorn");
 
 const GREEN = "\x1b[32m%s\x1b[0m";
 const YELLOW = "\x1b[33m%s\x1b[0m";
 const RED = "\x1b[31m%s\x1b[0m";
 
-const VERSION = 11;
+const VERSION = 12;
 
 Handlebars.registerHelper("or", function (param1, param2) {
   return param1 || param2;
@@ -320,7 +321,7 @@ for (const file of files) {
     .digest("hex")
     .slice(0, 4);
 
-  const prepend = `/* Simple Analytics - Privacy friendly analytics (docs.simpleanalytics.com/script; ${date}; ${hash}${
+  const prepend = `/* Simple Analytics - Privacy-first analytics (docs.simpleanalytics.com/script; ${date}; ${hash}${
     variables.sri ? `; SRI-version` : ""
   }${variables.version ? `; v${variables.version}` : ""}) */\n`;
 
@@ -358,6 +359,31 @@ for (const file of files) {
   for (const warning of warnings || [])
     console.warn(YELLOW, `[${name}] ${warning}`);
 
+  try {
+    acorn.parse(rawCode, { ecmaVersion: 5 });
+  } catch (error) {
+    // console.log("acorn", error);
+
+    // error object:
+    // pos: 147,
+    // loc: Position { line: 12, column: 0 },
+    // raisedAt: 148
+
+    // Find part of the code that is causing the error
+    const lines = rawCode.split("\n");
+    const line = error.loc.line;
+    const column = error.loc.column;
+    const start = Math.max(0, line - 3);
+    const end = Math.min(lines.length, line + 3);
+    const codeSnippet = lines.slice(start, end).join("\n");
+    const sentence = lines[error.loc.line - 1];
+
+    // console.log({ codeSnippet, line: lines[error.loc.line - 1] });
+
+    throw new Error(
+      `${error.message} at line ${sentence} position ${column}: ${codeSnippet}`
+    );
+  }
   const code = fillTemplate(codeTemplate, variables);
 
   const validate = template({