Logger abstraction added

.github/workflows/main.yml

@@ -22,13 +22,15 @@ jobs:
       CI_JOB_NUMBER: 2
     steps:
       - uses: actions/checkout@v1
+        with:
+          fetch-depth: 0
       - name: Use Node.js from .nvmrc
         uses: actions/setup-node@v6
         with:
           node-version-file: '.nvmrc'
       - run: corepack enable
       - run: yarn install
-      - run: yarn workspace @hawk.so/javascript test
+      - run: yarn test:modified origin/${{ github.event.pull_request.base.ref }}
 
   build:
     runs-on: ubuntu-latest

package.json

@@ -14,6 +14,8 @@
     "dev": "yarn workspace @hawk.so/javascript dev",
     "build:all": "yarn workspaces foreach -Apt run build",
     "build:modified": "yarn workspaces foreach --since=\"$@\" -Rpt run build",
+    "test:all": "yarn workspaces foreach -Apt run test",
+    "test:modified": "yarn workspaces foreach --since=\"$@\" -Rpt run test",
     "stats": "yarn workspace @hawk.so/javascript stats",
     "lint": "eslint -c ./.eslintrc.cjs packages/*/src --ext .ts,.js --fix",
     "lint-test": "eslint -c ./.eslintrc.cjs packages/*/src --ext .ts,.js"

packages/core/package.json

@@ -17,7 +17,10 @@
     }
   },
   "scripts": {
-    "build": "vite build"
+    "build": "vite build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint --fix \"src/**/*.{js,ts}\""
   },
   "repository": {
     "type": "git",
@@ -34,7 +37,9 @@
   },
   "homepage": "https://github.com/codex-team/hawk.javascript#readme",
   "devDependencies": {
+    "@vitest/coverage-v8": "^4.0.18",
     "vite": "^7.3.1",
-    "vite-plugin-dts": "^4.2.4"
+    "vite-plugin-dts": "^4.2.4",
+    "vitest": "^4.0.18"
   }
 }

packages/core/src/index.ts

@@ -0,0 +1,5 @@
+export type { HawkStorage } from './storages/hawk-storage';
+export type { UserManager } from './users/user-manager';
+export { HawkStorageUserManager } from './users/hawk-storage-user-manager';
+export type { Logger, LogType } from './logger/logger';
+export { setLogger, log } from './logger/logger';

packages/core/src/logger/logger.ts

@@ -0,0 +1,54 @@
+/**
+ * Log level type for categorizing log messages.
+ *
+ * Includes standard console methods supported in both browser and Node.js:
+ * - Standard levels: `log`, `warn`, `error`, `info`
+ * - Performance timing: `time`, `timeEnd`
+ */
+export type LogType = 'log' | 'warn' | 'error' | 'info' | 'time' | 'timeEnd';
+
+/**
+ * Logger function interface for environment-specific logging implementations.
+ *
+ * Implementations should handle message formatting, output styling,
+ * and platform-specific logging mechanisms (e.g., console, file, network).
+ *
+ * @param msg - The message to log.
+ * @param type - Log level/severity (default: 'log').
+ * @param args - Additional data to include with the log message.
+ */
+export interface Logger {
+  (msg: string, type?: LogType, args?: unknown): void;
+}
+
+/**
+ * Global logger instance, set by environment-specific packages.
+ */
+let loggerInstance: Logger | null = null;
+
+/**
+ * Registers the environment-specific logger implementation.
+ *
+ * This should be called once during application initialization
+ * by the environment-specific package.
+ *
+ * @param logger - Logger implementation to use globally.
+ */
+export function setLogger(logger: Logger): void {
+  loggerInstance = logger;
+}
+
+/**
+ * Logs a message using the registered logger implementation.
+ *
+ * If no logger has been registered via {@link setLogger}, this is a no-op.
+ *
+ * @param msg - Message to log.
+ * @param type - Log level (default: 'log').
+ * @param args - Additional arguments to log.
+ */
+export function log(msg: string, type?: LogType, args?: unknown): void {
+  if (loggerInstance) {
+    loggerInstance(msg, type, args);
+  }
+}

packages/core/src/storages/hawk-storage.ts

@@ -0,0 +1,26 @@
+/**
+ * Abstract key–value storage contract used by Hawk internals to persist data across sessions.
+ */
+export interface HawkStorage {
+  /**
+   * Returns the value associated with the given key, or `null` if none exists.
+   *
+   * @param key - Storage key to look up.
+   */
+  getItem(key: string): string | null
+
+  /**
+   * Persists a value under the given key.
+   *
+   * @param key - Storage key.
+   * @param value - Value to store.
+   */
+  setItem(key: string, value: string): void
+
+  /**
+   * Removes the entry for the given key.
+   *
+   * @param key - Storage key to remove.
+   */
+  removeItem(key: string): void
+}

packages/core/src/users/hawk-storage-user-manager.ts

@@ -0,0 +1,49 @@
+import type { AffectedUser } from '@hawk.so/types';
+import type { HawkStorage } from '../storages/hawk-storage';
+import type { UserManager } from './user-manager';
+
+/**
+ * Storage key used to persist the user identifier.
+ */
+const HAWK_USER_STORAGE_KEY = 'hawk-user-id';
+
+/**
+ * {@link UserManager} implementation that persists the affected user
+ * via an injected {@link HawkStorage} backend.
+ */
+export class HawkStorageUserManager implements UserManager {
+  /**
+   * Underlying storage used to read and write the user identifier.
+   */
+  private readonly storage: HawkStorage;
+
+  /**
+   * @param storage - Storage backend to use for persistence.
+   */
+  constructor(storage: HawkStorage) {
+    this.storage = storage;
+  }
+
+  /** @inheritDoc */
+  public getUser(): AffectedUser | null {
+    const storedId = this.storage.getItem(HAWK_USER_STORAGE_KEY);
+
+    if (storedId) {
+      return {
+        id: storedId,
+      };
+    }
+
+    return null;
+  }
+
+  /** @inheritDoc */
+  public setUser(user: AffectedUser): void {
+    this.storage.setItem(HAWK_USER_STORAGE_KEY, user.id);
+  }
+
+  /** @inheritDoc */
+  public clear(): void {
+    this.storage.removeItem(HAWK_USER_STORAGE_KEY);
+  }
+}

packages/core/src/users/user-manager.ts

@@ -0,0 +1,26 @@
+import type { AffectedUser } from '@hawk.so/types';
+
+/**
+ * Contract for user identity managers.
+ *
+ * Implementations are responsible for persisting and retrieving the
+ * {@link AffectedUser} that is attached to every error report sent by the catcher.
+ */
+export interface UserManager {
+  /**
+   * Returns the current affected user, or `null` if none has been set.
+   */
+  getUser(): AffectedUser | null
+
+  /**
+   * Replaces the stored user with the provided one.
+   *
+   * @param user - The affected user to persist.
+   */
+  setUser(user: AffectedUser): void
+
+  /**
+   * Removes any previously stored user data.
+   */
+  clear(): void
+}

packages/core/tests/users/hawk-storage-user-manager.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { HawkStorageUserManager } from '../../src';
+import type { HawkStorage } from '../../src';
+
+describe('StorageUserManager', () => {
+  let storage: HawkStorage;
+  let manager: HawkStorageUserManager;
+
+  beforeEach(() => {
+    storage = {
+      getItem: vi.fn().mockReturnValue(null),
+      setItem: vi.fn(),
+      removeItem: vi.fn(),
+    };
+    manager = new HawkStorageUserManager(storage);
+  });
+
+  it('should return null when storage is empty', () => {
+    expect(manager.getUser()).toBeNull();
+    expect(storage.getItem).toHaveBeenCalledWith('hawk-user-id');
+  });
+
+  it('should return user when ID exists in storage', () => {
+    vi.mocked(storage.getItem).mockReturnValue('test-user-123');
+
+    expect(manager.getUser()).toEqual({id: 'test-user-123'});
+    expect(storage.getItem).toHaveBeenCalledWith('hawk-user-id');
+  });
+
+  it('should persist user ID via setUser()', () => {
+    manager.setUser({id: 'user-abc'});
+
+    expect(storage.setItem).toHaveBeenCalledWith('hawk-user-id', 'user-abc');
+  });
+
+  it('should remove user ID via clear()', () => {
+    manager.clear();
+
+    expect(storage.removeItem).toHaveBeenCalledWith('hawk-user-id');
+  });
+});

packages/core/tsconfig.test.json

@@ -0,0 +1,13 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": null,
+    "declaration": false,
+    "types": ["vitest/globals"]
+  },
+  "include": [
+    "src/**/*",
+    "tests/**/*",
+    "vitest.config.ts"
+  ]
+}

packages/core/vitest.config.ts

@@ -0,0 +1,15 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+    include: ['tests/**/*.test.ts'],
+    typecheck: {
+      tsconfig: './tsconfig.test.json',
+    },
+    coverage: {
+      provider: 'v8',
+      include: ['src/**/*.ts'],
+    },
+  },
+});

packages/javascript/package.json

@@ -21,6 +21,7 @@
     "build": "vite build",
     "stats": "size-limit > stats.txt",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "eslint --fix \"src/**/*.{js,ts}\""
   },
@@ -39,10 +40,12 @@
   },
   "homepage": "https://github.com/codex-team/hawk.javascript#readme",
   "dependencies": {
+    "@hawk.so/core": "workspace:^",
     "error-stack-parser": "^2.1.4"
   },
   "devDependencies": {
     "@hawk.so/types": "0.5.8",
+    "@vitest/coverage-v8": "^4.0.18",
     "jsdom": "^28.0.0",
     "vite": "^7.3.1",
     "vite-plugin-dts": "^4.2.4",

packages/javascript/src/addons/breadcrumbs.ts

@@ -4,7 +4,7 @@
 import type { Breadcrumb, BreadcrumbLevel, BreadcrumbType, Json, JsonNode } from '@hawk.so/types';
 import Sanitizer from '../modules/sanitizer';
 import { buildElementSelector } from '../utils/selector';
-import log from '../utils/log';
+import { log } from '@hawk.so/core';
 import { isValidBreadcrumb } from '../utils/validation';
 
 /**