Skip to content
Merged
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
8 changes: 7 additions & 1 deletion CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -126,7 +126,13 @@ in `docs/adr/0001-event-bus-and-alerts.md`.

- Names: `<module>.<resource>.<action>`, snake_case, past participle
(`code_report.analysis.completed`, `vault.secret.created`, `access.granted`). Declare each type
and its payload in `DomainEventMap` (`src/lib/server/events/types.ts`).
and its payload in `DomainEventMap` (`src/lib/events/domain-events.ts`, shared with the client).
- Every event needs an `EventDefinition` in the catalog (`src/lib/events/catalog/`, one
`<module>.events.ts` per module): scope, `readPermission`, `alertable` and its filterable fields.
`EVENT_CATALOG` is exhaustive and field keys without `derive` are checked against the payload at
compile time. Labels are i18n keys (`events.<type>.label`, `.description`,
`.fields.<key>`, `events.options.<group>.<value>`) and must exist in `es.json` and `en.json`
(enforced by a test).
- Publish only **after** the GitDB write succeeded, with the right `scope`
(`organizationId` / `projectId`). `publish()` returns immediately; handlers run asynchronously,
in order per subscriber, and a failing handler is only logged.
Expand Down
184 changes: 184 additions & 0 deletions src/lib/events/catalog/catalog.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
import { describe, expect, it } from 'vitest';
import es from '#lib/i18n/locales/es.json';
import en from '#lib/i18n/locales/en.json';
import type { CodeReportAnalysisCompletedPayload } from '../domain-events';
import {
EVENT_CATALOG,
defineEventCatalog,
getEventDefinition,
getFieldValue,
isEventType,
listAlertableEvents,
type EventCatalog,
type EventDefinition,
type EventFieldDefinition,
} from './index';

function completedPayload(
overrides: Partial<CodeReportAnalysisCompletedPayload> = {},
): CodeReportAnalysisCompletedPayload {
return {
analysisId: 'analysis-1',
serviceId: 'service-1',
tool: 'trivy',
gitInfo: { repositoryUrl: null, branch: 'main', commit: 'abc', version: null },
summary: { critical: 2, high: 1, medium: 0, low: 0, unknown: 0, total: 3, secrets: 0 },
policies: { status: 'compliant', totalViolations: 0, blockingFailures: 0, failedPolicyIds: [] },
...overrides,
};
}

describe('event catalog: compile-time checks', () => {
it('rejects a field key that is not a path of the payload', () => {
const valid: EventFieldDefinition<CodeReportAnalysisCompletedPayload> = {
key: 'gitInfo.branch',
label: 'x',
type: 'string',
operators: ['eq'],
};
// @ts-expect-error 'gitInfo.tag' is not a path of the payload (and there is no `derive`)
const invalid: EventFieldDefinition<CodeReportAnalysisCompletedPayload> = {
key: 'gitInfo.tag',
label: 'x',
type: 'string',
operators: ['eq'],
};
const derived: EventFieldDefinition<CodeReportAnalysisCompletedPayload> = {
key: 'anything',
label: 'x',
type: 'boolean',
operators: ['is_true'],
derive: (payload) => payload.summary.total > 0,
};

expect([valid.key, invalid.key, derived.key]).toHaveLength(3);
});

it('requires a definition for every event of DomainEventMap', () => {
const incomplete: Partial<EventCatalog> = { ...EVENT_CATALOG };
delete incomplete['code_report.analysis.failed'];
// @ts-expect-error 'code_report.analysis.failed' is missing
const catalog: EventCatalog = incomplete;

expect(Object.keys(catalog)).not.toContain('code_report.analysis.failed');
});
});

describe('defineEventCatalog', () => {
it('rejects an entry whose type does not match its key', () => {
const completed = EVENT_CATALOG['code_report.analysis.completed'];
expect(() =>
defineEventCatalog({
...EVENT_CATALOG,
'code_report.analysis.failed': {
...completed,
} as unknown as EventDefinition<'code_report.analysis.failed'>,
}),
).toThrow(/declares type/);
});

it('rejects duplicated field keys', () => {
const failed = EVENT_CATALOG['code_report.analysis.failed'];
expect(() =>
defineEventCatalog({
...EVENT_CATALOG,
'code_report.analysis.failed': { ...failed, fields: [...failed.fields, failed.fields[0]] },
}),
).toThrow(/twice/);
});
});

describe('catalog helpers', () => {
it('looks up definitions and event types', () => {
expect(getEventDefinition('code_report.analysis.completed').readPermission).toBe(
'project:codereport:reports:read',
);
expect(isEventType('code_report.analysis.completed')).toBe(true);
expect(isEventType('code_report.analysis.unknown')).toBe(false);
expect(isEventType('toString')).toBe(false);
});

it('lists alertable events filtered by scope and module', () => {
const projectEvents = listAlertableEvents({ scope: 'project', module: 'code_report' });

expect(projectEvents.map((definition) => definition.type)).toContain(
'code_report.analysis.completed',
);
expect(listAlertableEvents({ scope: 'organization', module: 'code_report' })).toEqual([]);
});

it('reads nested payload paths', () => {
const event = { type: 'code_report.analysis.completed' as const, payload: completedPayload() };

expect(getFieldValue(event, 'gitInfo.branch')).toBe('main');
expect(getFieldValue(event, 'summary.critical')).toBe(2);
expect(getFieldValue(event, 'serviceId')).toBe('service-1');
});

it('computes derived fields', () => {
const clean = completedPayload({
summary: { critical: 0, high: 0, medium: 0, low: 0, unknown: 0, total: 0, secrets: 0 },
});
const violated = completedPayload({
policies: {
status: 'violated',
totalViolations: 2,
blockingFailures: 1,
failedPolicyIds: ['p'],
},
});
const type = 'code_report.analysis.completed' as const;

expect(getFieldValue({ type, payload: completedPayload() }, 'hasVulnerabilities')).toBe(true);
expect(getFieldValue({ type, payload: clean }, 'hasVulnerabilities')).toBe(false);
expect(getFieldValue({ type, payload: clean }, 'policiesViolated')).toBe(false);
expect(getFieldValue({ type, payload: violated }, 'policiesViolated')).toBe(true);
});

it('returns undefined for unknown fields and missing paths', () => {
const type = 'code_report.analysis.completed' as const;
const payload = completedPayload({ gitInfo: null as never });

expect(getFieldValue({ type, payload }, 'gitInfo.branch')).toBeUndefined();
// a real payload path that is not exposed in the catalog is not filterable
expect(getFieldValue({ type, payload }, 'analysisId')).toBeUndefined();
});
});

describe('catalog translations', () => {
function lookup(messages: unknown, key: string): unknown {
// keys may contain dots both as nesting and inside event types / field paths, so walk the
// object tree trying the longest matching segment first
if (key === '') return messages;
if (messages === null || typeof messages !== 'object') return undefined;
const record = messages as Record<string, unknown>;
const segments = key.split('.');
for (let length = segments.length; length > 0; length -= 1) {
const head = segments.slice(0, length).join('.');
if (head in record) {
const found = lookup(record[head], segments.slice(length).join('.'));
if (found !== undefined) return found;
}
}
return undefined;
}

function catalogKeys(): string[] {
return (Object.values(EVENT_CATALOG) as EventDefinition[]).flatMap((definition) => [
definition.label,
definition.description,
...definition.fields.flatMap((field) => [
field.label,
...(field.options ?? []).map((option) => option.label),
]),
]);
}

it.each([
['es', es],
['en', en],
])('has a %s translation for every event, field and option', (_locale, messages) => {
const missing = catalogKeys().filter((key) => typeof lookup(messages, key) !== 'string');
expect(missing).toEqual([]);
});
});
184 changes: 184 additions & 0 deletions src/lib/events/catalog/code-report.events.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,184 @@
import {
SECURITY_POLICY_ENFORCEMENTS,
SECURITY_POLICY_TYPES,
} from '#lib/code-report/security-policy';
import { OPERATORS, enumOptions, eventText, fieldLabel } from './fields';
import type { EventDefinitions } from './types';

/** Tools that report analyses: scanners plus the manual upload and the CI/CD API defaults. */
export const CODE_REPORT_TOOLS = [
'trivy',
'grype',
'semgrep',
'gitleaks',
'trufflehog',
'sbom',
'syft',
'coverage',
'manual-upload',
'api',
] as const;

const READ_REPORTS = 'project:codereport:reports:read';

const COMPLETED = 'code_report.analysis.completed';
const FAILED = 'code_report.analysis.failed';
const POLICY_VIOLATED = 'code_report.policy.violated';
const SERVICE_CREATED = 'code_report.service.created';
const SERVICE_DELETED = 'code_report.service.deleted';

function serviceField(type: typeof COMPLETED | typeof FAILED | typeof POLICY_VIOLATED) {
return {
key: 'serviceId',
label: fieldLabel(type, 'serviceId'),
type: 'reference',
reference: 'code_report_service',
operators: OPERATORS.reference,
} as const;
}

function toolField(type: typeof COMPLETED | typeof FAILED | typeof POLICY_VIOLATED) {
return {
key: 'tool',
label: fieldLabel(type, 'tool'),
type: 'enum',
options: enumOptions('tool', CODE_REPORT_TOOLS),
operators: ['eq', 'neq', 'in'],
} as const;
}

function branchField(type: typeof COMPLETED | typeof FAILED) {
return {
key: 'gitInfo.branch',
label: fieldLabel(type, 'gitInfo.branch'),
type: 'string',
operators: OPERATORS.string,
} as const;
}

function countField<K extends `summary.${'critical' | 'high' | 'medium' | 'low' | 'total'}`>(
key: K,
) {
return {
key,
label: fieldLabel(COMPLETED, key),
type: 'number',
operators: OPERATORS.number,
} as const;
}

export const codeReportEvents: EventDefinitions<
| typeof COMPLETED
| typeof FAILED
| typeof POLICY_VIOLATED
| typeof SERVICE_CREATED
| typeof SERVICE_DELETED
> = {
[COMPLETED]: {
...eventText(COMPLETED),
module: 'code_report',
scope: 'project',
readPermission: READ_REPORTS,
alertable: true,
fields: [
serviceField(COMPLETED),
toolField(COMPLETED),
branchField(COMPLETED),
countField('summary.critical'),
countField('summary.high'),
countField('summary.medium'),
countField('summary.low'),
countField('summary.total'),
{
key: 'hasVulnerabilities',
label: fieldLabel(COMPLETED, 'hasVulnerabilities'),
type: 'boolean',
operators: OPERATORS.boolean,
derive: (payload) => payload.summary.total > 0,
},
{
key: 'policiesViolated',
label: fieldLabel(COMPLETED, 'policiesViolated'),
type: 'boolean',
operators: OPERATORS.boolean,
derive: (payload) => payload.policies.status === 'violated',
},
],
},
[FAILED]: {
...eventText(FAILED),
module: 'code_report',
scope: 'project',
readPermission: READ_REPORTS,
alertable: true,
fields: [serviceField(FAILED), toolField(FAILED), branchField(FAILED)],
},
[POLICY_VIOLATED]: {
...eventText(POLICY_VIOLATED),
module: 'code_report',
scope: 'project',
readPermission: READ_REPORTS,
alertable: true,
fields: [
serviceField(POLICY_VIOLATED),
{
key: 'policyId',
label: fieldLabel(POLICY_VIOLATED, 'policyId'),
type: 'reference',
reference: 'code_report_policy',
operators: OPERATORS.reference,
},
{
key: 'policyType',
label: fieldLabel(POLICY_VIOLATED, 'policyType'),
type: 'enum',
options: enumOptions('policyType', SECURITY_POLICY_TYPES),
operators: OPERATORS.enum,
},
{
key: 'enforcement',
label: fieldLabel(POLICY_VIOLATED, 'enforcement'),
type: 'enum',
options: enumOptions('enforcement', SECURITY_POLICY_ENFORCEMENTS),
operators: OPERATORS.enum,
},
],
},
[SERVICE_CREATED]: {
...eventText(SERVICE_CREATED),
module: 'code_report',
scope: 'project',
readPermission: READ_REPORTS,
alertable: true,
fields: [
{
key: 'name',
label: fieldLabel(SERVICE_CREATED, 'name'),
type: 'string',
operators: OPERATORS.string,
},
],
},
[SERVICE_DELETED]: {
...eventText(SERVICE_DELETED),
module: 'code_report',
scope: 'project',
readPermission: READ_REPORTS,
alertable: true,
fields: [
{
key: 'serviceId',
label: fieldLabel(SERVICE_DELETED, 'serviceId'),
type: 'reference',
reference: 'code_report_service',
operators: OPERATORS.reference,
},
{
key: 'name',
label: fieldLabel(SERVICE_DELETED, 'name'),
type: 'string',
operators: OPERATORS.string,
},
],
},
};
Loading
Loading