@intentius/chant-lexicon-aws 0.33.0 → 0.34.0

package/dist/ambient.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Resources that are simply *there* (#1278).
+ *
+ * `describeResources` answers "what do I manage" and `observeDependencies`
+ * answers "what do I rely on". Both resolve outward from the declared estate,
+ * so neither can see a resource nothing points at — and "which of my security
+ * groups are unused" is precisely a question about resources nothing points at.
+ *
+ * A state file cannot answer this at all: it knows what it created, and an
+ * unused resource is by definition not something it created and attached. A
+ * lexicon that can enumerate a kind can.
+ *
+ * Bounded by the kinds the project declares. A project managing security groups
+ * is asked about security groups, not about the account.
+ */
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+/** The requested kinds, plus the ones they imply. */
+export declare function withImplied(kinds: string[]): string[];
+/** The kinds this reader can enumerate. Declared so a caller can mention
+ * `--ambient` without paying for a scan to discover it is relevant. */
+export declare const AMBIENT_KINDS: string[];
+/** True when this lexicon can enumerate the kind, so a caller can say what it skipped. */
+export declare function canEnumerate(kind: string): boolean;
+/**
+ * List resources of the declared kinds that exist in the account but are
+ * neither managed nor already observed.
+ *
+ * Attachment is deliberately NOT decided here. Whether a security group is
+ * "unused" is a graph question — does anything reference it — and the graph
+ * answers it once the group is a node. Deciding it in the reader would put a
+ * conclusion in the observation, which is the mistake `liveInternetFacing` made
+ * and #1271 undid.
+ */
+export declare function observeAwsAmbient(options: {
+    kinds: string[];
+    observed: Record<string, ResourceMetadata>;
+    region?: string;
+}): Promise<Record<string, ResourceMetadata>>;
+//# sourceMappingURL=ambient.d.ts.map

package/dist/ambient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ambient.d.ts","sourceRoot":"","sources":["../src/ambient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAkDjE,qDAAqD;AACrD,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE,CAErD;AAED;uEACuE;AACvE,eAAO,MAAM,aAAa,EAAE,MAAM,EAA4B,CAAC;AAE/D,0FAA0F;AAC1F,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElD;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE;IAC/C,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAmD5C"}

package/dist/deep-observe.d.ts

@@ -85,6 +85,11 @@ export interface AwsDeepObserveOptions {
         props: Record<string, unknown>;
     }>;
     stack?: string;
+    /** Region this stack is deployed in (#1267). Same reason the thin path takes
+     * one (#1261): without it a multi-region estate reads every stack against the
+     * ambient region, the out-of-region ones come back empty, and a deep snapshot
+     * silently records no properties for them. */
+    region?: string;
     owned?: boolean;
 }
 /**

package/dist/deep-observe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../src/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAGV,sBAAsB,EACtB,qBAAqB,EAItB,MAAM,0BAA0B,CAAC;AAKlC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAKlD,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAkBlD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBxE,CAAC;AAkBF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,sBAmDvC,CAAC;AAMF,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAuBrF;AASD,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAI/E;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CAwHhC"}
+{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../src/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAEH,OAAO,KAAK,EAGV,sBAAsB,EACtB,qBAAqB,EAItB,MAAM,0BAA0B,CAAC;AAKlC;;;GAGG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAKlD,CAAC;AAEH;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,EAAE,WAAW,CAAC,MAAM,CAkBlD,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBxE,CAAC;AAkBF;;;;;GAKG;AACH,eAAO,MAAM,yBAAyB,EAAE,sBAmDvC,CAAC;AAMF,uFAAuF;AACvF,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,MAAM,GAAG,oBAAoB,GAAG,IAAI,CAuBrF;AASD,6EAA6E;AAC7E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAI/E;AAED,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC/E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;kDAG8C;IAC9C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,qBAAqB,GAC7B,OAAO,CAAC,qBAAqB,CAAC,CA4HhC"}

package/dist/defaults.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Which resources the provider created, rather than anyone's infrastructure code.
+ *
+ * Every account arrives with resources nobody wrote: a default VPC and its
+ * subnets, a default security group per VPC, a main route table, AWS-managed
+ * KMS keys and IAM policies. They are yours to account for and were never
+ * yours to declare, and until now chant recorded them looking exactly like
+ * everything else.
+ *
+ * That matters wherever a question is about what you built. Asked which
+ * security groups were unused, agents split three ways on the same correct set
+ * of four — one excluded the three VPC defaults as "not real cleanup
+ * candidates" and answered one, another counted something extra and answered
+ * five. The answers that were accepted all did the same thing: listed all four
+ * and said which were defaults. They could only do that by recognising them,
+ * and chant gave them nothing to recognise them by.
+ *
+ * This records a fact and stops. `providerDefault: true` says the provider
+ * created this; it does not say the resource is unused, safe to ignore, or
+ * exempt from anything. Deciding that here would put a conclusion in an
+ * observation — the mistake `liveInternetFacing` made and #1271 undid — and it
+ * would be wrong in this very case, since the accepted answers count defaults
+ * as unused.
+ *
+ * Almost none of this is chant's judgement. AWS marks these itself, on the same
+ * payloads chant already reads; the fields were simply being dropped. The one
+ * derivation is the security group, and it is safe because `default` is a
+ * reserved group name — AWS rejects it on create, so a group called `default`
+ * is that VPC's default group.
+ */
+import type { ResourceMetadata } from "@intentius/chant/lexicon";
+/** True when this lexicon can tell whether the kind is a provider default. */
+export declare function canDetectDefault(kind: string): boolean;
+/** The kinds whose provider-default status this lexicon can report. */
+export declare const DEFAULT_AWARE_KINDS: string[];
+/**
+ * Mark the resources the provider created.
+ *
+ * Only ever sets the attribute to `true`, and only for kinds with a known
+ * marker: absent means "not a default, or chant cannot tell", and those are
+ * genuinely different from each other in a way a blanket `false` would hide.
+ */
+export declare function stampProviderDefaults(resources: Record<string, ResourceMetadata>): Record<string, ResourceMetadata>;
+//# sourceMappingURL=defaults.d.ts.map

package/dist/defaults.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"defaults.d.ts","sourceRoot":"","sources":["../src/defaults.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AA8BjE,8EAA8E;AAC9E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,uEAAuE;AACvE,eAAO,MAAM,mBAAmB,EAAE,MAAM,EAAkC,CAAC;AAE3E;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,GAC1C,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAkBlC"}

package/dist/dependencies.d.ts

@@ -0,0 +1,60 @@
+/**
+ * What an AWS estate depends on but does not declare (#1273).
+ *
+ * `describeResources` is scoped to the stack. An instance placed in the
+ * account's default VPC routes through a route table nobody declared, so that
+ * table is never observed, never a node, and no fold can traverse to it. The
+ * answer used to be computed inside the lexicon and injected as an attribute —
+ * which is a conclusion no snapshot can record enough to recompute.
+ *
+ * This reports the resources instead, so the one graph fold derives the answer.
+ *
+ * The closure is bounded: start from the observed instances, follow the
+ * reference chain the catalog declares as meaningful — subnet, then route
+ * table, then gateway — and stop. Anything not reached from a declared resource
+ * along a declared reference is not a dependency, it is just the account.
+ */
+import type { DependencyObservation, ResourceMetadata } from "@intentius/chant/lexicon";
+/** One ingress permission as `describe-security-groups` returns it. */
+interface RawIpPermission {
+    IpProtocol?: string;
+    FromPort?: number;
+    ToPort?: number;
+    IpRanges?: Array<{
+        CidrIp?: string;
+    }>;
+    Ipv6Ranges?: Array<{
+        CidrIpv6?: string;
+    }>;
+    UserIdGroupPairs?: Array<{
+        GroupId?: string;
+    }>;
+}
+/**
+ * Flatten `IpPermissions` into the CloudFormation-shaped rules the fold reads.
+ *
+ * The two AWS surfaces disagree about the same concept: a template's
+ * `SecurityGroupIngress` carries `CidrIp` flat on the rule, while
+ * `describe-security-groups` nests sources under `IpRanges[]`, `Ipv6Ranges[]`
+ * and `UserIdGroupPairs[]`, and one permission can hold several. Handing the
+ * describe shape to the fold unchanged yields a rule with no recognisable
+ * source, which `normalizeIngress` renders as `?` — an ingress rule that
+ * matches no CIDR query and quietly narrows the answer.
+ *
+ * One rule per source, because that is what the flat shape means.
+ */
+export declare function toIngressRules(permissions: RawIpPermission[]): Array<Record<string, unknown>>;
+/**
+ * Read the routing an observed estate depends on.
+ *
+ * Only the tables that actually serve an observed instance are reported: one
+ * reached by an explicit subnet association, or the VPC's main table standing in
+ * for a subnet with none. A route table serving nothing chant deployed is not a
+ * dependency of this estate.
+ */
+export declare function observeAwsDependencies(options: {
+    observed: Record<string, ResourceMetadata>;
+    region?: string;
+}): Promise<DependencyObservation>;
+export {};
+//# sourceMappingURL=dependencies.d.ts.map

package/dist/dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../src/dependencies.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,qBAAqB,EAAE,gBAAgB,EAAU,MAAM,0BAA0B,CAAC;AAKhG,uEAAuE;AACvE,UAAU,eAAe;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,KAAK,CAAC;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtC,UAAU,CAAC,EAAE,KAAK,CAAC;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC1C,gBAAgB,CAAC,EAAE,KAAK,CAAC;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,eAAe,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAmB7F;AASD;;;;;;;GAOG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE;IACpD,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA6OjC"}