feat: per-alarm action and severity overrides

[sai-ray]

Fixes #1599

This PR adds alarmOverrides on ConstructHub so customers can change what fires for a specific alarm at deploy time.

Today every alarm is locked into one of three severity buckets and each bucket has one action. Customers can't reclassify a single alarm or attach a custom action to one. The existing AlarmSeverities interface only covers two named alarms.

Example usage

This is the actual stack used to verify the feature against a real AWS account; every override flavor is exercised below.

import * as cdk from 'aws-cdk-lib/core';
import { SnsAction } from 'aws-cdk-lib/aws-cloudwatch-actions';
import * as sns from 'aws-cdk-lib/aws-sns';
import { Construct } from 'constructs';
import { AlarmSeverity, ConstructHub, Isolation } from 'construct-hub';

export class TempStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    const highTopic = new sns.Topic(this, 'HighTopic');
    const lowTopic = new sns.Topic(this, 'LowTopic');
    const customTopic = new sns.Topic(this, 'CustomTopic');

    new ConstructHub(this, 'ConstructHub', {
      sensitiveTaskIsolation: Isolation.UNLIMITED_INTERNET_ACCESS,
      alarmActions: {
        highSeverityAction: new SnsAction(highTopic),
        normalSeverityAction: new SnsAction(lowTopic),
      },
      alarmOverrides: {
        // (1) HIGH → LOW — downgrade
        'Sources/NpmJs/Canary/NotRunningOrFailing': { severity: AlarmSeverity.LOW },
        // (2) LOW → HIGH — upgrade (should appear on the high-sev dashboard)
        'PackageStats/Failures': { severity: AlarmSeverity.HIGH },
        // (3) actions-only — bypasses the bucket action
        'Ingestion/DLQNotEmpty': { actions: [new SnsAction(customTopic)] },
        // (4) severity + actions
        'Sources/NpmJs/Canary/StaleCanaryPackage': {
          severity: AlarmSeverity.HIGH,
          actions: [new SnsAction(customTopic)],
        },
        // (5) actions: [] — falls back to bucket action (does NOT mute)
        'VersionTracker/NotRunning': { actions: [] },
      },
    });
  }
}

The actual aws cloudwatch describe-alarms output after deploy:

Alarm	Default sev	Override	Wired to	✓
Sources/NpmJs/Canary/NotRunningOrFailing	HIGH	severity: LOW	LowTopic	✅
PackageStats/Failures	LOW	severity: HIGH	HighTopic	✅
Ingestion/DLQNotEmpty	HIGH	actions: [custom]	CustomTopic	✅
Sources/NpmJs/Canary/StaleCanaryPackage	MEDIUM	severity: HIGH, actions: [custom]	CustomTopic	✅
VersionTracker/NotRunning	LOW	actions: []	LowTopic (fallback)	✅
Ingestion/Failure (control)	HIGH	—	HighTopic	✅
VersionTracker/Failures (control)	LOW	—	LowTopic	✅

The two control rows (no override) prove the override is what's changing the wiring, not a fixed rule.

Raw aws cloudwatch describe-alarms output

--- Sources/NpmJs/Canary/NotRunningOrFailing ---
  AlarmName: AlarmOverridesSanity/ConstructHub/Sources/NpmJs/Canary/NotRunningOrFailing
  StateValue: OK
  AlarmAction: arn:aws:sns:us-east-1:XXXXXXXXXXXX:AlarmOverridesSanity-LowTopic4E7342F5-2LhqEbe3Nq27  (LowTopic)

--- PackageStats/Failures ---
  AlarmName: AlarmOverridesSanity/ConstructHub/PackageStats/Failures
  StateValue: INSUFFICIENT_DATA
  AlarmAction: arn:aws:sns:us-east-1:XXXXXXXXXXXX:AlarmOverridesSanity-HighTopic335D797C-GajKrapOI2K8  (HighTopic)

--- Ingestion/DLQNotEmpty ---
  AlarmName: AlarmOverridesSanity/ConstructHub/Ingestion/DLQNotEmpty
  StateValue: OK
  AlarmAction: arn:aws:sns:us-east-1:XXXXXXXXXXXX:AlarmOverridesSanity-CustomTopicE1837878-3SNvSZVTUsuD  (CustomTopic)

--- Sources/NpmJs/Canary/StaleCanaryPackage ---
  AlarmName: AlarmOverridesSanity/ConstructHub/Sources/NpmJs/Canary/StaleCanaryPackage
  StateValue: OK
  AlarmAction: arn:aws:sns:us-east-1:XXXXXXXXXXXX:AlarmOverridesSanity-CustomTopicE1837878-3SNvSZVTUsuD  (CustomTopic)

--- VersionTracker/NotRunning ---
  AlarmName: AlarmOverridesSanity/ConstructHub/VersionTracker/NotRunning
  StateValue: OK
  AlarmAction: arn:aws:sns:us-east-1:XXXXXXXXXXXX:AlarmOverridesSanity-LowTopic4E7342F5-2LhqEbe3Nq27  (LowTopic)

--- Ingestion/Failure (control) ---
  AlarmName: AlarmOverridesSanity/ConstructHub/Ingestion/Failure
  StateValue: OK
  AlarmAction: arn:aws:sns:us-east-1:XXXXXXXXXXXX:AlarmOverridesSanity-HighTopic335D797C-GajKrapOI2K8  (HighTopic)

--- VersionTracker/Failures (control) ---
  AlarmName: AlarmOverridesSanity/ConstructHub/VersionTracker/Failures
  StateValue: OK
  AlarmAction: arn:aws:sns:us-east-1:XXXXXXXXXXXX:AlarmOverridesSanity-LowTopic4E7342F5-2LhqEbe3Nq27  (LowTopic)

• severity — wire this alarm to a different bucket's action (AlarmSeverity.HIGH / MEDIUM / LOW).
• actions — supply custom actions that bypass the buckets entirely.
• Either, both, or neither.

Keys are the alarm's CloudWatch display name relative to the ConstructHub construct i.e. the same string a customer sees in tickets and the CloudWatch console.

Note

The existing AlarmActions interface calls the lowest-tier slot normalSeverity (legacy). Everywhere else in
the codebase (the AlarmSeverity enum, add*SeverityAlarm methods, and our new severity field) uses
LOW. Renaming AlarmActions.normalSeverity → lowSeverity can be a separate PR.

Warning

Three previously-anonymous alarms now have explicit alarmNames

The lookup mechanism keys on the alarm's CloudWatch display name. Three alarms in the codebase predate the alarmName: ${scope.node.path}/... convention and had no explicit name set:

• MonitoredCertificate/ACMAlarm (45-day cert expiry)
• MonitoredCertificate/EndpointAlarm (45-day cert expiry)
• Monitoring/WebCanary/Errors (web canary error rate)

This PR adds explicit names to all three, which means CloudFormation will replace the existing alarms (delete + create) on next deploy. The replacement is acceptable because (a) CloudWatch alarms hold no state, (b) the gap is bounded by the deploy duration, and (c) none of the three are time-sensitive (cert expiry is a 45-day window; the web canary fires only on sustained errors).

Implementation

• New AlarmOverride interface in src/api.ts.
• Monitoring reads (alarm.node.defaultChild as CfnAlarm | CfnCompositeAlarm).alarmName, strips the ConstructHub prefix, looks up the override. If found, fully wires the alarm itself; otherwise falls through to existing per-bucket logic. Each add*SeverityAlarm gains one early-return line; existing logic is untouched.
• alarmOverrides lives entirely on ConstructHub props, no per-source plumbing.
• Unknown override keys, and any registered alarm without an explicit alarmName, are surfaced as synth-time validation errors via node.addValidation. Validation only runs when alarmOverrides is non-empty, so existing customers and downstream forks are unaffected.
• An actions: [] override falls back to the bucket action (rather than silently muting the alarm).

Coverage

Every alarm registered through IMonitoring is overridable. Three alarms that previously had no explicit alarmName (the two cert-expiry alarms and the web canary alarm) now have one, so they're covered too.

Tests

7 new tests in monitoring.test.ts: severity-only override, actions-only override, both, empty actions: [] falls back to bucket, unknown override key (synth-time error), default path with explicit alarmName, alarm registered without alarmName when overrides are set (synth-time error).

---

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license