Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .agents/hooks/post-edit-format.sh
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ cd "$root" || exit 0
case "$rel" in
src/*.ts|src/*.js)
# eslint-plugin-prettier applies prettier as part of --fix.
npx --no-install eslint --fix --config .eslintrc.cjs "$rel" >&2 || exit 2 ;;
npx --no-install eslint --fix "$rel" >&2 || exit 2 ;;
test/*.ts|test/*.js)
npx --no-install prettier --write "$rel" >/dev/null ;;
esac
Expand Down
3 changes: 3 additions & 0 deletions .agents/skills/sdk-deps/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,3 +17,6 @@ description: Use when upgrading, adding or auditing PubNub JavaScript SDK npm de
commits rebuilt artifacts ([sdk-release](../sdk-release/SKILL.md)).
6. Triaging `npm outdated` or `npm audit` output is mechanical; give it to a light-model subagent. Report the
versions changed and the risk.
7. Dependency vulnerability scanning is done by Snyk, outside this repo; there is no in-repo audit gate.
8. `overrides` pins `@types/eslint-scope` to its 9.x stub. webpack's 3.x typings conflict with ESLint 10's own types and
break `typecheck` and `build:node`. Drop the override once webpack stops depending on them.
3 changes: 3 additions & 0 deletions .agents/skills/sdk-release/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,9 @@ description: Use when finalizing a PubNub JavaScript SDK PR for merge or release
Review the source diff first, then sanity-check `git diff --stat lib dist` for unexpected files.
3. Run `.scripts/agent-test.sh release`. It checks that `package.json`, `getVersion()` and the README CDN links agree,
and type-checks the aggregated declarations.
Then run `npm run pkg:check` (publint + attw on the packed package) and, once `lib/` is staged, `npm run api:check`
(CI fails when `lib/types/index.d.ts` differs from a fresh build). Any `lib/types` diff is a public API change:
call it out in the PR body. attw ignores only `named-exports` (an existing ESM named-import gap in the CJS build).
4. Write the PR title and body in the format from `.github/pull_request_template.md`: `type(scope): subject`, a body,
then a footer. The bot builds the changelog from them, so state the user-visible change precisely. Use `Closes #n`
for issues addressed and `BREAKING CHANGES:` for any breaking change.
Expand Down
5 changes: 4 additions & 1 deletion .agents/skills/sdk-test/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,10 @@ light-model subagent that returns the wrapper output verbatim.

- `test/unit/event_engine*.test.ts` drive full clients over nock-mocked HTTP.
- `npm test` includes live browser traffic; it is not an offline smoke test.
- `ci:*` scripts clean, build, lint and test everything. Use them only for full validation, never concurrently.
- `ci:*` scripts clean, build, lint (`lint` + `lint:arch`) and test everything. Use them only for full validation, never
concurrently. They delete `lib/` and `dist/`, so run `npm run pkg:check` before them, not after.
- Static checks need no keys or network. A new lint error in code you touched is a failure;
don't add it to `eslint-suppressions.json`.
- Run one suite at a time. Suites share ports, fake timers, mocks and build directories.

## Secrets
Expand Down
39 changes: 39 additions & 0 deletions .dependency-cruiser.cjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,39 @@
// Architecture rules for src/ (`npm run lint:arch`). Cycles count only through imports that survive compilation;
// type-only cycles do not affect CommonJS load order.
/** @type {import('dependency-cruiser').IConfiguration} */
module.exports = {
forbidden: [
{
name: 'shared-no-node-builtins',
comment: 'src/core, src/entities and src/event-engine run on every platform; Node built-ins belong in src/node.',
severity: 'error',
from: { path: '^src/(core|entities|event-engine)/' },
to: { dependencyTypes: ['core'] },
},
{
name: 'shared-no-platform-code',
comment: 'Shared code must not import a platform entry point or transport; inject them from the entry point.',
severity: 'error',
from: { path: '^src/(core|entities|event-engine)/' },
to: {
path: [
'^src/(node|web|react_native|nativescript|titanium)/',
'^src/transport/(node|web|react-native|titanium)-transport\\.ts$',
'^src/transport/subscription-worker/',
],
},
},
{
name: 'no-circular',
comment: 'Runtime import cycles break CommonJS load order (undefined imports at module evaluation).',
severity: 'error',
from: {},
to: { circular: true, viaOnly: { dependencyTypesNot: ['type-only', 'pre-compilation-only'] } },
},
],
options: {
doNotFollow: { path: 'node_modules' },
tsPreCompilationDeps: 'specify',
tsConfig: { fileName: 'tsconfig.json' },
},
};
9 changes: 0 additions & 9 deletions .eslintignore

This file was deleted.

24 changes: 0 additions & 24 deletions .eslintrc.cjs

This file was deleted.

13 changes: 13 additions & 0 deletions .github/codeql/codeql-config.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
name: PubNub JavaScript SDK CodeQL config

queries:
- uses: security-extended

# Analyze the SDK sources only: build output is generated from src/, and tests and snippets do not ship.
paths:
- src
paths-ignore:
- lib
- dist
- test
- docs-snippets
37 changes: 37 additions & 0 deletions .github/workflows/codeql.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
name: CodeQL

# Static security analysis (data flow across files). Results appear in the Security tab and as PR annotations.
on:
pull_request:
push:
branches: [master]
schedule:
- cron: '17 4 * * 1'
workflow_dispatch:
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true
permissions:
contents: read

jobs:
analyze:
name: Analyze (javascript-typescript)
runs-on:
group: organization/Default
permissions:
contents: read
security-events: write
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Initialize CodeQL
uses: github/codeql-action/init@v4
with:
languages: javascript-typescript
build-mode: none
config-file: ./.github/codeql/codeql-config.yml
- name: Perform CodeQL analysis
uses: github/codeql-action/analyze@v4
with:
category: '/language:javascript-typescript'
13 changes: 10 additions & 3 deletions .github/workflows/run-tests.yml
Original file line number Diff line number Diff line change
Expand Up @@ -42,10 +42,17 @@ jobs:
node-version: ${{ matrix.node }}
cache: 'npm'
cache-dependency-path: '**/package-lock.json'
- name: Install dependencies
run: npm install
# Runs on the committed lib/ and dist/ (what gets published), before ci:* cleans them.
- name: Package entry points and types resolution
if: matrix.node == '22' && matrix.env == 'ci:node'
run: npm run pkg:check
- name: Build and run tests for NodeJS ${{ matrix.node }}
run: |
npm install
npm run ${{ matrix.env }}
run: npm run ${{ matrix.env }}
- name: Committed public API types match the build
if: matrix.node == '22' && matrix.env == 'ci:node'
run: npm run api:check
all-tests:
name: Tests
runs-on:
Expand Down
6 changes: 4 additions & 2 deletions .npmignore
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,10 @@ coverage/
*.iml
.travis
test/*
.eslintignore
.eslintrc.cjs
eslint.config.mjs
eslint-suppressions.json
.dependency-cruiser.cjs
knip.json
.prettierrc
.prettierignore
.prettierignore
Expand Down
2 changes: 1 addition & 1 deletion .pre-commit-config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ repos:
hooks:
- id: eslint
name: eslint --fix (includes prettier) on src
entry: npx --no-install eslint --fix --config .eslintrc.cjs
entry: npx --no-install eslint --fix
language: system
files: ^src/.*\.ts$
- id: prettier
Expand Down
7 changes: 4 additions & 3 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,15 @@ types and realtime behavior, so small behavior changes can break them.
- Install: `npm install`, as `run-tests.yml` does. Use Node 22 or 24, the CI matrix. Mocha fails at startup on Node 26; that's environmental, not an SDK bug.
- Build (no keys needed): `npm run build:node` (tsc → `lib/` + aggregated `lib/types/index.d.ts`) · `npm run build:web` (rollup → `dist/web/`). Run `build:node` before the `release` or `node` suite when `src/` changed since `lib/types/index.d.ts` was built, or that file is missing.
- Typecheck: `npm run typecheck`. It covers Node sources only; browser/worker sources are type-checked by `build:web`.
- Lint: `npm run lint` (src/ only)
- Lint: `npm run lint` (src/ only; type-aware ESLint, `eslint.config.mjs`). Existing violations are baselined in `eslint-suppressions.json`, so new code must pass every rule. After fixing baselined ones, run `npx eslint src --prune-suppressions`; never use `--suppress-all` to hide new violations.
- Static analysis: `npm run lint:arch` (dependency-cruiser: shared code imports no Node built-ins or platform code; no runtime import cycles) · `npm run pkg:check` (publint + attw on the committed `lib/` and `dist/`; `ci:*` deletes them, so run it first) · `npm run api:check` (after `build:node`; fails until the rebuilt `lib/types/index.d.ts` is committed) · `npm run knip` (report-only, not in CI; `buffer` is the React Native polyfill, not unused). CodeQL runs in `.github/workflows/codeql.yml`.
- Test, one file: `.scripts/agent-test.sh test/unit/publish/publish.test.ts [--grep '<re>']`
- Keyless tests: `.scripts/agent-test.sh unit` runs with no env keys; nock mocks all HTTP. `integration` also passes without keys, except `test/integration/endpoints/data_sync/` (35 tests), which needs the `DS_*` keys.
- Other suites: `release` and `node` need `build:node` when `src/` changed since `lib/types/index.d.ts` was built, or that file is missing. `node` also needs the `DS_*` keys. Browser, live-key and contract suites → sdk-test skill, ask first.
- Wrap any noisy command: `.scripts/agent-test.sh npm run build:node` prints one line on pass and only the failures on fail.
- Don't call mocha/karma/cucumber directly: mocha without `--no-config` silently runs the whole suite.
- Inspect logs with `grep`/`tail`; never read a full log.
- Each edit to `src/` runs `eslint --fix` (includes prettier) and each edit to `test/` runs prettier, via the PostToolUse hook `.agents/hooks/post-edit-format.sh`. Nothing runs the secret scan.
- `.agents/hooks/post-edit-format.sh` runs `eslint --fix` (includes prettier) on `src/` and prettier on `test/`, but `.claude/settings.json` doesn't register it as a PostToolUse hook yet, so edits aren't auto-formatted: run `npm run lint`. The gitleaks secret scan runs in `.pre-commit-config.yaml` and, on PRs, `.github/workflows/pre-commit.yml`.

## Layout
- `src/core/`: shared public API. `pubnub-common.ts` (PubNubCore), `endpoints/` (one `AbstractRequest` subclass per REST call), `components/`, `types/api/`
Expand Down Expand Up @@ -48,7 +49,7 @@ types and realtime behavior, so small behavior changes can break them.
- **Never** (each is enforced by a hook or CI):
- hand-edit `lib/`, `dist/`, `package-lock.json`, `CHANGELOG.md`, `.pubnub.yml`, `.env*` or key files → `.agents/hooks/protect-files.sh`
- force-push or use `--no-verify` → `.agents/hooks/git-policy.sh`
- commit secrets → not enforced yet; no secret-scan hook or CI step runs (gitleaks was in the removed pre-commit config)
- commit secrets → gitleaks in `.pre-commit-config.yaml` and `.github/workflows/pre-commit.yml` (PRs)
- finish with a failing typecheck → `.agents/hooks/quick-check.sh`

## More context
Expand Down
Loading
Loading