Open History to see the last commit
1/**
2 * Selection grammar (PLAN.md task 12.3):
3 *
4 * provider[/endpointPattern][#request|#response]
5 *
6 * `endpointPattern` may contain `*` globs and is matched against public
7 * endpoint ids (which themselves contain slashes, e.g. `v1/messages`).
8 * Omitting the pattern selects every endpoint; omitting the kind selects
9 * both — implicitly, so a missing side (e.g. an endpoint with no response
10 * schema) is skipped rather than an error.
11 */
12
13export type Kind = 'input' | 'output'
14export type KindLabel = 'request' | 'response'
15
16export const KIND_LABEL: Record<Kind, KindLabel> = {
17 input: 'request',
18 output: 'response',
19}
20export const LABEL_KIND: Record<KindLabel, Kind> = {
21 request: 'input',
22 response: 'output',
23}
24
25export interface ParsedSelection {
26 provider: string
27 /** Glob over public endpoint ids; `*` when the selection names none. */
28 endpointPattern: string
29 kinds: Array<Kind>
30 /** True when the selection pinned a kind with `#request`/`#response`. */
31 explicitKind: boolean
32 raw: string
33}
34
35export function parseSelection(raw: string): ParsedSelection {
36 const trimmed = raw.trim()
37 if (trimmed === '') throw new Error('Empty selection.')
38
39 const hashIndex = trimmed.indexOf('#')
40 const body = hashIndex === -1 ? trimmed : trimmed.slice(0, hashIndex)
41 const kindLabel = hashIndex === -1 ? undefined : trimmed.slice(hashIndex + 1)
42 if (kindLabel?.includes('#') === true) {
43 throw new Error(`Selection '${raw}': more than one '#'.`)
44 }
45 let kinds: Array<Kind> = ['input', 'output']
46 if (kindLabel !== undefined) {
47 if (kindLabel !== 'request' && kindLabel !== 'response') {
48 throw new Error(
49 `Selection '${raw}': unknown kind '#${kindLabel}'. Use #request or #response.`,
50 )
51 }
52 kinds = [LABEL_KIND[kindLabel]]
53 }
54
55 const slash = body.indexOf('/')
56 const provider = slash === -1 ? body : body.slice(0, slash)
57 const endpointPattern = slash === -1 ? '*' : body.slice(slash + 1)
58 if (provider === '') throw new Error(`Selection '${raw}': empty provider.`)
59 if (provider.includes('*')) {
60 throw new Error(
61 `Selection '${raw}': globs are only supported in the endpoint part — name a provider (GET /v1/providers lists them).`,
62 )
63 }
64 if (endpointPattern === '') {
65 throw new Error(`Selection '${raw}': empty endpoint pattern after '/'.`)
66 }
67
68 return {
69 provider,
70 endpointPattern,
71 kinds,
72 explicitKind: kindLabel !== undefined,
73 raw: trimmed,
74 }
75}
76
77export function globToRegExp(pattern: string): RegExp {
78 const escaped = pattern
79 .split('*')
80 .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
81 .join('.*')
82 return new RegExp(`^${escaped}$`)
83}
84
85export interface ResolvedTarget {
86 provider: string
87 activity: string
88 endpointId: string
89 kind: Kind
90 explicitKind: boolean
91 /** The selection string that produced this target. */
92 selector: string
93}
94
95/** The `/v1/schemas/{provider}` index shape this package consumes. */
96export interface ProviderSchemaIndex {
97 provider: string
98 activities: Record<string, Array<string>>
99}
100
101/**
102 * Expand one parsed selection against a provider's schema index. Throws
103 * when a concrete (glob-free) pattern matches nothing — that's a typo, and
104 * the error lists valid ids; an unmatched glob just returns [].
105 */
106export function matchTargets(
107 selection: ParsedSelection,
108 index: ProviderSchemaIndex,
109): Array<ResolvedTarget> {
110 const pattern = globToRegExp(selection.endpointPattern)
111 const targets: Array<ResolvedTarget> = []
112 for (const [activity, endpointIds] of Object.entries(index.activities)) {
113 for (const endpointId of endpointIds) {
114 if (!pattern.test(endpointId)) continue
115 for (const kind of selection.kinds) {
116 targets.push({
117 provider: selection.provider,
118 activity,
119 endpointId,
120 kind,
121 explicitKind: selection.explicitKind,
122 selector: selection.raw,
123 })
124 }
125 }
126 }
127 if (targets.length === 0 && !selection.endpointPattern.includes('*')) {
128 const valid = Object.values(index.activities).flat().slice(0, 25)
129 throw new Error(
130 `Selection '${selection.raw}': no endpoint '${selection.endpointPattern}' for provider '${selection.provider}'.` +
131 (valid.length > 0 ? ` Valid endpoint ids: ${valid.join(', ')}.` : ''),
132 )
133 }
134 return targets
135}