diff --git a/.github/scripts/public_api.mjs b/.github/scripts/public_api.mjs new file mode 100644 index 0000000..08424b6 --- /dev/null +++ b/.github/scripts/public_api.mjs @@ -0,0 +1,70 @@ +// Prints the public surface of a JavaScript SDK module as sorted " " lines, so two versions can be compared. +// Usage: node public_api.mjs = [= ...] +// Each expression is evaluated with `sdk` bound to the module's export and is listed under its name, for example +// Countly=sdk or Instance='new sdk.CountlyClass({ app_key: "key", url: "https://example.invalid" })'. +import { writeSync } from "node:fs"; +import { pathToFileURL } from "node:url"; +import { resolve } from "node:path"; + +const MAX_DEPTH = 4; + +/** + * Returns the kind printed for a value: its typeof, with null and arrays told apart. + * @param {*} value the value to describe + * @returns {string} "null", "array" or the typeof of the value + */ +function kindOf(value) { + if (value === null) { + return "null"; + } + return Array.isArray(value) ? "array" : typeof value; +} + +/** + * Adds a line for the value at path and, for objects and functions, for each public member below it. + * Names that start with an underscore are private by convention and skipped, and array elements are data. + * @param {*} value the value to describe + * @param {string} path the dotted path that reaches the value + * @param {string[]} lines the lines collected so far + * @param {WeakSet} seen the objects already described, so cycles end + * @param {number} depth how many members deep the value is + */ +function describe(value, path, lines, seen, depth) { + const kind = kindOf(value); + lines.push(`${path} ${kind}`); + if ((kind !== "object" && kind !== "function") || depth >= MAX_DEPTH || seen.has(value)) { + return; + } + seen.add(value); + for (const key of Object.keys(value)) { + if (!key.startsWith("_")) { + describe(value[key], `${path}.${key}`, lines, seen, depth + 1); + } + } + if (kind === "function" && value.prototype) { + for (const key of Object.getOwnPropertyNames(value.prototype)) { + if (key !== "constructor" && !key.startsWith("_")) { + lines.push(`${path}.prototype.${key} ${kindOf(value.prototype[key])}`); + } + } + } +} + +const [modulePath, ...roots] = process.argv.slice(2); +if (!modulePath || roots.length === 0) { + console.error("Usage: node public_api.mjs = [...]"); + process.exit(2); +} +const loaded = await import(pathToFileURL(resolve(modulePath)).href); +const sdk = loaded.default ?? loaded; +const lines = []; +for (const root of roots) { + const separator = root.indexOf("="); + const name = root.slice(0, separator); + const value = new Function("sdk", `return (${root.slice(separator + 1)});`)(sdk); + describe(value, name, lines, new WeakSet(), 0); +} +// A synchronous write, because the exit below would cut off an asynchronous write to a pipe. +writeSync(1, [...new Set(lines)].sort().join("\n") + "\n"); +// The SDK may have started timers (an instance's heartbeat, for example), so the process ends here. +process.exit(0); diff --git a/.github/scripts/public_api_record.sh b/.github/scripts/public_api_record.sh new file mode 100644 index 0000000..88f5c95 --- /dev/null +++ b/.github/scripts/public_api_record.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +# Compares the public API this run extracted with the record committed in the repository. On a difference it lists the +# changed lines in the job summary, copies the extracted API to $RUNNER_TEMP/public-api-record/ under the record's path, +# for the workflow to upload, and fails: a deliberate change is committed together with a changelog line. +# $@ pairs "=" +set -euo pipefail +out="$RUNNER_TEMP/public-api-record" +status=0 +current="$RUNNER_TEMP/public-api-current.txt" +recorded="$RUNNER_TEMP/public-api-recorded.txt" +for pair in "$@"; do + extracted=${pair%%=*} + record=${pair#*=} + # Line endings do not count: .NET writes CRLF on Windows, and a Windows checkout can give the record CRLF too. + tr -d '\r' < "$extracted" > "$current" + if [ -f "$record" ] && tr -d '\r' < "$record" | cmp -s - "$current"; then + echo "The public API is the one $record records." + continue + fi + status=1 + mkdir -p "$out/$(dirname "$record")" + cp "$current" "$out/$record" + { + printf '### The public API differs from %s\n\n' "$record" + printf "Commit \`%s\` from the \`public-api-record\` artifact of this run, with a changelog line for the change.\n\n" "$record" + if [ -f "$record" ]; then + printf '```diff\n' + tr -d '\r' < "$record" > "$recorded" + diff -u "$recorded" "$current" | tail -n +3 | head -n 300 || true + printf '```\n\n' + else + printf 'There is no record yet.\n\n' + fi + } >> "$GITHUB_STEP_SUMMARY" + echo "::error title=Public API record::The public API differs from $record. Commit the file from this run's public-api-record artifact and add a changelog line." +done +exit "$status" diff --git a/.github/scripts/public_api_report.sh b/.github/scripts/public_api_report.sh new file mode 100644 index 0000000..e9b930c --- /dev/null +++ b/.github/scripts/public_api_report.sh @@ -0,0 +1,46 @@ +#!/usr/bin/env bash +# Writes the report of a pull request's public API changes to the job summary, and to the step output "report", which +# the workflow's comment job posts on the pull request. The comment lists at most 200 lines per section. +# $1 a file with one removed or changed declaration per line +# $2 a file with one declaration per line that the pull request adds to the public API +set -euo pipefail +breaking=$1 +added=$2 +marker='' + +# Prints a section titled $1 and explained by $2 with the lines of file $3, at most $4 of them when $4 is not 0. +section() { + local count + count=$(grep -c . "$3" || true) + [ "$count" -gt 0 ] || return 0 + printf '**%s: %s.** %s\n\n```\n' "$1" "$count" "$2" + if [ "$4" -gt 0 ]; then + head -n "$4" "$3" + else + cat "$3" + fi + printf '```\n' + if [ "$4" -gt 0 ] && [ "$count" -gt "$4" ]; then + printf '\n%s more in the job summary.\n' "$((count - $4))" + fi + printf '\n' +} + +# Prints the whole report, with at most $1 lines per section when $1 is not 0. +report() { + printf '%s\n### Public API changes\n\n' "$marker" + if ! grep -q . "$breaking" && ! grep -q . "$added"; then + printf 'No public API change.\n' + return + fi + section 'Removed or changed' 'Each needs a CHANGELOG entry that marks it as a breaking change.' "$breaking" "$1" + section 'Added' 'Check that each one is meant to be public.' "$added" "$1" +} + +report 0 >> "$GITHUB_STEP_SUMMARY" +delimiter="EOF_$(od -An -N8 -tx1 /dev/urandom | tr -d ' \n')" +{ + echo "report<<$delimiter" + report 200 + echo "$delimiter" +} >> "$GITHUB_OUTPUT" diff --git a/.github/workflows/api-changelog.yml b/.github/workflows/api-changelog.yml new file mode 100644 index 0000000..95385d3 --- /dev/null +++ b/.github/workflows/api-changelog.yml @@ -0,0 +1,52 @@ +name: Public API changelog + +# A pull request that changes or removes a record of the public API must also change the CHANGELOG.md that API_FILES +# pairs it with, so that the release notes tell integrators about every such change. A record the pull request adds needs +# no line. A path ending in "/" stands for every file under it. The API check keeps each record in step with the SDK. +on: + pull_request: + branches: [master, staging] + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +permissions: + pull-requests: read # to list the files the pull request changes + +jobs: + changelog: + name: A public API change comes with a CHANGELOG line + runs-on: ubuntu-24.04 + steps: + - name: Check the files the pull request changes + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + PR: ${{ github.event.pull_request.number }} + API_FILES: api/countly-sdk-nodejs.api=CHANGELOG.md + run: | + changed=$(gh api "repos/$REPO/pulls/$PR/files" --paginate --jq '.[] | select(.status != "added") | .filename') + changes() { + case "$1" in + */) printf '%s\n' "$changed" | awk -v prefix="$1" 'index($0, prefix) == 1 { found = 1 } END { exit !found }' ;; + *) printf '%s\n' "$changed" | grep -qxF "$1" ;; + esac + } + recorded_changed=no + for pair in $API_FILES; do + record=${pair%%=*} + changelog=${pair#*=} + if changes "$record"; then + recorded_changed=yes + if ! changes "$changelog"; then + echo "::error::This pull request changes $record, which records the public API, but not $changelog. Add a line that tells integrators what changed." + exit 1 + fi + fi + done + if [ "$recorded_changed" = yes ]; then + echo "The recorded public API changes, and the CHANGELOG changes with it." + else + echo "This pull request changes no recorded public API." + fi diff --git a/.github/workflows/public_api.yml b/.github/workflows/public_api.yml new file mode 100644 index 0000000..12420ca --- /dev/null +++ b/.github/workflows/public_api.yml @@ -0,0 +1,101 @@ +name: Public API changes + +on: + pull_request: + +permissions: + contents: read + +concurrency: + group: ${{ github.workflow }}-${{ github.ref }} + cancel-in-progress: true + +jobs: + api: + name: Breaking changes + outputs: + report: ${{ steps.report.outputs.report }} + runs-on: ubuntu-24.04 + steps: + - name: Checkout SDK code + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + fetch-depth: 2 + persist-credentials: false + + - name: Set up Node.js + uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 24 + + # The first parent of the pull request's merge commit is the base branch it merges into. + - name: Compare the public API with the base branch + id: compare + run: | + git worktree add "$RUNNER_TEMP/base" HEAD^1 + roots=( + 'Countly=sdk' + 'Bulk=new sdk.Bulk({ app_key: "key", url: "https://example.invalid", persist_queue: false })' + 'BulkUser=new sdk.Bulk({ app_key: "key", url: "https://example.invalid", persist_queue: false }).add_user({ device_id: "id" })' + ) + node .github/scripts/public_api.mjs "$RUNNER_TEMP/base/lib/countly.js" "${roots[@]}" > "$RUNNER_TEMP/base.txt" + node .github/scripts/public_api.mjs lib/countly.js "${roots[@]}" > "$RUNNER_TEMP/head.txt" + LC_ALL=C comm -23 "$RUNNER_TEMP/base.txt" "$RUNNER_TEMP/head.txt" | sed 's/^/Removed or changed: /' > "$RUNNER_TEMP/breaking.txt" + LC_ALL=C comm -13 "$RUNNER_TEMP/base.txt" "$RUNNER_TEMP/head.txt" > "$RUNNER_TEMP/added.txt" + + - name: Report the public API changes + id: report + run: bash .github/scripts/public_api_report.sh "$RUNNER_TEMP/breaking.txt" "$RUNNER_TEMP/added.txt" + + - name: Require a CHANGELOG entry for breaking changes + run: | + if [ ! -s "$RUNNER_TEMP/breaking.txt" ]; then + exit 0 + fi + if git diff --quiet HEAD^1 HEAD -- CHANGELOG.md; then + echo "::error title=Breaking API change::This pull request breaks the public API without a CHANGELOG.md entry. The job summary lists each break." + exit 1 + fi + echo "::warning title=Breaking API change::This pull request breaks the public API. Check that CHANGELOG.md marks it as a breaking change." + + # The committed record keeps every change to the public API visible in the pull request's diff. + - name: Compare the public API with its record + id: record + if: ${{ !cancelled() && steps.compare.outcome == 'success' }} + run: > + bash .github/scripts/public_api_record.sh + "$RUNNER_TEMP/head.txt=api/countly-sdk-nodejs.api" + + - name: Upload the new record + if: ${{ !cancelled() && steps.record.outcome == 'failure' }} + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: public-api-record + path: ${{ runner.temp }}/public-api-record + + comment: + name: Comment the public API changes + needs: api + # A fork's or Dependabot's pull request only gets a read-only token, so its report stays in the job summary. + if: >- + always() && needs.api.outputs.report != '' && + github.event.pull_request.head.repo.full_name == github.repository && + github.event.pull_request.user.login != 'dependabot[bot]' + runs-on: ubuntu-24.04 + permissions: + pull-requests: write + steps: + - name: Post or update the comment + env: + GH_TOKEN: ${{ github.token }} + REPO: ${{ github.repository }} + PR: ${{ github.event.pull_request.number }} + REPORT: ${{ needs.api.outputs.report }} + run: | + id=$(gh api --paginate "repos/$REPO/issues/$PR/comments" --jq \ + '.[] | select(.user.login == "github-actions[bot]" and (.body | startswith(""))) | .id' | tail -n 1) + if [ -n "$id" ]; then + gh api --method PATCH "repos/$REPO/issues/comments/$id" -f "body=$REPORT" > /dev/null + elif ! grep -qx 'No public API change.' <<< "$REPORT"; then + gh api --method POST "repos/$REPO/issues/$PR/comments" -f "body=$REPORT" > /dev/null + fi diff --git a/api/countly-sdk-nodejs.api b/api/countly-sdk-nodejs.api new file mode 100644 index 0000000..cca35ef --- /dev/null +++ b/api/countly-sdk-nodejs.api @@ -0,0 +1,119 @@ +Bulk object +Bulk.add_bulk_request function +Bulk.add_event function +Bulk.add_request function +Bulk.add_user function +Bulk.conf object +Bulk.conf.app_key string +Bulk.conf.bulk_size number +Bulk.conf.debug boolean +Bulk.conf.fail_timeout number +Bulk.conf.force_post boolean +Bulk.conf.http_options null +Bulk.conf.interval number +Bulk.conf.maxBreadcrumbCount number +Bulk.conf.maxKeyLength number +Bulk.conf.maxSegmentationValues number +Bulk.conf.maxStackTraceLineLength number +Bulk.conf.maxStackTraceLinesPerThread number +Bulk.conf.maxValueSize number +Bulk.conf.max_events number +Bulk.conf.persist_queue boolean +Bulk.conf.request_timeout number +Bulk.conf.salt null +Bulk.conf.session_update number +Bulk.conf.storage_type string +Bulk.conf.url string +Bulk.queue_size function +Bulk.start function +Bulk.stop function +BulkUser object +BulkUser.add_consent function +BulkUser.add_event function +BulkUser.begin_session function +BulkUser.check_consent function +BulkUser.custom_increment function +BulkUser.custom_increment_by function +BulkUser.custom_max function +BulkUser.custom_min function +BulkUser.custom_multiply function +BulkUser.custom_pull function +BulkUser.custom_push function +BulkUser.custom_push_unique function +BulkUser.custom_save function +BulkUser.custom_set function +BulkUser.custom_set_once function +BulkUser.custom_unset function +BulkUser.group_features function +BulkUser.remove_consent function +BulkUser.remove_consent_internal function +BulkUser.report_conversion function +BulkUser.report_crash function +BulkUser.report_feedback function +BulkUser.report_trace function +BulkUser.report_view function +BulkUser.user_details function +Countly object +Countly.Bulk function +Countly.Bulk.StorageTypes object +Countly.DeviceIdType object +Countly.DeviceIdType.DEVELOPER_SUPPLIED number +Countly.DeviceIdType.SDK_GENERATED number +Countly.StorageTypes object +Countly.StorageTypes.FILE string +Countly.StorageTypes.MEMORY string +Countly.add_consent function +Countly.add_event function +Countly.add_log function +Countly.begin_session function +Countly.change_app_key function +Countly.change_id function +Countly.change_server_url function +Countly.check_any_consent function +Countly.check_consent function +Countly.end_event function +Countly.end_session function +Countly.features array +Countly.fetch_remote_config function +Countly.flush function +Countly.flush_queues function +Countly.get_device_id function +Countly.get_device_id_type function +Countly.get_remote_config function +Countly.group_features function +Countly.halt function +Countly.init function +Countly.log_error function +Countly.remove_consent function +Countly.remove_consent_internal function +Countly.remove_different_app_keys_from_queue function +Countly.replace_all_app_keys_in_queue_with_current_app_key function +Countly.report_app_start function +Countly.report_conversion function +Countly.report_feedback function +Countly.report_trace function +Countly.request function +Countly.session_duration function +Countly.setLoggingEnabled function +Countly.set_id function +Countly.set_location function +Countly.start_event function +Countly.start_time function +Countly.stop_time function +Countly.track_errors function +Countly.track_pageview function +Countly.track_view function +Countly.userData object +Countly.userData.increment function +Countly.userData.increment_by function +Countly.userData.max function +Countly.userData.min function +Countly.userData.multiply function +Countly.userData.pull function +Countly.userData.push function +Countly.userData.push_unique function +Countly.userData.save function +Countly.userData.set function +Countly.userData.set_once function +Countly.userData.unset function +Countly.user_details function