@appport/contract-builder 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +396 -0
- package/dist/compatibility.d.ts +24 -0
- package/dist/compatibility.d.ts.map +1 -0
- package/dist/compatibility.js +86 -0
- package/dist/compatibility.js.map +1 -0
- package/dist/contract.d.ts +258 -0
- package/dist/contract.d.ts.map +1 -0
- package/dist/contract.js +316 -0
- package/dist/contract.js.map +1 -0
- package/dist/diff.d.ts +32 -0
- package/dist/diff.d.ts.map +1 -0
- package/dist/diff.js +110 -0
- package/dist/diff.js.map +1 -0
- package/dist/generators/python-server.d.ts +13 -0
- package/dist/generators/python-server.d.ts.map +1 -0
- package/dist/generators/python-server.js +193 -0
- package/dist/generators/python-server.js.map +1 -0
- package/dist/generators/stubs.d.ts +10 -0
- package/dist/generators/stubs.d.ts.map +1 -0
- package/dist/generators/stubs.js +58 -0
- package/dist/generators/stubs.js.map +1 -0
- package/dist/generators/typescript-server.d.ts +12 -0
- package/dist/generators/typescript-server.d.ts.map +1 -0
- package/dist/generators/typescript-server.js +190 -0
- package/dist/generators/typescript-server.js.map +1 -0
- package/dist/hooks.d.ts +73 -0
- package/dist/hooks.d.ts.map +1 -0
- package/dist/hooks.js +55 -0
- package/dist/hooks.js.map +1 -0
- package/dist/index.d.ts +10 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +10 -0
- package/dist/index.js.map +1 -0
- package/dist/manifest.d.ts +23 -0
- package/dist/manifest.d.ts.map +1 -0
- package/dist/manifest.js +148 -0
- package/dist/manifest.js.map +1 -0
- package/dist/validate.d.ts +12 -0
- package/dist/validate.d.ts.map +1 -0
- package/dist/validate.js +238 -0
- package/dist/validate.js.map +1 -0
- package/package.json +29 -0
package/README.md
ADDED
|
@@ -0,0 +1,396 @@
|
|
|
1
|
+
# @appport/contract-builder
|
|
2
|
+
|
|
3
|
+
Contract builder for creating portable AppPort application contracts.
|
|
4
|
+
|
|
5
|
+
## Overview
|
|
6
|
+
|
|
7
|
+
The contract builder provides tools for defining AppPort application contracts independently of their implementation. Contracts are the canonical machine-readable format that describe what an application can do.
|
|
8
|
+
|
|
9
|
+
## Usage
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
# Create a new contract
|
|
13
|
+
appport contract init
|
|
14
|
+
|
|
15
|
+
# Inspect a contract
|
|
16
|
+
appport contract inspect appport/contract.json
|
|
17
|
+
|
|
18
|
+
# Validate a contract
|
|
19
|
+
appport contract validate appport/contract.json
|
|
20
|
+
|
|
21
|
+
# Compare two contracts
|
|
22
|
+
appport contract diff old.json new.json
|
|
23
|
+
|
|
24
|
+
# Generate a TypeScript implementation skeleton
|
|
25
|
+
appport contract generate --output my-app
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
## Contract Format
|
|
29
|
+
|
|
30
|
+
A contract is a JSON file describing the application and its capabilities:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"protocol": "appport/1",
|
|
35
|
+
"application": {
|
|
36
|
+
"id": "com.example.myapp",
|
|
37
|
+
"name": "My App",
|
|
38
|
+
"version": "1.0.0",
|
|
39
|
+
"description": "A sample application"
|
|
40
|
+
},
|
|
41
|
+
"capabilities": [
|
|
42
|
+
{
|
|
43
|
+
"name": "documents.list",
|
|
44
|
+
"version": 1,
|
|
45
|
+
"description": "List all documents",
|
|
46
|
+
"purpose": "Retrieve all documents",
|
|
47
|
+
"authority": "documents",
|
|
48
|
+
"input": { "type": "object", "properties": {} },
|
|
49
|
+
"output": {
|
|
50
|
+
"type": "object",
|
|
51
|
+
"properties": {
|
|
52
|
+
"documents": {
|
|
53
|
+
"type": "array",
|
|
54
|
+
"items": { "type": "object" }
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
},
|
|
58
|
+
"authorization": ["documents.read"],
|
|
59
|
+
"effects": [
|
|
60
|
+
{
|
|
61
|
+
"type": "read",
|
|
62
|
+
"description": "Reads document data"
|
|
63
|
+
}
|
|
64
|
+
]
|
|
65
|
+
}
|
|
66
|
+
],
|
|
67
|
+
"events": []
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Building Contracts Programmatically
|
|
72
|
+
|
|
73
|
+
PR15 introduces a contract-native capability builder for fluent contract construction:
|
|
74
|
+
|
|
75
|
+
```typescript
|
|
76
|
+
import { createContractBuilder, capability } from "@appport/contract-builder";
|
|
77
|
+
|
|
78
|
+
// Create a contract builder
|
|
79
|
+
const contract = createContractBuilder({
|
|
80
|
+
id: "com.example.invoicing",
|
|
81
|
+
name: "Invoicing",
|
|
82
|
+
version: "1.0"
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
// Define and attach capabilities using the builder pattern
|
|
86
|
+
const refund = contract
|
|
87
|
+
.capability("invoice.refund", "1")
|
|
88
|
+
.purpose("Refund an invoice")
|
|
89
|
+
.input({
|
|
90
|
+
type: "object",
|
|
91
|
+
properties: {
|
|
92
|
+
invoice_id: { type: "string" },
|
|
93
|
+
reason: { type: "string" }
|
|
94
|
+
},
|
|
95
|
+
required: ["invoice_id", "reason"]
|
|
96
|
+
})
|
|
97
|
+
.output({
|
|
98
|
+
type: "object",
|
|
99
|
+
properties: {
|
|
100
|
+
refund_id: { type: "string" },
|
|
101
|
+
invoice_id: { type: "string" },
|
|
102
|
+
status: { type: "string" }
|
|
103
|
+
},
|
|
104
|
+
required: ["refund_id", "invoice_id", "status"]
|
|
105
|
+
})
|
|
106
|
+
.authority("invoicing")
|
|
107
|
+
.requiresScope("invoice.refund")
|
|
108
|
+
.effect({
|
|
109
|
+
type: "state",
|
|
110
|
+
description: "Invoice becomes refunded"
|
|
111
|
+
})
|
|
112
|
+
.emits("invoice.refunded@1")
|
|
113
|
+
.build();
|
|
114
|
+
|
|
115
|
+
contract.attach(refund);
|
|
116
|
+
|
|
117
|
+
// Manage capabilities
|
|
118
|
+
contract.getCapability("invoice.refund@1"); // Get by ID (name@version)
|
|
119
|
+
contract.listCapabilities(); // List all attached capabilities
|
|
120
|
+
contract.detach("invoice.refund@1"); // Remove a capability
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
### Capability Builder API
|
|
124
|
+
|
|
125
|
+
- `.purpose(text: string)` - Set the semantic purpose of the capability
|
|
126
|
+
- `.input(schema: JSONSchema)` - Define the input schema
|
|
127
|
+
- `.output(schema: JSONSchema)` - Define the output schema
|
|
128
|
+
- `.authority(auth: string)` - Set the domain/authority this capability belongs to
|
|
129
|
+
- `.requiresScope(scope: string)` - Add an authorization scope requirement
|
|
130
|
+
- `.effect(effect: CapabilityEffect)` - Add an effect this capability produces
|
|
131
|
+
- `.emits(event: string)` - Add an event this capability emits
|
|
132
|
+
- `.description(text: string)` - Set the description
|
|
133
|
+
- `.kind(kind: "request" | "stream")` - Set the capability kind
|
|
134
|
+
- `.build()` - Build and return the capability
|
|
135
|
+
|
|
136
|
+
### Contract Builder API (PR15)
|
|
137
|
+
|
|
138
|
+
- `.capability(name: string, version: string | number)` - Create a capability builder
|
|
139
|
+
- `.attach(capability: ContractCapability)` - Attach a capability to the contract
|
|
140
|
+
- `.detach(capabilityId: string)` - Remove a capability by ID (name@version format)
|
|
141
|
+
- `.getCapability(capabilityId: string)` - Retrieve a capability by ID
|
|
142
|
+
- `.listCapabilities()` - Get all attached capabilities
|
|
143
|
+
- `.listProvidedCapabilities()` - Alias for listCapabilities
|
|
144
|
+
|
|
145
|
+
## Application Capability Relationships (PR16)
|
|
146
|
+
|
|
147
|
+
PR16 extends contracts to declare both what an application provides and what it requires from other applications.
|
|
148
|
+
|
|
149
|
+
### Capability Requirements
|
|
150
|
+
|
|
151
|
+
Applications can declare external dependencies using capability requirements. Requirements support version constraints to enable dynamic composition:
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
import { createContractBuilder, requirement } from "@appport/contract-builder";
|
|
155
|
+
|
|
156
|
+
const commerce = createContractBuilder({
|
|
157
|
+
id: "com.example.commerce",
|
|
158
|
+
name: "Commerce",
|
|
159
|
+
version: "1.0"
|
|
160
|
+
});
|
|
161
|
+
|
|
162
|
+
// Add a provided capability
|
|
163
|
+
const orderCreate = commerce
|
|
164
|
+
.capability("order.create", 1)
|
|
165
|
+
.purpose("Create an order")
|
|
166
|
+
.input({ type: "object", properties: {} })
|
|
167
|
+
.output({ type: "object", properties: {} })
|
|
168
|
+
.build();
|
|
169
|
+
|
|
170
|
+
commerce.attach(orderCreate);
|
|
171
|
+
|
|
172
|
+
// Add requirements from other applications
|
|
173
|
+
const invoiceRequirement = commerce
|
|
174
|
+
.requirement("invoice.create", "^1")
|
|
175
|
+
.purpose("Create an invoice for a completed order")
|
|
176
|
+
.from("com.example.invoicing")
|
|
177
|
+
.build();
|
|
178
|
+
|
|
179
|
+
commerce.addRequirement(invoiceRequirement);
|
|
180
|
+
|
|
181
|
+
// Manage requirements
|
|
182
|
+
commerce.listRequiredCapabilities(); // List all required capabilities
|
|
183
|
+
commerce.getRequirement("invoice.create"); // Get by name
|
|
184
|
+
commerce.requiresCapability("invoice.create"); // Check if required
|
|
185
|
+
commerce.removeRequirement("invoice.create"); // Remove a requirement
|
|
186
|
+
```
|
|
187
|
+
|
|
188
|
+
### Requirement Builder API
|
|
189
|
+
|
|
190
|
+
- `.purpose(text: string)` - Set the purpose of the requirement
|
|
191
|
+
- `.from(applicationId: string)` - Constrain the provider to a specific application ID
|
|
192
|
+
- `.build()` - Build and return the requirement
|
|
193
|
+
|
|
194
|
+
### Contract Builder API (PR16 Extensions)
|
|
195
|
+
|
|
196
|
+
- `.requirement(name: string, versionConstraint: string)` - Create a requirement builder
|
|
197
|
+
- `.addRequirement(requirement: CapabilityRequirement)` - Add a required capability
|
|
198
|
+
- `.removeRequirement(name: string)` - Remove a requirement by name
|
|
199
|
+
- `.getRequirement(name: string)` - Retrieve a requirement by name
|
|
200
|
+
- `.listRequiredCapabilities()` - Get all required capabilities
|
|
201
|
+
- `.requiresCapability(name: string)` - Check if a capability is required
|
|
202
|
+
- `.provides(capabilityId: string)` - Check if a capability is provided
|
|
203
|
+
- `.hooks(hooks: ContractBuilderHooks)` - Register lifecycle hooks
|
|
204
|
+
|
|
205
|
+
### Version Constraints
|
|
206
|
+
|
|
207
|
+
Requirements support semantic version constraints:
|
|
208
|
+
|
|
209
|
+
- `^1` - Compatible with 1.x.x
|
|
210
|
+
- `~1.2` - Compatible with 1.2.x
|
|
211
|
+
- `>=1` - Version 1 or higher
|
|
212
|
+
- `>1` - Version higher than 1
|
|
213
|
+
- `<=2` - Version 2 or lower
|
|
214
|
+
- `<2` - Version lower than 2
|
|
215
|
+
- `1` - Exact version 1
|
|
216
|
+
|
|
217
|
+
### Compatibility Checking
|
|
218
|
+
|
|
219
|
+
Check if a provided capability satisfies a requirement:
|
|
220
|
+
|
|
221
|
+
```typescript
|
|
222
|
+
import { isCapabilityCompatible, satisfiesVersionConstraint } from "@appport/contract-builder";
|
|
223
|
+
|
|
224
|
+
// Check version constraint satisfaction
|
|
225
|
+
satisfiesVersionConstraint(1, "^1"); // true
|
|
226
|
+
satisfiesVersionConstraint(2, "^1"); // false
|
|
227
|
+
|
|
228
|
+
// Check full compatibility (name and version)
|
|
229
|
+
const requirement = { name: "invoice.create", versionConstraint: "^1" };
|
|
230
|
+
const capability = { name: "invoice.create", version: 1, input: {}, output: {} };
|
|
231
|
+
|
|
232
|
+
isCapabilityCompatible(requirement, capability); // true
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
### Key Distinctions
|
|
236
|
+
|
|
237
|
+
**Provides vs Requires**
|
|
238
|
+
|
|
239
|
+
- **Provides**: Capabilities owned by this application (declared via `.attach()`)
|
|
240
|
+
- **Requires**: Capabilities expected from other applications (declared via `.addRequirement()`)
|
|
241
|
+
|
|
242
|
+
**Discovery vs Compatibility vs Authorization**
|
|
243
|
+
|
|
244
|
+
PR16 establishes three distinct stages:
|
|
245
|
+
|
|
246
|
+
1. **Discovery** - Find available capabilities at runtime
|
|
247
|
+
2. **Compatibility** - Check version constraints and schema compatibility
|
|
248
|
+
3. **Authorization** - Verify permission to use the capability
|
|
249
|
+
|
|
250
|
+
These stages are independent. A capability can be discovered and compatible but still not authorized for use.
|
|
251
|
+
|
|
252
|
+
**No Compile-Time Coupling**
|
|
253
|
+
|
|
254
|
+
Requirements do not include implementation details:
|
|
255
|
+
- No SDK imports
|
|
256
|
+
- No provider URLs
|
|
257
|
+
- No provider code
|
|
258
|
+
- No transport details
|
|
259
|
+
|
|
260
|
+
The consumer contract describes a requirement. The runtime resolves the provider.
|
|
261
|
+
|
|
262
|
+
### Builder Hooks
|
|
263
|
+
|
|
264
|
+
Register hooks to be notified of contract authoring events:
|
|
265
|
+
|
|
266
|
+
```typescript
|
|
267
|
+
const contract = createContractBuilder({...});
|
|
268
|
+
|
|
269
|
+
contract.hooks({
|
|
270
|
+
onCapabilityAdded(capability) {
|
|
271
|
+
console.log(`Added capability: ${capability.name}`);
|
|
272
|
+
},
|
|
273
|
+
onCapabilityRequired(requirement) {
|
|
274
|
+
console.log(`Added requirement: ${requirement.name}`);
|
|
275
|
+
},
|
|
276
|
+
onCapabilityRequirementRemoved(name) {
|
|
277
|
+
console.log(`Removed requirement: ${name}`);
|
|
278
|
+
}
|
|
279
|
+
});
|
|
280
|
+
|
|
281
|
+
// Hooks are called when capabilities/requirements are added/removed
|
|
282
|
+
contract.attach(cap);
|
|
283
|
+
contract.addRequirement(req);
|
|
284
|
+
```
|
|
285
|
+
|
|
286
|
+
Available hooks:
|
|
287
|
+
- `onCapabilityAdded(capability)` - Called when a capability is attached
|
|
288
|
+
- `onCapabilityRemoved(capabilityId)` - Called when a capability is detached
|
|
289
|
+
- `onCapabilityChanged(old, new)` - Called when a capability is modified
|
|
290
|
+
- `onCapabilityRequired(requirement)` - Called when a requirement is added
|
|
291
|
+
- `onCapabilityRequirementRemoved(name)` - Called when a requirement is removed
|
|
292
|
+
- `onCapabilityRequirementChanged(old, new)` - Called when a requirement is modified
|
|
293
|
+
|
|
294
|
+
### Contract Diff with Requirements
|
|
295
|
+
|
|
296
|
+
The diff function now tracks requirement changes:
|
|
297
|
+
|
|
298
|
+
```typescript
|
|
299
|
+
import { diffContracts } from "@appport/contract-builder";
|
|
300
|
+
|
|
301
|
+
const diff = diffContracts(oldContract, newContract);
|
|
302
|
+
|
|
303
|
+
console.log(diff.capabilities); // Capability changes
|
|
304
|
+
console.log(diff.requirements); // Requirement changes
|
|
305
|
+
console.log(diff.events); // Event changes
|
|
306
|
+
console.log(diff.hasBreakingChanges); // true if any breaking changes
|
|
307
|
+
|
|
308
|
+
// Requirement changes include:
|
|
309
|
+
// { type: "added", name: "invoice.create", versionConstraint: "^1" }
|
|
310
|
+
// { type: "removed", name: "payment.authorize" }
|
|
311
|
+
// { type: "modified", name: "invoice.send", versionConstraint: "^2", breaking: true }
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
### Extracting Requirements from Contracts
|
|
315
|
+
|
|
316
|
+
Extract requirements for analysis:
|
|
317
|
+
|
|
318
|
+
```typescript
|
|
319
|
+
import { getContractRequirements } from "@appport/contract-builder";
|
|
320
|
+
|
|
321
|
+
const requirements = getContractRequirements(contract);
|
|
322
|
+
// Returns array of requirement objects with full details
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
## API
|
|
326
|
+
|
|
327
|
+
### `createContract(application: ContractApplication): Contract`
|
|
328
|
+
|
|
329
|
+
Create a new contract with sensible defaults. (Legacy API)
|
|
330
|
+
|
|
331
|
+
### `createContractBuilder(application: ContractApplication): ContractBuilder`
|
|
332
|
+
|
|
333
|
+
Create a new contract builder with the fluent API for constructing contracts programmatically.
|
|
334
|
+
|
|
335
|
+
### `capability(name: string, version: string | number): CapabilityBuilder`
|
|
336
|
+
|
|
337
|
+
Create a new capability builder for defining a single capability.
|
|
338
|
+
|
|
339
|
+
### `requirement(name: string, versionConstraint: string): RequirementBuilder`
|
|
340
|
+
|
|
341
|
+
Create a new requirement builder for defining a capability requirement.
|
|
342
|
+
|
|
343
|
+
### `validateContract(contract: Contract): ValidationResult`
|
|
344
|
+
|
|
345
|
+
Validate a contract. Returns validation issues and overall validity. Validates both provided capabilities and requirements.
|
|
346
|
+
|
|
347
|
+
### `diffContracts(from: Contract, to: Contract): ContractDiff`
|
|
348
|
+
|
|
349
|
+
Compare two contracts and produce a diff highlighting changes and breaking changes. Includes capability, event, and requirement changes.
|
|
350
|
+
|
|
351
|
+
### `isCapabilityCompatible(requirement: CapabilityRequirement, capability: ContractCapability): boolean`
|
|
352
|
+
|
|
353
|
+
Check if a provided capability can satisfy a requirement by verifying:
|
|
354
|
+
- Name matches
|
|
355
|
+
- Provided version satisfies version constraint
|
|
356
|
+
- Schemas exist
|
|
357
|
+
|
|
358
|
+
Returns true if compatible, false otherwise. Authorization is NOT checked here.
|
|
359
|
+
|
|
360
|
+
### `satisfiesVersionConstraint(providedVersion: number, constraint: string): boolean`
|
|
361
|
+
|
|
362
|
+
Check if a provided version number satisfies a semantic version constraint (e.g., "^1", "~1.2", ">=2").
|
|
363
|
+
|
|
364
|
+
### `getContractRequirements(contract: Contract): CapabilityRequirement[]`
|
|
365
|
+
|
|
366
|
+
Extract all required capabilities from a contract, useful for analyzing external dependencies.
|
|
367
|
+
|
|
368
|
+
### `contractToManifest(contract: Contract): AppPortManifest`
|
|
369
|
+
|
|
370
|
+
Convert a portable Contract to an AppPortManifest for use with client generation and other tools.
|
|
371
|
+
|
|
372
|
+
### `generateTypescriptServer(contract: Contract): GeneratedTypescriptServer`
|
|
373
|
+
|
|
374
|
+
Generate a complete TypeScript implementation skeleton from a contract, including:
|
|
375
|
+
- Configuration
|
|
376
|
+
- Capability definitions
|
|
377
|
+
- Event handlers
|
|
378
|
+
- Server and client setup
|
|
379
|
+
|
|
380
|
+
## Key Design Principles
|
|
381
|
+
|
|
382
|
+
1. **Contract-Native**: The contract is the canonical definition of capabilities and requirements
|
|
383
|
+
2. **Fluent API**: Build contracts programmatically with a natural, fluent interface
|
|
384
|
+
3. **Ownership**: Capabilities are explicitly attached to contracts, establishing ownership
|
|
385
|
+
4. **Identity**: Capabilities and requirements are uniquely identified by name@version
|
|
386
|
+
5. **Canonical Format**: The contract is the source of truth, not the implementation
|
|
387
|
+
6. **Portable**: Contracts can move between TypeScript, Python, Rust, etc.
|
|
388
|
+
7. **Validation**: Strong validation ensures contract correctness
|
|
389
|
+
8. **Generation**: Contracts can generate implementation skeletons
|
|
390
|
+
9. **Diffing**: Compare contracts to track changes and breaking changes
|
|
391
|
+
10. **Distinct Relationships**: Provides (ownership) and requires (participation) are separate concerns
|
|
392
|
+
11. **Version Constraints**: Requirements use semantic version constraints for dynamic composition
|
|
393
|
+
12. **No Compile-Time Coupling**: Applications can require capabilities without importing provider code
|
|
394
|
+
13. **Discovery ≠ Compatibility ≠ Authorization**: Three independent stages in capability resolution
|
|
395
|
+
14. **Lifecycle Hooks**: Contract authoring events trigger optional hooks for validation and logging
|
|
396
|
+
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
import type { ContractCapability, CapabilityRequirement } from "./contract.js";
|
|
2
|
+
/**
|
|
3
|
+
* Parse a semantic version constraint and check if a provided version satisfies it.
|
|
4
|
+
*
|
|
5
|
+
* Supports:
|
|
6
|
+
* - Exact: "1" (matches 1 only)
|
|
7
|
+
* - Caret: "^1" (matches 1.x.x)
|
|
8
|
+
* - Tilde: "~1.2" (matches 1.2.x)
|
|
9
|
+
* - Comparison: ">=1", ">1", "<=1", "<1"
|
|
10
|
+
*/
|
|
11
|
+
export declare function satisfiesVersionConstraint(providedVersion: number, constraint: string): boolean;
|
|
12
|
+
/**
|
|
13
|
+
* Check if a provided capability can satisfy a requirement.
|
|
14
|
+
*
|
|
15
|
+
* Verifies:
|
|
16
|
+
* - Capability name matches requirement name
|
|
17
|
+
* - Provided version satisfies version constraint
|
|
18
|
+
* - Input/output schemas are compatible
|
|
19
|
+
*
|
|
20
|
+
* Note: Authorization is NOT checked here. This is purely a schema/version compatibility check.
|
|
21
|
+
* Authorization is a separate, independent concern.
|
|
22
|
+
*/
|
|
23
|
+
export declare function isCapabilityCompatible(requirement: CapabilityRequirement, providedCapability: ContractCapability): boolean;
|
|
24
|
+
//# sourceMappingURL=compatibility.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"compatibility.d.ts","sourceRoot":"","sources":["../src/compatibility.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,qBAAqB,EAAE,MAAM,eAAe,CAAC;AAE/E;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CAAC,eAAe,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAqD/F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,WAAW,EAAE,qBAAqB,EAClC,kBAAkB,EAAE,kBAAkB,GACrC,OAAO,CAsBT"}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Parse a semantic version constraint and check if a provided version satisfies it.
|
|
3
|
+
*
|
|
4
|
+
* Supports:
|
|
5
|
+
* - Exact: "1" (matches 1 only)
|
|
6
|
+
* - Caret: "^1" (matches 1.x.x)
|
|
7
|
+
* - Tilde: "~1.2" (matches 1.2.x)
|
|
8
|
+
* - Comparison: ">=1", ">1", "<=1", "<1"
|
|
9
|
+
*/
|
|
10
|
+
export function satisfiesVersionConstraint(providedVersion, constraint) {
|
|
11
|
+
const trimmed = constraint.trim();
|
|
12
|
+
// Caret range: ^1.2.3 matches >= 1.2.3 and < 2.0.0
|
|
13
|
+
if (trimmed.startsWith("^")) {
|
|
14
|
+
const versionStr = trimmed.substring(1);
|
|
15
|
+
const [major] = versionStr.split(".").map(Number);
|
|
16
|
+
return providedVersion >= major && providedVersion < major + 1;
|
|
17
|
+
}
|
|
18
|
+
// Tilde range: ~1.2.3 matches >= 1.2.3 and < 1.3.0
|
|
19
|
+
if (trimmed.startsWith("~")) {
|
|
20
|
+
const versionStr = trimmed.substring(1);
|
|
21
|
+
const [major, minor] = versionStr.split(".").map(Number);
|
|
22
|
+
if (minor === undefined) {
|
|
23
|
+
// ~1 is equivalent to ^1
|
|
24
|
+
return providedVersion >= major && providedVersion < major + 1;
|
|
25
|
+
}
|
|
26
|
+
// For ~1.2, we only match 1.2.x since we're dealing with major version numbers
|
|
27
|
+
return providedVersion === major;
|
|
28
|
+
}
|
|
29
|
+
// Greater than or equal: >=1
|
|
30
|
+
if (trimmed.startsWith(">=")) {
|
|
31
|
+
const version = parseInt(trimmed.substring(2), 10);
|
|
32
|
+
return providedVersion >= version;
|
|
33
|
+
}
|
|
34
|
+
// Greater than: >1
|
|
35
|
+
if (trimmed.startsWith(">")) {
|
|
36
|
+
const version = parseInt(trimmed.substring(1), 10);
|
|
37
|
+
return providedVersion > version;
|
|
38
|
+
}
|
|
39
|
+
// Less than or equal: <=1
|
|
40
|
+
if (trimmed.startsWith("<=")) {
|
|
41
|
+
const version = parseInt(trimmed.substring(2), 10);
|
|
42
|
+
return providedVersion <= version;
|
|
43
|
+
}
|
|
44
|
+
// Less than: <1
|
|
45
|
+
if (trimmed.startsWith("<")) {
|
|
46
|
+
const version = parseInt(trimmed.substring(1), 10);
|
|
47
|
+
return providedVersion < version;
|
|
48
|
+
}
|
|
49
|
+
// Exact version: 1
|
|
50
|
+
const version = parseInt(trimmed, 10);
|
|
51
|
+
if (!Number.isNaN(version)) {
|
|
52
|
+
return providedVersion === version;
|
|
53
|
+
}
|
|
54
|
+
return false;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Check if a provided capability can satisfy a requirement.
|
|
58
|
+
*
|
|
59
|
+
* Verifies:
|
|
60
|
+
* - Capability name matches requirement name
|
|
61
|
+
* - Provided version satisfies version constraint
|
|
62
|
+
* - Input/output schemas are compatible
|
|
63
|
+
*
|
|
64
|
+
* Note: Authorization is NOT checked here. This is purely a schema/version compatibility check.
|
|
65
|
+
* Authorization is a separate, independent concern.
|
|
66
|
+
*/
|
|
67
|
+
export function isCapabilityCompatible(requirement, providedCapability) {
|
|
68
|
+
// Check name match
|
|
69
|
+
if (providedCapability.name !== requirement.name) {
|
|
70
|
+
return false;
|
|
71
|
+
}
|
|
72
|
+
// Check version constraint satisfaction
|
|
73
|
+
if (!satisfiesVersionConstraint(providedCapability.version, requirement.versionConstraint)) {
|
|
74
|
+
return false;
|
|
75
|
+
}
|
|
76
|
+
// Both must have schemas (already validated at contract level)
|
|
77
|
+
if (!providedCapability.input || !providedCapability.output) {
|
|
78
|
+
return false;
|
|
79
|
+
}
|
|
80
|
+
// Schema compatibility: schemas must be logically compatible
|
|
81
|
+
// For now, we do a simple check: both must exist
|
|
82
|
+
// More sophisticated schema validation would compare structure compatibility
|
|
83
|
+
// (e.g., provided output must be assignable to requirement's expected output)
|
|
84
|
+
return true;
|
|
85
|
+
}
|
|
86
|
+
//# sourceMappingURL=compatibility.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"compatibility.js","sourceRoot":"","sources":["../src/compatibility.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,MAAM,UAAU,0BAA0B,CAAC,eAAuB,EAAE,UAAkB;IACpF,MAAM,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,CAAC;IAElC,mDAAmD;IACnD,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QAClD,OAAO,eAAe,IAAI,KAAK,IAAI,eAAe,GAAG,KAAK,GAAG,CAAC,CAAC;IACjE,CAAC;IAED,mDAAmD;IACnD,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;QACzD,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,yBAAyB;YACzB,OAAO,eAAe,IAAI,KAAK,IAAI,eAAe,GAAG,KAAK,GAAG,CAAC,CAAC;QACjE,CAAC;QACD,+EAA+E;QAC/E,OAAO,eAAe,KAAK,KAAK,CAAC;IACnC,CAAC;IAED,6BAA6B;IAC7B,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnD,OAAO,eAAe,IAAI,OAAO,CAAC;IACpC,CAAC;IAED,mBAAmB;IACnB,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnD,OAAO,eAAe,GAAG,OAAO,CAAC;IACnC,CAAC;IAED,0BAA0B;IAC1B,IAAI,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAC7B,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnD,OAAO,eAAe,IAAI,OAAO,CAAC;IACpC,CAAC;IAED,gBAAgB;IAChB,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QACnD,OAAO,eAAe,GAAG,OAAO,CAAC;IACnC,CAAC;IAED,mBAAmB;IACnB,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAO,eAAe,KAAK,OAAO,CAAC;IACrC,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CACpC,WAAkC,EAClC,kBAAsC;IAEtC,mBAAmB;IACnB,IAAI,kBAAkB,CAAC,IAAI,KAAK,WAAW,CAAC,IAAI,EAAE,CAAC;QACjD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,wCAAwC;IACxC,IAAI,CAAC,0BAA0B,CAAC,kBAAkB,CAAC,OAAO,EAAE,WAAW,CAAC,iBAAiB,CAAC,EAAE,CAAC;QAC3F,OAAO,KAAK,CAAC;IACf,CAAC;IAED,+DAA+D;IAC/D,IAAI,CAAC,kBAAkB,CAAC,KAAK,IAAI,CAAC,kBAAkB,CAAC,MAAM,EAAE,CAAC;QAC5D,OAAO,KAAK,CAAC;IACf,CAAC;IAED,6DAA6D;IAC7D,iDAAiD;IACjD,6EAA6E;IAC7E,8EAA8E;IAE9E,OAAO,IAAI,CAAC;AACd,CAAC"}
|