test(analytics): fix inner beforeEach + add missing captureException source test

Add jest.resetModules() in capture source attribution beforeEach (latent
flake risk). Add properties.source > system precedence test for captureException.

Author: PierreBrisorgueil

README.md

@@ -263,6 +263,30 @@ git merge devkit-node/master
 
 > Caution: resolve conflicts manually to preserve downstream customizations before pushing.
 
+## :bar_chart: Analytics (PostHog)
+
+The devkit ships an `analyticsService` backed by `posthog-node`. Enable via `config.analytics.posthog.enabled = true` + a valid `key`.
+
+### Source attribution convention
+
+Every `analytics.capture()` and `analytics.captureException()` event gets a `source` property. The lookup order is:
+
+1. Explicit `source` param: `analytics.capture({ ..., source: 'cron' })`
+2. `properties.source` legacy/inline form
+3. `req.posthogContext.source` (auto-set by `posthogContextMiddleware`)
+4. `'system'` default
+
+Canonical sources used downstream:
+
+| Source | Meaning |
+|---|---|
+| `web` | Request from browser (UA not matched as CLI) |
+| `cli` | Request from `@trawlme/cli/<version>` (UA-parsed) |
+| `stripe-webhook` | Stripe POST `/api/billing/webhook` |
+| `worker-callback` | worker-puppeteer scrap completion callback |
+| `cron` | Scheduled background job |
+| `system` | Server-side fallback (no req, no caller override) |
+
 ## :pencil2: Contribute
 
 Open issues and pull requests on [GitHub](https://github.com/pierreb-devkit/Node).

lib/services/tests/analytics.capture.unit.tests.js

@@ -286,6 +286,10 @@ describe('Analytics capture() and enabled-flag:', () => {
   describe('source attribution:', () => {
     let AnalyticsService;
     beforeEach(async () => {
+      jest.resetModules();
+      jest.unstable_mockModule('posthog-node', () => ({
+        PostHog: jest.fn().mockImplementation(() => mockPostHogInstance),
+      }));
       jest.unstable_mockModule('../../../config/index.js', () => ({
         default: { analytics: { posthog: { enabled: true, key: 'phc_test', host: 'https://eu.i.posthog.com', appTag: 'trawl' } } },
       }));

lib/services/tests/analytics.captureException.unit.tests.js

@@ -57,7 +57,16 @@ describe('Analytics captureException():', () => {
     }));
   });
 
-  test('ctx.properties.source wins over default but explicit ctx.source wins over ctx.properties.source', () => {
+  test('ctx.properties.source wins over system default', () => {
+    AnalyticsService.captureException(new Error('boom'), {
+      properties: { source: 'stripe-webhook' },
+    });
+    expect(mockPostHogInstance.capture).toHaveBeenCalledWith(expect.objectContaining({
+      properties: expect.objectContaining({ source: 'stripe-webhook' }),
+    }));
+  });
+
+  test('explicit ctx.source wins over ctx.properties.source', () => {
     AnalyticsService.captureException(new Error('boom'), {
       source: 'cron',
       properties: { source: 'web' },