refactor(cli): derive the SSL assertion grammar from one declaration

The certificate/connection grammar was stated in four hand-synced places
— 19 operator classes, two operator maps, a value-type table, and a
comparison whitelist. Review found three ways they could drift while
compiling clean: an operator added to a class but not the whitelist, a
value type changed without the class's target type, and a property
literal copy-pasted onto the wrong class. TypeScript's Record keying
caught a missing entry but never a mismatched one.

Declare each property once, as data: the operators it exposes and its
target type. The property unions, the typed builder methods, the
validation whitelist, and codegen's literal kind are all derived from
that row, so the three drifts become structurally impossible — a
property cannot expose an operator its whitelist rejects, or a target
type codegen renders wrong, and there are no repeated literals to
mis-copy.

The generic machinery (operator catalog, target specs, the mapped type
that turns a row into a builder surface) lives in a monitor-agnostic
internal/assertion-grammar.ts; the SSL grammar tables and the runtime
lookups validation and codegen read live in ssl-assertion-grammar.ts.
Both stay out of the public API. Public call shapes, the property unions,
wire output, and per-property operator and target narrowing are all
unchanged: the pre-existing SSL tests pass untouched.

A new consistency spec iterates the grammar and asserts the builder,
validation and codegen agree for every declared (property, operator),
and that number and boolean properties declare only operators codegen
renders as literals — guarding the one drift the type system cannot,
using codegen's own predicates rather than restating them.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: sorccu

packages/cli/src/constructs/__tests__/ssl-assertion-grammar.spec.ts

@@ -0,0 +1,122 @@
+import { describe, it, expect } from 'vitest'
+
+import { Diagnostics } from '../diagnostics.js'
+import { operatorComparisons } from '../internal/assertion-grammar.js'
+import { certificateGrammar, connectionGrammar } from '../ssl-assertion-grammar.js'
+import { booleanComparisons, numericComparisons, valueForSslAssertion } from '../ssl-assertion-codegen.js'
+import { validateSslAssertion } from '../ssl-assertion-validation.js'
+import { SslAssertion, SslAssertionBuilder } from '../ssl-assertion.js'
+import { GeneratedFile, Output } from '../../sourcegen/index.js'
+
+// The grammar tables in internal/ssl-grammar.ts are the single declaration the builder,
+// the validation whitelist, and codegen are all derived from. These tests iterate that
+// data and assert the three consumers agree for every declared (property, operator), so a
+// drift between them cannot land — replacing the per-class synchronization the previous
+// design could not hold by hand.
+
+function render (assertion: SslAssertion): string {
+  const output = new Output()
+  valueForSslAssertion(new GeneratedFile('foo.ts'), assertion).render(output)
+  return output.finalize()
+}
+
+// A runtime target of the right shape for a property's value kind. The builder stringifies
+// it, so any in-kind value round-trips; validation then accepts it.
+function sampleTarget (kind: string): string | number | boolean {
+  switch (kind) {
+    case 'number':
+      return 1
+    case 'boolean':
+      return true
+    default:
+      return 'x'
+  }
+}
+
+const sources = [
+  { source: 'CERTIFICATE', method: 'certificate', grammar: certificateGrammar },
+  { source: 'CONNECTION', method: 'connection', grammar: connectionGrammar },
+] as const
+
+describe('SSL assertion grammar', () => {
+  it('routes every declared operator through the public builder to the right wire fields', () => {
+    for (const { source, method, grammar } of sources) {
+      for (const [property, decl] of Object.entries(grammar)) {
+        for (const operator of decl.operators) {
+          type Builder = Record<string, (t: unknown) => SslAssertion>
+          const builder = (SslAssertionBuilder[method] as (p: string) => Builder)(property)
+          const assertion = builder[operator](sampleTarget(decl.target.kind))
+          expect(assertion).toMatchObject({
+            source,
+            property,
+            comparison: operatorComparisons[operator],
+          })
+        }
+      }
+    }
+  })
+
+  it('accepts every declared (property, operator) through validation', () => {
+    for (const { source, grammar } of sources) {
+      for (const [property, decl] of Object.entries(grammar)) {
+        for (const operator of decl.operators) {
+          const assertion: SslAssertion = {
+            source,
+            property,
+            comparison: operatorComparisons[operator],
+            target: String(sampleTarget(decl.target.kind)),
+            regex: null,
+          }
+          const diags = new Diagnostics()
+          validateSslAssertion(diags, assertion, 0)
+          expect(diags.isFatal(), `${source}.${property}.${operator} should validate`).toEqual(false)
+        }
+      }
+    }
+  })
+
+  it('renders every declared (property, operator) naming the same property and operator', () => {
+    for (const { method, grammar } of sources) {
+      for (const [property, decl] of Object.entries(grammar)) {
+        for (const operator of decl.operators) {
+          const assertion: SslAssertion = {
+            source: method === 'certificate' ? 'CERTIFICATE' : 'CONNECTION',
+            property,
+            comparison: operatorComparisons[operator],
+            target: String(sampleTarget(decl.target.kind)),
+            regex: null,
+          }
+          const source = render(assertion)
+          expect(source).toContain(`SslAssertionBuilder.${method}('${property}')`)
+          expect(source).toContain(`.${operator}(`)
+        }
+      }
+    }
+  })
+
+  // Codegen renders a number target as a bare number literal and a boolean as a bare
+  // boolean, both only for the comparisons it has typed paths for. A property of that kind
+  // declaring any other operator would fall through to the quoted-string form, which does
+  // not compile against the property's typed builder method — the drift this guards against.
+  //
+  // The renderable sets are codegen's own predicates (numericComparisons / booleanComparisons),
+  // not restated here, so this cannot fall out of step with what codegen actually renders.
+  it('lets number and boolean properties declare only operators codegen renders as literals', () => {
+    const renderableFor: Record<string, Record<string, true>> = {
+      number: numericComparisons,
+      boolean: booleanComparisons,
+    }
+    for (const { grammar } of sources) {
+      for (const [property, decl] of Object.entries(grammar)) {
+        const renderable = renderableFor[decl.target.kind]
+        if (renderable === undefined) {
+          continue
+        }
+        for (const operator of decl.operators) {
+          const comparison = operatorComparisons[operator]
+          expect(Object.hasOwn(renderable, comparison), `${property}.${operator} is not rendered as a ${decl.target.kind} literal`).toBe(true)
+        }
+      }
+    }
+  })
+})

packages/cli/src/constructs/internal/assertion-grammar.ts

@@ -0,0 +1,131 @@
+import { Assertion, GeneralAssertionBuilder, toAssertion } from './assertion.js'
+
+// A property-scoped assertion grammar: one declaration per property states the operators
+// it exposes and the type of its target. The builder surface, the validation whitelist,
+// and codegen's literal kind are all derived from it, so a property's grammar lives in one
+// place instead of being restated in a builder class, a value-type table, and a whitelist.
+//
+// This module is monitor-agnostic; each monitor supplies its own grammar tables.
+
+// The operator catalog: builder method name -> wire comparison. Shared by every monitor
+// grammar; adding an operator is one line here plus listing it on the properties that
+// accept it.
+export const operatorComparisons = {
+  equals: 'EQUALS',
+  notEquals: 'NOT_EQUALS',
+  greaterThan: 'GREATER_THAN',
+  lessThan: 'LESS_THAN',
+  contains: 'CONTAINS',
+  notContains: 'NOT_CONTAINS',
+} as const
+
+export type OperatorName = keyof typeof operatorComparisons
+
+// How a target value is written on the wire. Drives validation's target-value check and
+// codegen's choice of a bare literal versus a quoted string.
+export type TargetValueType = 'number' | 'boolean' | 'string'
+
+// A target spec carries the runtime value kind and, through a phantom type parameter, the
+// compile-time target type. The symbol member is optional and never assigned, so a spec is
+// just `{ kind }` at runtime.
+//
+// The grammar constraint below uses the phantom-free supertype `AnyTargetSpec`, never
+// `TargetSpec<any>`: a `TargetSpec<any>` constraint would contextually type a bare
+// `stringTarget()` call, and contextual inference (`T = any`) would beat the `= string`
+// default — silently widening a plain-string property's target to `any`. With no phantom
+// member in the constraint there is no inference candidate, so the default holds.
+declare const targetType: unique symbol
+
+export interface AnyTargetSpec {
+  readonly kind: TargetValueType
+}
+
+export interface TargetSpec<T extends string | number | boolean> extends AnyTargetSpec {
+  readonly [targetType]?: T
+}
+
+export function numberTarget (): TargetSpec<number> {
+  return { kind: 'number' }
+}
+
+export function booleanTarget (): TargetSpec<boolean> {
+  return { kind: 'boolean' }
+}
+
+export function stringTarget<T extends string = string> (): TargetSpec<T> {
+  return { kind: 'string' }
+}
+
+export interface PropertyGrammar {
+  readonly operators: readonly OperatorName[]
+  readonly target: AnyTargetSpec
+}
+
+// `const G` keeps each row's operator array a literal tuple without callers writing
+// `as const`, so `keyof typeof grammar` and the per-property operator sets stay precise.
+export function defineGrammar<const G extends Record<string, PropertyGrammar>> (grammar: G): G {
+  return grammar
+}
+
+type TargetOf<Spec> = Spec extends TargetSpec<infer T> ? T : never
+
+// The builder surface for one property: each declared operator becomes a method taking the
+// property's target type. Distributing over a union `Decl` means a builder created from a
+// union property exposes only the operators common to every arm.
+export type PropertyOperators<Source extends string, Decl extends PropertyGrammar> =
+  Decl extends PropertyGrammar
+    ? { [Op in Decl['operators'][number]]: (target: TargetOf<Decl['target']>) => Assertion<Source> }
+    : never
+
+// Builds the operator object for a known property by looping over its declared operators.
+// The cast is the one unavoidable bridge in the design: TypeScript cannot connect a runtime
+// loop to a mapped type. It is sound because the loop defines exactly the keys in
+// `decl.operators`, each routed through `operatorComparisons` — the same data
+// `PropertyOperators` is computed from.
+function makeOperators<Source extends string, Decl extends PropertyGrammar> (
+  source: Source,
+  property: string,
+  decl: Decl,
+): PropertyOperators<Source, Decl> {
+  const operators: Record<string, (target: string | number | boolean) => Assertion<Source>> = {}
+  for (const operator of decl.operators) {
+    operators[operator] = target => toAssertion(source, operatorComparisons[operator], target, property)
+  }
+  return operators as PropertyOperators<Source, Decl>
+}
+
+// Resolves the operators for a property of a grammar.
+//
+// The typed signature makes an unknown property a compile error, but plain JavaScript
+// callers and object-literal assertions still reach this at runtime with an arbitrary
+// string. Those fall back to an unconstrained builder so the call returns something usable;
+// the property is then reported by the monitor's validation at deploy time rather than
+// throwing here.
+export function operatorsForProperty<
+  Source extends string,
+  Grammar extends Record<string, PropertyGrammar>,
+  Property extends keyof Grammar & string,
+> (
+  grammar: Grammar,
+  source: Source,
+  property: Property,
+): PropertyOperators<Source, Grammar[Property]> {
+  if (!Object.hasOwn(grammar, property)) {
+    const fallback = new GeneralAssertionBuilder<Source>(source, property)
+    return fallback as unknown as PropertyOperators<Source, Grammar[Property]>
+  }
+  return makeOperators(source, property, grammar[property])
+}
+
+// Runtime derivations shared by validation and codegen, so both read the same grammar the
+// builder is generated from.
+
+// The wire comparisons a property accepts, from its declared operators.
+export function comparisonsForGrammar (decl: PropertyGrammar): Record<string, true> {
+  return Object.fromEntries(decl.operators.map(operator => [operatorComparisons[operator], true]))
+}
+
+// How a property's target is written on the wire.
+export function valueTypeForGrammar (decl: PropertyGrammar): TargetValueType {
+  return decl.target.kind
+}

packages/cli/src/constructs/internal/ssl-properties.ts

@@ -5,7 +5,7 @@ import {
   valueForGeneralAssertion,
   valueForNumericAssertion,
 } from './internal/assertion-codegen.js'
-import { isSslNumericTarget, sslPropertyValueType } from './internal/ssl-properties.js'
+import { isSslNumericTarget, sslPropertyValueType } from './ssl-assertion-grammar.js'
 import { SslAssertion } from './ssl-assertion.js'
 
 // Every SSL source addresses its value through the property slot — CERTIFICATE /
@@ -16,11 +16,20 @@ const withProperty = { hasProperty: true, hasRegex: false }
 
 // The comparisons each typed helper can render. A comparison outside the set makes the
 // helper throw, which would abort the whole import over a single assertion, so the
-// dispatch below checks membership rather than relying on the throw.
-const numericComparisons: Record<string, true> = {
+// dispatch below checks membership rather than relying on the throw. Exported so the
+// grammar consistency spec can assert numeric properties declare only operators this
+// renders, rather than restating the set.
+export const numericComparisons: Record<string, true> = {
   EQUALS: true, NOT_EQUALS: true, GREATER_THAN: true, LESS_THAN: true,
 }
 
+// The boolean helper renders only EQUALS as a bare boolean literal; any other comparison
+// falls through to the quoted-string form, which would not compile against a boolean
+// operator. The grammar spec asserts boolean properties declare only this.
+export const booleanComparisons: Record<string, true> = {
+  EQUALS: true,
+}
+
 // The operators for a numeric or boolean property take a `number` / `boolean`, so their
 // targets must be emitted as bare literals rather than quoted strings — otherwise the
 // generated code does not compile.
@@ -51,7 +60,7 @@ function valueForPropertyScopedAssertion (method: string, assertion: SslAssertio
   }
 
   const isRenderableBoolean = valueType === 'boolean'
-    && assertion.comparison === 'EQUALS'
+    && Object.hasOwn(booleanComparisons, assertion.comparison)
     && (assertion.target === 'true' || assertion.target === 'false')
   if (isRenderableBoolean) {
     return valueForBooleanAssertion('SslAssertionBuilder', method, assertion, { hasProperty: true })