@devries-cameron20 / t3code Mirror · read-only
Fork 0

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

main
ts 1,325 lines 39.5 KB
Raw
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 );