The best way to control Claude Code, Codex and more from any computer or phone
Mirrored from https://github.com/Camo67/t3code.git
Synced Nov 21, 03:37 UTC
| 1 | /** |
| 2 | * Spec-Driven Service Audit Script |
| 3 | * |
| 4 | * This script analyzes a distilled AWS service spec and compares it against |
| 5 | * the alchemy implementation to identify gaps in bindings, resources, |
| 6 | * event sources, and helpers. |
| 7 | * |
| 8 | * Usage: |
| 9 | * node scripts/audit-service.ts dynamodb |
| 10 | * node scripts/audit-service.ts s3 |
| 11 | * node scripts/audit-service.ts --json dynamodb |
| 12 | */ |
| 13 | |
| 14 | import * as NodeRuntime from "@effect/platform-node/NodeRuntime"; |
| 15 | import * as NodeServices from "@effect/platform-node/NodeServices"; |
| 16 | import { Argument, Command, Flag } from "effect/cli"; |
| 17 | import * as Console from "effect/Console"; |
| 18 | import * as Data from "effect/Data"; |
| 19 | import * as Effect from "effect/Effect"; |
| 20 | import * as FileSystem from "effect/FileSystem"; |
| 21 | import * as Option from "effect/Option"; |
| 22 | import * as Path from "effect/Path"; |
| 23 | |
| 24 | class DistilledImportError extends Data.TaggedError("DistilledImportError")<{ |
| 25 | message: string; |
| 26 | cause: unknown; |
| 27 | }> {} |
| 28 | |
| 29 | /** Reads a file, or `undefined` if it is missing or unreadable. */ |
| 30 | const readOptional = Effect.fn(function* (file: string) { |
| 31 | const fs = yield* FileSystem.FileSystem; |
| 32 | return yield* fs.readFileString(file).pipe(Effect.option, Effect.map(Option.getOrUndefined)); |
| 33 | }); |
| 34 | |
| 35 | // ============ Types ============ |
| 36 | |
| 37 | interface Operation { |
| 38 | name: string; |
| 39 | camelCase: string; |
| 40 | pascalCase: string; |
| 41 | category: OperationCategory; |
| 42 | resourceArity: ResourceArity; |
| 43 | impliesResource: boolean; |
| 44 | impliesEventSource: boolean; |
| 45 | implemented: boolean; |
| 46 | registeredInProviders: boolean; |
| 47 | registeredInIndex: boolean; |
| 48 | } |
| 49 | |
| 50 | type OperationCategory = |
| 51 | | "binding" // Data-plane operation that becomes a Binding.Service |
| 52 | | "resource-lifecycle" // create/update/delete operations that imply a Resource |
| 53 | | "event-source" // stream/notification operations |
| 54 | | "helper-candidate" // operations that might become ergonomic helpers |
| 55 | | "internal"; // operations unlikely to be exposed directly |
| 56 | |
| 57 | type ResourceArity = |
| 58 | | 0 // account/service scoped (e.g., ListBuckets, DescribeLimits) |
| 59 | | 1 // single resource scoped (e.g., GetObject(Bucket), GetItem(Table)) |
| 60 | | 2 // fixed multi-resource (e.g., CopyObject(SourceBucket, DestBucket)) |
| 61 | | "n"; // variadic resource set (e.g., ExecuteTransaction(TableA, TableB, ...)) |
| 62 | |
| 63 | interface AuditReport { |
| 64 | service: string; |
| 65 | distilledPath: string; |
| 66 | alchemyPath: string; |
| 67 | bindingTestPath: string; |
| 68 | totalOperations: number; |
| 69 | implementedBindings: Operation[]; |
| 70 | missingBindings: Operation[]; |
| 71 | resourceLifecycleOps: Operation[]; |
| 72 | eventSourceOps: Operation[]; |
| 73 | helperCandidates: Operation[]; |
| 74 | internalOps: Operation[]; |
| 75 | canonicalResources: CanonicalResource[]; |
| 76 | suggestedHelpers: SuggestedHelper[]; |
| 77 | registrationGaps: RegistrationGap[]; |
| 78 | missingBindingTests: string[]; |
| 79 | leastPrivilegeWarnings: LeastPrivilegeWarning[]; |
| 80 | } |
| 81 | |
| 82 | interface CanonicalResource { |
| 83 | name: string; |
| 84 | impliedByOperations: string[]; |
| 85 | hasProvider: boolean; |
| 86 | suggestedBindings: string[]; |
| 87 | } |
| 88 | |
| 89 | interface SuggestedHelper { |
| 90 | name: string; |
| 91 | pattern: string; |
| 92 | basedOn: string[]; |
| 93 | existingExample: string | null; |
| 94 | } |
| 95 | |
| 96 | interface RegistrationGap { |
| 97 | type: "provider" | "index" | "policy"; |
| 98 | file: string; |
| 99 | missing: string[]; |
| 100 | } |
| 101 | |
| 102 | interface LeastPrivilegeWarning { |
| 103 | binding: string; |
| 104 | file: string; |
| 105 | resourceArity: ResourceArity; |
| 106 | message: string; |
| 107 | } |
| 108 | |
| 109 | // ============ Operation Classification Rules ============ |
| 110 | |
| 111 | // Resource lifecycle operations create/update/delete the resource ITSELF (Table, Bucket, Queue) |
| 112 | // NOT operations on items within a resource (deleteItem is a binding, deleteTable is lifecycle) |
| 113 | const RESOURCE_LIFECYCLE_PATTERNS = [ |
| 114 | /^createTable$/, |
| 115 | /^deleteTable$/, |
| 116 | /^updateTable$/, |
| 117 | /^createBucket$/, |
| 118 | /^deleteBucket$/, |
| 119 | /^createQueue$/, |
| 120 | /^deleteQueue$/, |
| 121 | /^createFunction$/, |
| 122 | /^deleteFunction$/, |
| 123 | /^updateFunctionCode$/, |
| 124 | /^updateFunctionConfiguration$/, |
| 125 | /^createStream$/, |
| 126 | /^deleteStream$/, |
| 127 | /^createPipe$/, |
| 128 | /^deletePipe$/, |
| 129 | /^updatePipe$/, |
| 130 | /^createTopic$/, |
| 131 | /^deleteTopic$/, |
| 132 | /^createSchedule$/, |
| 133 | /^deleteSchedule$/, |
| 134 | /^updateSchedule$/, |
| 135 | /^createScheduleGroup$/, |
| 136 | /^deleteScheduleGroup$/, |
| 137 | /^put[A-Z].*(?:Policy|Configuration|Settings)$/, |
| 138 | ]; |
| 139 | |
| 140 | const EVENT_SOURCE_PATTERNS = [ |
| 141 | /stream/i, |
| 142 | /kinesis/i, |
| 143 | /notification/i, |
| 144 | /subscription/i, |
| 145 | /^describe.*Stream/, |
| 146 | /^enable.*Stream/, |
| 147 | /^disable.*Stream/, |
| 148 | /StreamingDestination/i, |
| 149 | ]; |
| 150 | |
| 151 | // Operations that are both bindings AND helper candidates (will be classified as bindings first) |
| 152 | // These are data-plane operations that might benefit from higher-level wrappers |
| 153 | const HELPER_CANDIDATE_PATTERNS = [/^batch/i, /^transact/i, /^execute.*Statement/]; |
| 154 | |
| 155 | // Core data-plane bindings (these should always be classified as bindings) |
| 156 | const CORE_BINDING_PATTERNS = [ |
| 157 | /^get(?:Item|Object|Message|Record)$/i, |
| 158 | /^put(?:Item|Object|Record)$/i, |
| 159 | /^delete(?:Item|Object|Message)$/i, |
| 160 | /^update(?:Item)$/i, |
| 161 | /^query$/i, |
| 162 | /^scan$/i, |
| 163 | /^send(?:Message|Record)$/i, |
| 164 | /^receive(?:Message)$/i, |
| 165 | /^head(?:Object|Bucket)$/i, |
| 166 | /^list(?:Objects|ObjectsV2)$/i, |
| 167 | /^copy(?:Object)$/i, |
| 168 | /^upload(?:Part)$/i, |
| 169 | /^complete(?:MultipartUpload)$/i, |
| 170 | /^create(?:MultipartUpload)$/i, |
| 171 | /^abort(?:MultipartUpload)$/i, |
| 172 | ]; |
| 173 | |
| 174 | const INTERNAL_PATTERNS = [ |
| 175 | /^describe(?:Endpoints|Limits)$/, |
| 176 | /^list(?:Tags|Backups|Exports|Imports|GlobalTables|ContributorInsights)$/, |
| 177 | /^tag/i, |
| 178 | /^untag/i, |
| 179 | /Backup/i, |
| 180 | /Export/i, |
| 181 | /Import/i, |
| 182 | /GlobalTable(?!s$)/i, |
| 183 | /ReplicaAutoScaling/i, |
| 184 | /ContributorInsights/i, |
| 185 | /ResourcePolicy/i, |
| 186 | /ContinuousBackups/i, |
| 187 | ]; |
| 188 | |
| 189 | const ZERO_ARITY_PATTERNS = [ |
| 190 | /^list(?:Tables|Buckets|Queues|Functions|Streams)$/i, |
| 191 | /^describe(?:Endpoints|Limits|Account)$/i, |
| 192 | ]; |
| 193 | |
| 194 | const FIXED_MULTI_ARITY_PATTERNS = [/^copy/i, /^replicate/i, /^restore.*From/i]; |
| 195 | |
| 196 | const N_ARITY_PATTERNS = [ |
| 197 | /^batch/i, |
| 198 | /^transact/i, |
| 199 | /^execute.*Statement/i, |
| 200 | /^execute.*Transaction/i, |
| 201 | ]; |
| 202 | |
| 203 | // ============ Utilities ============ |
| 204 | |
| 205 | function toPascalCase(str: string): string { |
| 206 | return str.charAt(0).toUpperCase() + str.slice(1); |
| 207 | } |
| 208 | |
| 209 | function matchesAnyPattern(name: string, patterns: RegExp[]): boolean { |
| 210 | return patterns.some((p) => p.test(name)); |
| 211 | } |
| 212 | |
| 213 | function classifyOperation( |
| 214 | serviceName: string, |
| 215 | name: string, |
| 216 | ): { |
| 217 | category: OperationCategory; |
| 218 | resourceArity: ResourceArity; |
| 219 | impliesResource: boolean; |
| 220 | impliesEventSource: boolean; |
| 221 | } { |
| 222 | if (serviceName === "iam") { |
| 223 | const lifecycleIamOps = new Set([ |
| 224 | "createAccessKey", |
| 225 | "deleteAccessKey", |
| 226 | "updateAccessKey", |
| 227 | "createAccountAlias", |
| 228 | "deleteAccountAlias", |
| 229 | "updateAccountPasswordPolicy", |
| 230 | "deleteAccountPasswordPolicy", |
| 231 | "createGroup", |
| 232 | "deleteGroup", |
| 233 | "updateGroup", |
| 234 | "createInstanceProfile", |
| 235 | "deleteInstanceProfile", |
| 236 | "createLoginProfile", |
| 237 | "deleteLoginProfile", |
| 238 | "updateLoginProfile", |
| 239 | "createOpenIDConnectProvider", |
| 240 | "deleteOpenIDConnectProvider", |
| 241 | "createPolicy", |
| 242 | "deletePolicy", |
| 243 | "createRole", |
| 244 | "deleteRole", |
| 245 | "updateRole", |
| 246 | "createSAMLProvider", |
| 247 | "deleteSAMLProvider", |
| 248 | "updateSAMLProvider", |
| 249 | "deleteServerCertificate", |
| 250 | "updateServerCertificate", |
| 251 | "createServiceSpecificCredential", |
| 252 | "deleteServiceSpecificCredential", |
| 253 | "updateServiceSpecificCredential", |
| 254 | "deleteSigningCertificate", |
| 255 | "updateSigningCertificate", |
| 256 | "deleteSSHPublicKey", |
| 257 | "updateSSHPublicKey", |
| 258 | "createUser", |
| 259 | "deleteUser", |
| 260 | "updateUser", |
| 261 | "createVirtualMFADevice", |
| 262 | "deleteVirtualMFADevice", |
| 263 | ]); |
| 264 | |
| 265 | if (lifecycleIamOps.has(name)) { |
| 266 | return { |
| 267 | category: "resource-lifecycle", |
| 268 | resourceArity: |
| 269 | name === "updateAccountPasswordPolicy" || name === "deleteAccountPasswordPolicy" ? 0 : 1, |
| 270 | impliesResource: true, |
| 271 | impliesEventSource: false, |
| 272 | }; |
| 273 | } |
| 274 | |
| 275 | return { |
| 276 | category: "internal", |
| 277 | resourceArity: matchesAnyPattern(name, ZERO_ARITY_PATTERNS) ? 0 : 1, |
| 278 | impliesResource: false, |
| 279 | impliesEventSource: false, |
| 280 | }; |
| 281 | } |
| 282 | |
| 283 | if (serviceName === "sns") { |
| 284 | if (name === "createTopic" || name === "deleteTopic") { |
| 285 | return { |
| 286 | category: "resource-lifecycle", |
| 287 | resourceArity: 1, |
| 288 | impliesResource: true, |
| 289 | impliesEventSource: false, |
| 290 | }; |
| 291 | } |
| 292 | |
| 293 | if (name === "subscribe" || name === "unsubscribe") { |
| 294 | return { |
| 295 | category: "resource-lifecycle", |
| 296 | resourceArity: 1, |
| 297 | impliesResource: true, |
| 298 | impliesEventSource: true, |
| 299 | }; |
| 300 | } |
| 301 | } |
| 302 | |
| 303 | if (serviceName === "kinesis") { |
| 304 | if (name === "registerStreamConsumer" || name === "deregisterStreamConsumer") { |
| 305 | return { |
| 306 | category: "resource-lifecycle", |
| 307 | resourceArity: 1, |
| 308 | impliesResource: true, |
| 309 | impliesEventSource: false, |
| 310 | }; |
| 311 | } |
| 312 | |
| 313 | if ( |
| 314 | [ |
| 315 | "addTagsToStream", |
| 316 | "decreaseStreamRetentionPeriod", |
| 317 | "deleteResourcePolicy", |
| 318 | "disableEnhancedMonitoring", |
| 319 | "enableEnhancedMonitoring", |
| 320 | "increaseStreamRetentionPeriod", |
| 321 | "mergeShards", |
| 322 | "putResourcePolicy", |
| 323 | "removeTagsFromStream", |
| 324 | "splitShard", |
| 325 | "startStreamEncryption", |
| 326 | "stopStreamEncryption", |
| 327 | "tagResource", |
| 328 | "untagResource", |
| 329 | "updateMaxRecordSize", |
| 330 | "updateShardCount", |
| 331 | "updateStreamMode", |
| 332 | "updateStreamWarmThroughput", |
| 333 | ].includes(name) |
| 334 | ) { |
| 335 | return { |
| 336 | category: "resource-lifecycle", |
| 337 | resourceArity: 1, |
| 338 | impliesResource: true, |
| 339 | impliesEventSource: false, |
| 340 | }; |
| 341 | } |
| 342 | |
| 343 | if ( |
| 344 | [ |
| 345 | "describeAccountSettings", |
| 346 | "describeLimits", |
| 347 | "describeStream", |
| 348 | "describeStreamConsumer", |
| 349 | "describeStreamSummary", |
| 350 | "getRecords", |
| 351 | "getResourcePolicy", |
| 352 | "getShardIterator", |
| 353 | "listShards", |
| 354 | "listStreamConsumers", |
| 355 | "listStreams", |
| 356 | "listTagsForResource", |
| 357 | "putRecord", |
| 358 | "putRecords", |
| 359 | "subscribeToShard", |
| 360 | ].includes(name) |
| 361 | ) { |
| 362 | return { |
| 363 | category: "binding", |
| 364 | resourceArity: matchesAnyPattern(name, ZERO_ARITY_PATTERNS) ? 0 : 1, |
| 365 | impliesResource: false, |
| 366 | impliesEventSource: false, |
| 367 | }; |
| 368 | } |
| 369 | |
| 370 | if (name === "listTagsForStream" || name === "updateAccountSettings") { |
| 371 | return { |
| 372 | category: "internal", |
| 373 | resourceArity: 1, |
| 374 | impliesResource: false, |
| 375 | impliesEventSource: false, |
| 376 | }; |
| 377 | } |
| 378 | } |
| 379 | |
| 380 | if (serviceName === "rds-data") { |
| 381 | return { |
| 382 | category: "binding", |
| 383 | resourceArity: 1, |
| 384 | impliesResource: false, |
| 385 | impliesEventSource: false, |
| 386 | }; |
| 387 | } |
| 388 | |
| 389 | if (serviceName === "secrets-manager") { |
| 390 | if (["createSecret", "deleteSecret", "updateSecret"].includes(name)) { |
| 391 | return { |
| 392 | category: "resource-lifecycle", |
| 393 | resourceArity: 1, |
| 394 | impliesResource: true, |
| 395 | impliesEventSource: false, |
| 396 | }; |
| 397 | } |
| 398 | |
| 399 | if (name === "listSecrets" || name === "getRandomPassword") { |
| 400 | return { |
| 401 | category: "binding", |
| 402 | resourceArity: 0, |
| 403 | impliesResource: false, |
| 404 | impliesEventSource: false, |
| 405 | }; |
| 406 | } |
| 407 | |
| 408 | if ( |
| 409 | [ |
| 410 | "getSecretValue", |
| 411 | "putSecretValue", |
| 412 | "describeSecret", |
| 413 | "listSecretVersionIds", |
| 414 | "getResourcePolicy", |
| 415 | "putResourcePolicy", |
| 416 | "deleteResourcePolicy", |
| 417 | "updateSecretVersionStage", |
| 418 | "validateResourcePolicy", |
| 419 | ].includes(name) |
| 420 | ) { |
| 421 | return { |
| 422 | category: "binding", |
| 423 | resourceArity: 1, |
| 424 | impliesResource: false, |
| 425 | impliesEventSource: false, |
| 426 | }; |
| 427 | } |
| 428 | } |
| 429 | |
| 430 | if (serviceName === "rds") { |
| 431 | if ( |
| 432 | [ |
| 433 | "createDBCluster", |
| 434 | "deleteDBCluster", |
| 435 | "modifyDBCluster", |
| 436 | "enableHttpEndpoint", |
| 437 | "disableHttpEndpoint", |
| 438 | "startDBCluster", |
| 439 | "stopDBCluster", |
| 440 | "rebootDBCluster", |
| 441 | "createDBClusterEndpoint", |
| 442 | "deleteDBClusterEndpoint", |
| 443 | "modifyDBClusterEndpoint", |
| 444 | "createDBClusterParameterGroup", |
| 445 | "deleteDBClusterParameterGroup", |
| 446 | "modifyDBClusterParameterGroup", |
| 447 | "createDBInstance", |
| 448 | "deleteDBInstance", |
| 449 | "modifyDBInstance", |
| 450 | "createDBParameterGroup", |
| 451 | "deleteDBParameterGroup", |
| 452 | "modifyDBParameterGroup", |
| 453 | "createDBProxy", |
| 454 | "deleteDBProxy", |
| 455 | "modifyDBProxy", |
| 456 | "createDBProxyEndpoint", |
| 457 | "deleteDBProxyEndpoint", |
| 458 | "modifyDBProxyEndpoint", |
| 459 | "modifyDBProxyTargetGroup", |
| 460 | "registerDBProxyTargets", |
| 461 | "deregisterDBProxyTargets", |
| 462 | "createDBSubnetGroup", |
| 463 | "deleteDBSubnetGroup", |
| 464 | "modifyDBSubnetGroup", |
| 465 | "createGlobalCluster", |
| 466 | "deleteGlobalCluster", |
| 467 | "modifyGlobalCluster", |
| 468 | ].includes(name) |
| 469 | ) { |
| 470 | return { |
| 471 | category: "resource-lifecycle", |
| 472 | resourceArity: 1, |
| 473 | impliesResource: true, |
| 474 | impliesEventSource: false, |
| 475 | }; |
| 476 | } |
| 477 | |
| 478 | if ( |
| 479 | [ |
| 480 | "describeDBClusters", |
| 481 | "describeDBInstances", |
| 482 | "describeDBSubnetGroups", |
| 483 | "describeDBClusterParameterGroups", |
| 484 | "describeDBParameterGroups", |
| 485 | "describeDBProxies", |
| 486 | "describeDBProxyEndpoints", |
| 487 | "describeDBProxyTargetGroups", |
| 488 | "describeDBProxyTargets", |
| 489 | "listTagsForResource", |
| 490 | ].includes(name) |
| 491 | ) { |
| 492 | return { |
| 493 | category: "binding", |
| 494 | resourceArity: 1, |
| 495 | impliesResource: false, |
| 496 | impliesEventSource: false, |
| 497 | }; |
| 498 | } |
| 499 | } |
| 500 | |
| 501 | if (serviceName === "eventbridge") { |
| 502 | if ( |
| 503 | [ |
| 504 | "createEventBus", |
| 505 | "deleteEventBus", |
| 506 | "updateEventBus", |
| 507 | "putRule", |
| 508 | "deleteRule", |
| 509 | "putPermission", |
| 510 | "removePermission", |
| 511 | ].includes(name) |
| 512 | ) { |
| 513 | return { |
| 514 | category: "resource-lifecycle", |
| 515 | resourceArity: name === "putPermission" || name === "removePermission" ? 1 : 1, |
| 516 | impliesResource: true, |
| 517 | impliesEventSource: name === "putRule" || name === "deleteRule", |
| 518 | }; |
| 519 | } |
| 520 | |
| 521 | if ( |
| 522 | [ |
| 523 | "describeEventBus", |
| 524 | "listEventBuses", |
| 525 | "describeRule", |
| 526 | "listRules", |
| 527 | "listTargetsByRule", |
| 528 | "listRuleNamesByTarget", |
| 529 | "putEvents", |
| 530 | "testEventPattern", |
| 531 | ].includes(name) |
| 532 | ) { |
| 533 | return { |
| 534 | category: "binding", |
| 535 | resourceArity: name === "listEventBuses" || name === "testEventPattern" ? 0 : 1, |
| 536 | impliesResource: false, |
| 537 | impliesEventSource: false, |
| 538 | }; |
| 539 | } |
| 540 | } |
| 541 | |
| 542 | if (serviceName === "pipes") { |
| 543 | if ( |
| 544 | ["createPipe", "describePipe", "updatePipe", "deletePipe", "startPipe", "stopPipe"].includes( |
| 545 | name, |
| 546 | ) |
| 547 | ) { |
| 548 | return { |
| 549 | category: "resource-lifecycle", |
| 550 | resourceArity: 1, |
| 551 | impliesResource: true, |
| 552 | impliesEventSource: true, |
| 553 | }; |
| 554 | } |
| 555 | |
| 556 | if (["listPipes", "listTagsForResource"].includes(name)) { |
| 557 | return { |
| 558 | category: "binding", |
| 559 | resourceArity: name === "listPipes" ? 0 : 1, |
| 560 | impliesResource: false, |
| 561 | impliesEventSource: false, |
| 562 | }; |
| 563 | } |
| 564 | } |
| 565 | |
| 566 | if (serviceName === "scheduler") { |
| 567 | if ( |
| 568 | [ |
| 569 | "createSchedule", |
| 570 | "getSchedule", |
| 571 | "updateSchedule", |
| 572 | "deleteSchedule", |
| 573 | "createScheduleGroup", |
| 574 | "getScheduleGroup", |
| 575 | "deleteScheduleGroup", |
| 576 | ].includes(name) |
| 577 | ) { |
| 578 | return { |
| 579 | category: "resource-lifecycle", |
| 580 | resourceArity: 1, |
| 581 | impliesResource: true, |
| 582 | impliesEventSource: true, |
| 583 | }; |
| 584 | } |
| 585 | |
| 586 | if (["listSchedules", "listScheduleGroups", "listTagsForResource"].includes(name)) { |
| 587 | return { |
| 588 | category: "binding", |
| 589 | resourceArity: name === "listTagsForResource" ? 1 : 0, |
| 590 | impliesResource: false, |
| 591 | impliesEventSource: false, |
| 592 | }; |
| 593 | } |
| 594 | } |
| 595 | |
| 596 | const impliesEventSource = matchesAnyPattern(name, EVENT_SOURCE_PATTERNS); |
| 597 | const impliesResource = matchesAnyPattern(name, RESOURCE_LIFECYCLE_PATTERNS); |
| 598 | const isCoreBinding = matchesAnyPattern(name, CORE_BINDING_PATTERNS); |
| 599 | |
| 600 | let category: OperationCategory; |
| 601 | if (matchesAnyPattern(name, INTERNAL_PATTERNS)) { |
| 602 | category = "internal"; |
| 603 | } else if (isCoreBinding) { |
| 604 | // Core bindings take priority - these are the main data-plane operations |
| 605 | category = "binding"; |
| 606 | } else if (impliesResource) { |
| 607 | category = "resource-lifecycle"; |
| 608 | } else if (impliesEventSource) { |
| 609 | category = "event-source"; |
| 610 | } else if (matchesAnyPattern(name, HELPER_CANDIDATE_PATTERNS)) { |
| 611 | category = "helper-candidate"; |
| 612 | } else { |
| 613 | category = "binding"; |
| 614 | } |
| 615 | |
| 616 | let resourceArity: ResourceArity; |
| 617 | if (matchesAnyPattern(name, ZERO_ARITY_PATTERNS)) { |
| 618 | resourceArity = 0; |
| 619 | } else if (matchesAnyPattern(name, N_ARITY_PATTERNS)) { |
| 620 | resourceArity = "n"; |
| 621 | } else if (matchesAnyPattern(name, FIXED_MULTI_ARITY_PATTERNS)) { |
| 622 | resourceArity = 2; |
| 623 | } else { |
| 624 | resourceArity = 1; |
| 625 | } |
| 626 | |
| 627 | return { category, resourceArity, impliesResource, impliesEventSource }; |
| 628 | } |
| 629 | |
| 630 | const inferImplementedResourceArity = Effect.fn(function* ( |
| 631 | alchemyPath: string, |
| 632 | pascalCase: string, |
| 633 | fallback: ResourceArity, |
| 634 | ) { |
| 635 | const path = yield* Path.Path; |
| 636 | const content = yield* readOptional(path.join(alchemyPath, `${pascalCase}.ts`)); |
| 637 | // Fall back to heuristic classification when the file is unreadable. |
| 638 | return content === undefined ? fallback : implementedResourceArity(content, fallback); |
| 639 | }); |
| 640 | |
| 641 | function implementedResourceArity(content: string, fallback: ResourceArity): ResourceArity { |
| 642 | const serviceSignatureMatch = content.match( |
| 643 | /Binding\.Service<[\s\S]*?,\s*(\([\s\S]*?\)\s*=>\s*Effect\.Effect<)/, |
| 644 | ); |
| 645 | |
| 646 | if (!serviceSignatureMatch) { |
| 647 | return fallback; |
| 648 | } |
| 649 | |
| 650 | const signature = serviceSignatureMatch[1]; |
| 651 | |
| 652 | if (/\(\s*\)\s*=>\s*Effect\.Effect</.test(signature)) { |
| 653 | return 0; |
| 654 | } |
| 655 | |
| 656 | if (/\(\s*\.\.\.[^)]+\)\s*=>\s*Effect\.Effect</.test(signature)) { |
| 657 | return "n"; |
| 658 | } |
| 659 | |
| 660 | if (/\([^)]*,[^)]*\)\s*=>\s*Effect\.Effect</.test(signature)) { |
| 661 | return 2; |
| 662 | } |
| 663 | |
| 664 | if (/\([^)]*\)\s*=>\s*Effect\.Effect</.test(signature)) { |
| 665 | return 1; |
| 666 | } |
| 667 | |
| 668 | return fallback; |
| 669 | } |
| 670 | |
| 671 | function formatArity(arity: ResourceArity): string { |
| 672 | return `arity=${arity}`; |
| 673 | } |
| 674 | |
| 675 | // ============ File Parsing ============ |
| 676 | |
| 677 | const extractDistilledOperations = Effect.fn(function* ( |
| 678 | distilledPath: string, |
| 679 | moduleSpecifier?: string, |
| 680 | ) { |
| 681 | const content = yield* readOptional(distilledPath); |
| 682 | if (content !== undefined) { |
| 683 | const operations: string[] = []; |
| 684 | const regex = /^export const ([a-z][a-zA-Z0-9]*): API\.OperationMethod</gm; |
| 685 | |
| 686 | let match; |
| 687 | while ((match = regex.exec(content)) !== null) { |
| 688 | operations.push(match[1]); |
| 689 | } |
| 690 | |
| 691 | return operations; |
| 692 | } |
| 693 | if (!moduleSpecifier) { |
| 694 | return yield* Effect.fail(new Error(`Could not read distilled spec: ${distilledPath}`)); |
| 695 | } |
| 696 | |
| 697 | const mod: Record<string, unknown> = yield* Effect.tryPromise({ |
| 698 | try: () => import(moduleSpecifier), |
| 699 | catch: (cause) => |
| 700 | new DistilledImportError({ |
| 701 | message: `Could not import distilled spec: ${moduleSpecifier}`, |
| 702 | cause, |
| 703 | }), |
| 704 | }); |
| 705 | return Object.keys(mod) |
| 706 | .filter((key) => /^[a-z]/.test(key)) |
| 707 | .sort(); |
| 708 | }); |
| 709 | |
| 710 | const getAlchemyFiles = Effect.fn(function* (alchemyPath: string) { |
| 711 | const fs = yield* FileSystem.FileSystem; |
| 712 | const files = new Set<string>(); |
| 713 | // A missing directory has no files. |
| 714 | const entries = yield* fs.readDirectory(alchemyPath).pipe(Effect.orElseSucceed(() => [])); |
| 715 | for (const entry of entries) { |
| 716 | if (entry.endsWith(".ts") && entry !== "index.ts") { |
| 717 | files.add(entry.replace(".ts", "")); |
| 718 | } |
| 719 | } |
| 720 | return files; |
| 721 | }); |
| 722 | |
| 723 | const getIndexExports = Effect.fn(function* (indexPath: string) { |
| 724 | const exports = new Set<string>(); |
| 725 | const content = yield* readOptional(indexPath); |
| 726 | if (content !== undefined) { |
| 727 | const regex = /export \* from ["']\.\/([^"']+)["']/g; |
| 728 | let match; |
| 729 | while ((match = regex.exec(content)) !== null) { |
| 730 | const name = match[1].replace(".ts", "").replace(".js", ""); |
| 731 | exports.add(name); |
| 732 | } |
| 733 | } |
| 734 | return exports; |
| 735 | }); |
| 736 | |
| 737 | const getProvidersRegistrations = Effect.fn(function* (providersPath: string, service: string) { |
| 738 | const resources = new Set<string>(); |
| 739 | const bindings = new Set<string>(); |
| 740 | |
| 741 | const content = yield* readOptional(providersPath); |
| 742 | if (content !== undefined) { |
| 743 | // Match DynamoDB.TableProvider(), S3.BucketProvider(), etc. |
| 744 | const resourceRegex = new RegExp(`${service}\\.([A-Z][a-zA-Z0-9]+)Provider\\(\\)`, "g"); |
| 745 | let match; |
| 746 | while ((match = resourceRegex.exec(content)) !== null) { |
| 747 | resources.add(match[1]); |
| 748 | } |
| 749 | |
| 750 | // Match DynamoDB.GetItemPolicyLive, S3.GetObjectPolicyLive, etc. |
| 751 | // Note: The binding name is like "GetItem" and the export is "GetItemPolicyLive" |
| 752 | const bindingRegex = new RegExp(`${service}\\.([A-Z][a-zA-Z0-9]+)PolicyLive`, "g"); |
| 753 | while ((match = bindingRegex.exec(content)) !== null) { |
| 754 | bindings.add(match[1]); |
| 755 | } |
| 756 | } |
| 757 | |
| 758 | return { resources, bindings }; |
| 759 | }); |
| 760 | |
| 761 | const getBindingTestDescribes = Effect.fn(function* (bindingTestPath: string) { |
| 762 | const describes = new Set<string>(); |
| 763 | |
| 764 | const content = yield* readOptional(bindingTestPath); |
| 765 | if (content === undefined) { |
| 766 | return { exists: false, describes }; |
| 767 | } |
| 768 | const regex = /describe\(\s*["']([A-Z][A-Za-z0-9]+)["']/g; |
| 769 | |
| 770 | let match; |
| 771 | while ((match = regex.exec(content)) !== null) { |
| 772 | describes.add(match[1]); |
| 773 | } |
| 774 | |
| 775 | return { exists: true, describes }; |
| 776 | }); |
| 777 | |
| 778 | const getLeastPrivilegeWarnings = Effect.fn(function* ( |
| 779 | alchemyPath: string, |
| 780 | operations: Operation[], |
| 781 | ) { |
| 782 | const path = yield* Path.Path; |
| 783 | const warnings: LeastPrivilegeWarning[] = []; |
| 784 | const wildcardResourcePattern = /Resource:\s*\[\s*["']\*["']\s*\]/; |
| 785 | |
| 786 | for (const op of operations) { |
| 787 | if (!op.implemented || op.resourceArity === 0) { |
| 788 | continue; |
| 789 | } |
| 790 | |
| 791 | if ( |
| 792 | op.category !== "binding" && |
| 793 | op.category !== "helper-candidate" && |
| 794 | op.category !== "event-source" |
| 795 | ) { |
| 796 | continue; |
| 797 | } |
| 798 | |
| 799 | const file = path.join(alchemyPath, `${op.pascalCase}.ts`); |
| 800 | // Missing or unreadable files are surfaced by other audit checks. |
| 801 | const content = yield* readOptional(file); |
| 802 | if (content !== undefined && wildcardResourcePattern.test(content)) { |
| 803 | warnings.push({ |
| 804 | binding: op.pascalCase, |
| 805 | file, |
| 806 | resourceArity: op.resourceArity, |
| 807 | message: |
| 808 | 'Resource-bound binding uses `Resource: ["*"]`; bind the canonical resource(s) explicitly so the policy stays least-privilege.', |
| 809 | }); |
| 810 | } |
| 811 | } |
| 812 | |
| 813 | return warnings.sort((a, b) => a.binding.localeCompare(b.binding)); |
| 814 | }); |
| 815 | |
| 816 | // ============ Resource Inference ============ |
| 817 | |
| 818 | function inferCanonicalResources( |
| 819 | operations: Operation[], |
| 820 | existingFiles: Set<string>, |
| 821 | ): CanonicalResource[] { |
| 822 | const resourceMap = new Map<string, { operations: string[]; bindings: string[] }>(); |
| 823 | |
| 824 | for (const op of operations) { |
| 825 | if (op.category === "resource-lifecycle") { |
| 826 | let resourceName: string | undefined; |
| 827 | |
| 828 | if (["registerStreamConsumer", "deregisterStreamConsumer"].includes(op.camelCase)) { |
| 829 | resourceName = "StreamConsumer"; |
| 830 | } else if (["putRule", "deleteRule"].includes(op.camelCase)) { |
| 831 | resourceName = "Rule"; |
| 832 | } else if (["putPermission", "removePermission"].includes(op.camelCase)) { |
| 833 | resourceName = "Permission"; |
| 834 | } else if ( |
| 835 | [ |
| 836 | "addTagsToStream", |
| 837 | "createStream", |
| 838 | "decreaseStreamRetentionPeriod", |
| 839 | "deleteResourcePolicy", |
| 840 | "deleteStream", |
| 841 | "disableEnhancedMonitoring", |
| 842 | "enableEnhancedMonitoring", |
| 843 | "increaseStreamRetentionPeriod", |
| 844 | "mergeShards", |
| 845 | "putResourcePolicy", |
| 846 | "removeTagsFromStream", |
| 847 | "splitShard", |
| 848 | "startStreamEncryption", |
| 849 | "stopStreamEncryption", |
| 850 | "tagResource", |
| 851 | "untagResource", |
| 852 | "updateMaxRecordSize", |
| 853 | "updateShardCount", |
| 854 | "updateStreamMode", |
| 855 | "updateStreamWarmThroughput", |
| 856 | ].includes(op.camelCase) |
| 857 | ) { |
| 858 | resourceName = "Stream"; |
| 859 | } |
| 860 | |
| 861 | // Extract resource name from operation like createTable -> Table |
| 862 | const match = |
| 863 | resourceName === undefined |
| 864 | ? op.camelCase.match(/^(create|delete|update|describe)([A-Z][a-zA-Z]+)/) |
| 865 | : undefined; |
| 866 | if (resourceName || match) { |
| 867 | const resolvedResourceName = resourceName ?? match![2]; |
| 868 | if (!resourceMap.has(resolvedResourceName)) { |
| 869 | resourceMap.set(resolvedResourceName, { |
| 870 | operations: [], |
| 871 | bindings: [], |
| 872 | }); |
| 873 | } |
| 874 | resourceMap.get(resolvedResourceName)!.operations.push(op.camelCase); |
| 875 | } |
| 876 | } else if (op.category === "binding" && op.resourceArity === 1) { |
| 877 | // Associate binding with likely resource |
| 878 | // e.g., getItem, putItem, deleteItem -> Table (DynamoDB convention) |
| 879 | // This is heuristic and service-specific |
| 880 | const commonResources = ["Table", "Bucket", "Queue", "Stream", "Function"]; |
| 881 | for (const res of commonResources) { |
| 882 | if (!resourceMap.has(res)) { |
| 883 | resourceMap.set(res, { operations: [], bindings: [] }); |
| 884 | } |
| 885 | resourceMap.get(res)!.bindings.push(op.pascalCase); |
| 886 | } |
| 887 | } |
| 888 | } |
| 889 | |
| 890 | const results: CanonicalResource[] = []; |
| 891 | for (const [name, data] of resourceMap) { |
| 892 | if (data.operations.length > 0) { |
| 893 | results.push({ |
| 894 | name, |
| 895 | impliedByOperations: data.operations, |
| 896 | hasProvider: existingFiles.has(name), |
| 897 | suggestedBindings: data.bindings.slice(0, 10), // Limit for readability |
| 898 | }); |
| 899 | } |
| 900 | } |
| 901 | |
| 902 | return results.sort((a, b) => a.name.localeCompare(b.name)); |
| 903 | } |
| 904 | |
| 905 | // ============ Helper Suggestions ============ |
| 906 | |
| 907 | function suggestHelpers(operations: Operation[], service: string): SuggestedHelper[] { |
| 908 | const suggestions: SuggestedHelper[] = []; |
| 909 | |
| 910 | // Pattern: Stream-based helpers like notifications(bucket), messages(queue), changes(table) |
| 911 | const streamOps = operations.filter((op) => op.impliesEventSource); |
| 912 | if (streamOps.length > 0) { |
| 913 | const helperName = |
| 914 | service.toLowerCase() === "dynamodb" |
| 915 | ? "changes" |
| 916 | : service.toLowerCase() === "sqs" |
| 917 | ? "messages" |
| 918 | : service.toLowerCase() === "s3" |
| 919 | ? "notifications" |
| 920 | : "events"; |
| 921 | |
| 922 | suggestions.push({ |
| 923 | name: `${helperName}(resource)`, |
| 924 | pattern: "Event stream subscription helper", |
| 925 | basedOn: streamOps.map((op) => op.camelCase), |
| 926 | existingExample: |
| 927 | service.toLowerCase() === "s3" |
| 928 | ? "aws/src/S3/BucketNotifications.ts" |
| 929 | : service.toLowerCase() === "sqs" |
| 930 | ? "aws/src/SQS/QueueEventSource.ts" |
| 931 | : null, |
| 932 | }); |
| 933 | } |
| 934 | |
| 935 | // Pattern: Batch operations -> typed batch helpers |
| 936 | const batchOps = operations.filter( |
| 937 | (op) => op.camelCase.startsWith("batch") || op.camelCase.startsWith("transact"), |
| 938 | ); |
| 939 | if (batchOps.length > 0) { |
| 940 | suggestions.push({ |
| 941 | name: "batch operations", |
| 942 | pattern: "Typed batch/transaction wrappers", |
| 943 | basedOn: batchOps.map((op) => op.camelCase), |
| 944 | existingExample: null, |
| 945 | }); |
| 946 | } |
| 947 | |
| 948 | return suggestions; |
| 949 | } |
| 950 | |
| 951 | // ============ Main Audit Logic ============ |
| 952 | |
| 953 | const auditService = Effect.fn(function* (serviceName: string) { |
| 954 | const fs = yield* FileSystem.FileSystem; |
| 955 | const path = yield* Path.Path; |
| 956 | const root = path.resolve(import.meta.dirname, ".."); |
| 957 | const serviceNameLower = serviceName.toLowerCase(); |
| 958 | const serviceNameUpper = serviceName.charAt(0).toUpperCase() + serviceName.slice(1); |
| 959 | |
| 960 | // Map common service names to their distilled paths and alchemy paths |
| 961 | const serviceConfig: Record<string, { distilled: string; alchemy: string }> = { |
| 962 | dynamodb: { distilled: "dynamodb", alchemy: "DynamoDB" }, |
| 963 | s3: { distilled: "s3", alchemy: "S3" }, |
| 964 | sqs: { distilled: "sqs", alchemy: "SQS" }, |
| 965 | lambda: { distilled: "lambda", alchemy: "Lambda" }, |
| 966 | kinesis: { distilled: "kinesis", alchemy: "Kinesis" }, |
| 967 | ec2: { distilled: "ec2", alchemy: "EC2" }, |
| 968 | ecs: { distilled: "ecs", alchemy: "ECS" }, |
| 969 | cloudfront: { distilled: "cloudfront", alchemy: "CloudFront" }, |
| 970 | cloudwatch: { distilled: "cloudwatch", alchemy: "CloudWatch" }, |
| 971 | eventbridge: { distilled: "eventbridge", alchemy: "EventBridge" }, |
| 972 | iam: { distilled: "iam", alchemy: "IAM" }, |
| 973 | pipes: { distilled: "pipes", alchemy: "Pipes" }, |
| 974 | sns: { distilled: "sns", alchemy: "SNS" }, |
| 975 | scheduler: { distilled: "scheduler", alchemy: "Scheduler" }, |
| 976 | rds: { distilled: "rds", alchemy: "RDS" }, |
| 977 | "rds-data": { distilled: "rds-data", alchemy: "RDSData" }, |
| 978 | "secrets-manager": { |
| 979 | distilled: "secrets-manager", |
| 980 | alchemy: "SecretsManager", |
| 981 | }, |
| 982 | apigateway: { distilled: "api-gateway", alchemy: "ApiGateway" }, |
| 983 | ses: { distilled: "ses", alchemy: "SES" }, |
| 984 | sesv2: { distilled: "sesv2", alchemy: "SES" }, |
| 985 | }; |
| 986 | |
| 987 | const config = serviceConfig[serviceNameLower] || { |
| 988 | distilled: serviceNameLower, |
| 989 | alchemy: serviceNameUpper, |
| 990 | }; |
| 991 | |
| 992 | const preferredDistilledPath = path.resolve( |
| 993 | root, |
| 994 | `submodules/distilled/packages/aws/src/services/${config.distilled}.ts`, |
| 995 | ); |
| 996 | const resolvedDistilledPath = (yield* fs.access(preferredDistilledPath).pipe(Effect.isSuccess)) |
| 997 | ? preferredDistilledPath |
| 998 | : undefined; |
| 999 | const distilledPath = resolvedDistilledPath ?? `@distilled.cloud/aws/${config.distilled}`; |
| 1000 | const alchemyPath = path.resolve(root, `packages/aws/src/${config.alchemy}`); |
| 1001 | const bindingTestPath = path.resolve( |
| 1002 | root, |
| 1003 | `packages/integration-tests/test/AWS/${config.alchemy}/Bindings.test.ts`, |
| 1004 | ); |
| 1005 | const indexPath = path.join(alchemyPath, "index.ts"); |
| 1006 | const providersPath = path.resolve(root, "packages/aws/src/Providers.ts"); |
| 1007 | |
| 1008 | // Extract data |
| 1009 | const distilledOps = yield* extractDistilledOperations( |
| 1010 | resolvedDistilledPath ?? preferredDistilledPath, |
| 1011 | `@distilled.cloud/aws/${config.distilled}`, |
| 1012 | ); |
| 1013 | const alchemyFiles = yield* getAlchemyFiles(alchemyPath); |
| 1014 | const indexExports = yield* getIndexExports(indexPath); |
| 1015 | const providerRegs = yield* getProvidersRegistrations(providersPath, config.alchemy); |
| 1016 | const bindingTestCoverage = yield* getBindingTestDescribes(bindingTestPath); |
| 1017 | |
| 1018 | // Classify operations |
| 1019 | const operations: Operation[] = yield* Effect.forEach( |
| 1020 | distilledOps, |
| 1021 | Effect.fnUntraced(function* (name) { |
| 1022 | const pascalCase = toPascalCase(name); |
| 1023 | const classification = classifyOperation(serviceNameLower, name); |
| 1024 | const implemented = alchemyFiles.has(pascalCase); |
| 1025 | const resourceArity = implemented |
| 1026 | ? yield* inferImplementedResourceArity( |
| 1027 | alchemyPath, |
| 1028 | pascalCase, |
| 1029 | classification.resourceArity, |
| 1030 | ) |
| 1031 | : classification.resourceArity; |
| 1032 | |
| 1033 | return { |
| 1034 | name, |
| 1035 | camelCase: name, |
| 1036 | pascalCase, |
| 1037 | ...classification, |
| 1038 | resourceArity, |
| 1039 | implemented, |
| 1040 | registeredInProviders: providerRegs.bindings.has(pascalCase), |
| 1041 | registeredInIndex: indexExports.has(pascalCase), |
| 1042 | }; |
| 1043 | }), |
| 1044 | ); |
| 1045 | |
| 1046 | // Group by category |
| 1047 | const implementedBindings = operations.filter( |
| 1048 | (op) => op.category === "binding" && op.implemented, |
| 1049 | ); |
| 1050 | const missingBindings = operations.filter((op) => op.category === "binding" && !op.implemented); |
| 1051 | const resourceLifecycleOps = operations.filter((op) => op.category === "resource-lifecycle"); |
| 1052 | const eventSourceOps = operations.filter((op) => op.category === "event-source"); |
| 1053 | const helperCandidates = operations.filter((op) => op.category === "helper-candidate"); |
| 1054 | const internalOps = operations.filter((op) => op.category === "internal"); |
| 1055 | |
| 1056 | // Infer resources and helpers |
| 1057 | const canonicalResources = inferCanonicalResources(operations, alchemyFiles); |
| 1058 | const suggestedHelpers = suggestHelpers(operations, serviceName); |
| 1059 | const leastPrivilegeWarnings = yield* getLeastPrivilegeWarnings(alchemyPath, operations); |
| 1060 | |
| 1061 | // Find registration gaps |
| 1062 | const registrationGaps: RegistrationGap[] = []; |
| 1063 | |
| 1064 | const implementedButNotInIndex = implementedBindings.filter((op) => !op.registeredInIndex); |
| 1065 | if (implementedButNotInIndex.length > 0) { |
| 1066 | registrationGaps.push({ |
| 1067 | type: "index", |
| 1068 | file: indexPath, |
| 1069 | missing: implementedButNotInIndex.map((op) => op.pascalCase), |
| 1070 | }); |
| 1071 | } |
| 1072 | |
| 1073 | const implementedButNotInProviders = implementedBindings.filter( |
| 1074 | (op) => !op.registeredInProviders, |
| 1075 | ); |
| 1076 | if (implementedButNotInProviders.length > 0) { |
| 1077 | registrationGaps.push({ |
| 1078 | type: "policy", |
| 1079 | file: providersPath, |
| 1080 | missing: implementedButNotInProviders.map((op) => `${op.pascalCase}PolicyLive`), |
| 1081 | }); |
| 1082 | } |
| 1083 | |
| 1084 | const missingBindingTests = bindingTestCoverage.exists |
| 1085 | ? implementedBindings |
| 1086 | .filter((op) => !bindingTestCoverage.describes.has(op.pascalCase)) |
| 1087 | .map((op) => op.pascalCase) |
| 1088 | : implementedBindings.map((op) => op.pascalCase); |
| 1089 | |
| 1090 | const report: AuditReport = { |
| 1091 | service: serviceName, |
| 1092 | distilledPath, |
| 1093 | alchemyPath, |
| 1094 | bindingTestPath, |
| 1095 | totalOperations: operations.length, |
| 1096 | implementedBindings, |
| 1097 | missingBindings, |
| 1098 | resourceLifecycleOps, |
| 1099 | eventSourceOps, |
| 1100 | helperCandidates, |
| 1101 | internalOps, |
| 1102 | canonicalResources, |
| 1103 | suggestedHelpers, |
| 1104 | registrationGaps, |
| 1105 | missingBindingTests, |
| 1106 | leastPrivilegeWarnings, |
| 1107 | }; |
| 1108 | return report; |
| 1109 | }); |
| 1110 | |
| 1111 | // ============ Report Formatting ============ |
| 1112 | |
| 1113 | function formatReport(report: AuditReport): string { |
| 1114 | const lines: string[] = []; |
| 1115 | |
| 1116 | lines.push(`\n${"=".repeat(80)}`); |
| 1117 | lines.push(`SERVICE AUDIT: ${report.service.toUpperCase()}`); |
| 1118 | lines.push(`${"=".repeat(80)}\n`); |
| 1119 | |
| 1120 | lines.push(`Distilled spec: ${report.distilledPath}`); |
| 1121 | lines.push(`Alchemy path: ${report.alchemyPath}`); |
| 1122 | lines.push(`Binding tests: ${report.bindingTestPath}`); |
| 1123 | lines.push(`Total operations in distilled: ${report.totalOperations}\n`); |
| 1124 | |
| 1125 | // Summary |
| 1126 | lines.push(`${"─".repeat(80)}`); |
| 1127 | lines.push("SUMMARY"); |
| 1128 | lines.push(`${"─".repeat(80)}`); |
| 1129 | lines.push(` Implemented bindings: ${report.implementedBindings.length}`); |
| 1130 | lines.push(` Missing bindings: ${report.missingBindings.length}`); |
| 1131 | lines.push(` Resource lifecycle ops: ${report.resourceLifecycleOps.length}`); |
| 1132 | lines.push(` Event source ops: ${report.eventSourceOps.length}`); |
| 1133 | lines.push(` Helper candidates: ${report.helperCandidates.length}`); |
| 1134 | lines.push(` Internal ops (skip): ${report.internalOps.length}`); |
| 1135 | lines.push(` Missing binding tests: ${report.missingBindingTests.length}`); |
| 1136 | lines.push(` Least-privilege warnings: ${report.leastPrivilegeWarnings.length}`); |
| 1137 | lines.push(""); |
| 1138 | |
| 1139 | // Implemented bindings |
| 1140 | if (report.implementedBindings.length > 0) { |
| 1141 | lines.push(`${"─".repeat(80)}`); |
| 1142 | lines.push("IMPLEMENTED BINDINGS"); |
| 1143 | lines.push(`${"─".repeat(80)}`); |
| 1144 | for (const op of report.implementedBindings) { |
| 1145 | const arity = `[${formatArity(op.resourceArity)}]`; |
| 1146 | const regStatus = op.registeredInProviders ? "✓ registered" : "⚠ NOT in Providers.ts"; |
| 1147 | lines.push(` ✓ ${op.pascalCase}.ts ${arity} ${regStatus}`); |
| 1148 | } |
| 1149 | lines.push(""); |
| 1150 | } |
| 1151 | |
| 1152 | // Missing bindings (priority list) |
| 1153 | if (report.missingBindings.length > 0) { |
| 1154 | lines.push(`${"─".repeat(80)}`); |
| 1155 | lines.push("MISSING BINDINGS (implement these)"); |
| 1156 | lines.push(`${"─".repeat(80)}`); |
| 1157 | |
| 1158 | // Group by arity |
| 1159 | const arity1 = report.missingBindings.filter((op) => op.resourceArity === 1); |
| 1160 | const arity0 = report.missingBindings.filter((op) => op.resourceArity === 0); |
| 1161 | const arity2 = report.missingBindings.filter((op) => op.resourceArity === 2); |
| 1162 | const arityN = report.missingBindings.filter((op) => op.resourceArity === "n"); |
| 1163 | |
| 1164 | if (arity1.length > 0) { |
| 1165 | lines.push(" Single-resource bindings (arity=1):"); |
| 1166 | for (const op of arity1.slice(0, 20)) { |
| 1167 | lines.push(` • ${op.pascalCase} (${op.camelCase})`); |
| 1168 | } |
| 1169 | if (arity1.length > 20) { |
| 1170 | lines.push(` ... and ${arity1.length - 20} more`); |
| 1171 | } |
| 1172 | } |
| 1173 | |
| 1174 | if (arity0.length > 0) { |
| 1175 | lines.push(" Service-scoped bindings (arity=0):"); |
| 1176 | for (const op of arity0) { |
| 1177 | lines.push(` • ${op.pascalCase} (${op.camelCase})`); |
| 1178 | } |
| 1179 | } |
| 1180 | |
| 1181 | if (arity2.length > 0) { |
| 1182 | lines.push(" Fixed multi-resource bindings (arity=2):"); |
| 1183 | for (const op of arity2) { |
| 1184 | lines.push(` • ${op.pascalCase} (${op.camelCase})`); |
| 1185 | } |
| 1186 | } |
| 1187 | |
| 1188 | if (arityN.length > 0) { |
| 1189 | lines.push(" Variadic resource bindings (arity=n):"); |
| 1190 | for (const op of arityN) { |
| 1191 | lines.push(` • ${op.pascalCase} (${op.camelCase})`); |
| 1192 | } |
| 1193 | } |
| 1194 | lines.push(""); |
| 1195 | } |
| 1196 | |
| 1197 | // Canonical resources |
| 1198 | if (report.canonicalResources.length > 0) { |
| 1199 | lines.push(`${"─".repeat(80)}`); |
| 1200 | lines.push("CANONICAL RESOURCES (IaC resources to implement)"); |
| 1201 | lines.push(`${"─".repeat(80)}`); |
| 1202 | for (const res of report.canonicalResources) { |
| 1203 | const status = res.hasProvider ? "✓ has provider" : "⚠ MISSING provider"; |
| 1204 | lines.push(` ${res.name}: ${status}`); |
| 1205 | lines.push(` Implied by: ${res.impliedByOperations.join(", ")}`); |
| 1206 | } |
| 1207 | lines.push(""); |
| 1208 | } |
| 1209 | |
| 1210 | // Event source operations |
| 1211 | if (report.eventSourceOps.length > 0) { |
| 1212 | lines.push(`${"─".repeat(80)}`); |
| 1213 | lines.push("EVENT SOURCE OPERATIONS"); |
| 1214 | lines.push(`${"─".repeat(80)}`); |
| 1215 | for (const op of report.eventSourceOps) { |
| 1216 | const impl = op.implemented ? "✓" : "○"; |
| 1217 | lines.push(` ${impl} ${op.camelCase}`); |
| 1218 | } |
| 1219 | lines.push(""); |
| 1220 | } |
| 1221 | |
| 1222 | // Helper suggestions |
| 1223 | if (report.suggestedHelpers.length > 0) { |
| 1224 | lines.push(`${"─".repeat(80)}`); |
| 1225 | lines.push("SUGGESTED HELPERS"); |
| 1226 | lines.push(`${"─".repeat(80)}`); |
| 1227 | for (const helper of report.suggestedHelpers) { |
| 1228 | lines.push(` ${helper.name}`); |
| 1229 | lines.push(` Pattern: ${helper.pattern}`); |
| 1230 | lines.push(` Based on: ${helper.basedOn.join(", ")}`); |
| 1231 | if (helper.existingExample) { |
| 1232 | lines.push(` Example: ${helper.existingExample}`); |
| 1233 | } |
| 1234 | } |
| 1235 | lines.push(""); |
| 1236 | } |
| 1237 | |
| 1238 | // Registration gaps |
| 1239 | if (report.registrationGaps.length > 0) { |
| 1240 | lines.push(`${"─".repeat(80)}`); |
| 1241 | lines.push("REGISTRATION GAPS (fix these)"); |
| 1242 | lines.push(`${"─".repeat(80)}`); |
| 1243 | for (const gap of report.registrationGaps) { |
| 1244 | lines.push(` ${gap.type.toUpperCase()} (${gap.file}):`); |
| 1245 | for (const item of gap.missing) { |
| 1246 | lines.push(` • ${item}`); |
| 1247 | } |
| 1248 | } |
| 1249 | lines.push(""); |
| 1250 | } |
| 1251 | |
| 1252 | if (report.missingBindingTests.length > 0) { |
| 1253 | lines.push(`${"─".repeat(80)}`); |
| 1254 | lines.push("MISSING BINDING TESTS (add describe blocks)"); |
| 1255 | lines.push(`${"─".repeat(80)}`); |
| 1256 | lines.push(` In: ${report.bindingTestPath}`); |
| 1257 | for (const binding of report.missingBindingTests) { |
| 1258 | lines.push(` • describe("${binding}", ...)`); |
| 1259 | } |
| 1260 | lines.push(""); |
| 1261 | } |
| 1262 | |
| 1263 | if (report.leastPrivilegeWarnings.length > 0) { |
| 1264 | lines.push(`${"─".repeat(80)}`); |
| 1265 | lines.push("LEAST-PRIVILEGE WARNINGS"); |
| 1266 | lines.push(`${"─".repeat(80)}`); |
| 1267 | for (const warning of report.leastPrivilegeWarnings) { |
| 1268 | lines.push( |
| 1269 | ` ⚠ ${warning.binding}.ts [${formatArity(warning.resourceArity)}] (${warning.file})`, |
| 1270 | ); |
| 1271 | lines.push(` ${warning.message}`); |
| 1272 | } |
| 1273 | lines.push(""); |
| 1274 | } |
| 1275 | |
| 1276 | // Helper candidate operations |
| 1277 | if (report.helperCandidates.length > 0) { |
| 1278 | lines.push(`${"─".repeat(80)}`); |
| 1279 | lines.push("HELPER CANDIDATE OPERATIONS (consider wrapping)"); |
| 1280 | lines.push(`${"─".repeat(80)}`); |
| 1281 | for (const op of report.helperCandidates) { |
| 1282 | const impl = op.implemented ? "✓" : "○"; |
| 1283 | lines.push(` ${impl} ${op.camelCase} [${formatArity(op.resourceArity)}]`); |
| 1284 | } |
| 1285 | lines.push(""); |
| 1286 | } |
| 1287 | |
| 1288 | lines.push(`${"=".repeat(80)}`); |
| 1289 | lines.push("END OF AUDIT"); |
| 1290 | lines.push(`${"=".repeat(80)}\n`); |
| 1291 | |
| 1292 | return lines.join("\n"); |
| 1293 | } |
| 1294 | |
| 1295 | // ============ CLI ============ |
| 1296 | |
| 1297 | const command = Command.make( |
| 1298 | "audit-service", |
| 1299 | { |
| 1300 | json: Flag.Boolean("json").pipe( |
| 1301 | Flag.withDescription("Print the report as JSON"), |
| 1302 | Flag.withDefault(false), |
| 1303 | ), |
| 1304 | service: Argument.String("service").pipe( |
| 1305 | Argument.withDescription("AWS service to audit, e.g. dynamodb, s3, sqs"), |
| 1306 | ), |
| 1307 | }, |
| 1308 | Effect.fn(function* ({ json, service }) { |
| 1309 | const report = yield* auditService(service).pipe( |
| 1310 | Effect.mapError( |
| 1311 | (cause) => new Error(`Error auditing service ${service}: ${String(cause)}`, { cause }), |
| 1312 | ), |
| 1313 | ); |
| 1314 | yield* Console.log(json ? JSON.stringify(report, null, 2) : formatReport(report)); |
| 1315 | }), |
| 1316 | ).pipe( |
| 1317 | Command.withDescription( |
| 1318 | "Compare a distilled AWS service spec against the alchemy implementation", |
| 1319 | ), |
| 1320 | ); |
| 1321 | |
| 1322 | Command.run(command, { version: "0.0.0" }).pipe( |
| 1323 | Effect.provide(NodeServices.layer), |
| 1324 | NodeRuntime.runMain, |
| 1325 | ); |