CLI-727 Telemetry foundation: timed() utility, CliAnalysisFindingDetected types, and findings path constant

[vnaskos-sonar]

What

Purely additive foundation that the subsequent CLI-728, CLI-730, CLI-731, and CLI-733 PRs depend on. No behaviour changes.

• src/lib/timed.ts — generic timed<T>(fn: () => Promise<T>) utility that wraps any async call and returns its result alongside the wall-clock duration in milliseconds. Used by all three analyzer call sites (sonar-secrets, SQAA, SCA) to measure scan duration without changing existing function signatures.
• src/lib/state.ts — two new types: AnalysisFindingEventPayload (the four new fields caller_command, analyzer, rule_key, scan_duration_ms plus all shared identity/connection fields from CliCommandExecuted) and StoredFindingEvent (metadata envelope + payload, mirrors StoredTelemetryEvent).
• src/lib/config-constants.ts — TELEMETRY_DIR and FINDINGS_NDJSON_PATH constants pointing to ~/.sonar/sonarqube-cli/telemetry/findings.ndjson, the append-only NDJSON sink introduced in CLI-728.

Tests

• timed() returns the correct value and a non-negative durationMs
• timed() propagates errors from the wrapped function unchanged
• durationMs reflects actual elapsed time (wraps a real 50 ms sleep and asserts the result lands within tolerance — catches implementations that always return 0)

Dependencies

None. Must land before CLI-728 (sink + flush), CLI-730 (secrets call sites), CLI-731 (SQAA call sites), and CLI-733 (SCA call sites).

[netlify]

✅ Deploy Preview for sonarqube-cli canceled.

Name	Link
🔨 Latest commit	a6e22e1
🔍 Latest deploy log	https://app.netlify.com/projects/sonarqube-cli/deploys/6a393c8b0a71a000073fe059

[hashicorp-vault-sonar-prod]

CLI-727

[gitar-bot]

💡 Quality: event_timestamp format undocumented for finding events

TelemetryEventMetadata.event_timestamp is documented as "Epoch milliseconds as a string" (state.ts:417-418), but the inlined metadata.event_timestamp in the new StoredFindingEvent (state.ts:484-490) has no doc comment specifying the same format. Since CliAnalysisFindingDetected events are sent to the same backend, downstream code in CLI-728 could write an ISO string instead of epoch-ms, causing a silent format divergence between the two event types that the backend may reject or misparse. Add a matching doc comment (and ideally factor out a shared metadata type or event_timestamp semantic) to lock the format in. Note also that StoredFindingEvent.metadata duplicates the shape of TelemetryEventMetadata rather than reusing it; this is acceptable because event_type is a different literal, but documenting the timestamp keeps the two in sync.

_{Was this helpful? React with 👍 / 👎}

[gitar-bot]

Code Review 👍 Approved with suggestions 0 resolved / 1 findings

Adds telemetry infrastructure including a timed utility, new finding types, and file path constants. Please document the event_timestamp format for finding events to ensure consistency.

💡 Quality: event_timestamp format undocumented for finding events

📄 src/lib/state.ts:417-418 📄 src/lib/state.ts:484-490

TelemetryEventMetadata.event_timestamp is documented as "Epoch milliseconds as a string" (state.ts:417-418), but the inlined metadata.event_timestamp in the new StoredFindingEvent (state.ts:484-490) has no doc comment specifying the same format. Since CliAnalysisFindingDetected events are sent to the same backend, downstream code in CLI-728 could write an ISO string instead of epoch-ms, causing a silent format divergence between the two event types that the backend may reject or misparse. Add a matching doc comment (and ideally factor out a shared metadata type or event_timestamp semantic) to lock the format in. Note also that StoredFindingEvent.metadata duplicates the shape of TelemetryEventMetadata rather than reusing it; this is acceptable because event_type is a different literal, but documenting the timestamp keeps the two in sync.

🤖 Prompt for agents

Code Review: Adds telemetry infrastructure including a timed utility, new finding types, and file path constants. Please document the event_timestamp format for finding events to ensure consistency.

1. 💡 Quality: event_timestamp format undocumented for finding events
   Files: src/lib/state.ts:417-418, src/lib/state.ts:484-490

   `TelemetryEventMetadata.event_timestamp` is documented as "Epoch milliseconds as a string" (state.ts:417-418), but the inlined `metadata.event_timestamp` in the new `StoredFindingEvent` (state.ts:484-490) has no doc comment specifying the same format. Since CliAnalysisFindingDetected events are sent to the same backend, downstream code in CLI-728 could write an ISO string instead of epoch-ms, causing a silent format divergence between the two event types that the backend may reject or misparse. Add a matching doc comment (and ideally factor out a shared metadata type or `event_timestamp` semantic) to lock the format in. Note also that `StoredFindingEvent.metadata` duplicates the shape of `TelemetryEventMetadata` rather than reusing it; this is acceptable because `event_type` is a different literal, but documenting the timestamp keeps the two in sync.

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues
0 New dependency risks

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud