@intentius/chant-lexicon-aws 0.124.103 → 0.124.104

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,10 @@
1
1
  import { type AwsReadClientOptions } from "./api/read-client.js";
2
2
  import type { ResourceMetadata } from "@intentius/chant/lexicon";
3
+ /**
4
+ * The primary identifier's parts for a resource type, or undefined when the
5
+ * type is not a generated resource or has no primary identifier on record.
6
+ */
7
+ export declare function primaryIdentifierParts(entityType: string): readonly string[] | undefined;
3
8
  /**
4
9
  * The Cloud Control identifier the declared props spell, or undefined when the
5
10
  * type has no primary identifier on record or any part of it is absent or
@@ -33,6 +33,16 @@ function manifestByType() {
33
33
  }
34
34
  return byResourceType;
35
35
  }
36
+ /**
37
+ * The primary identifier's parts for a resource type, or undefined when the
38
+ * type is not a generated resource or has no primary identifier on record.
39
+ */
40
+ export function primaryIdentifierParts(entityType) {
41
+ const entry = manifestByType().get(entityType);
42
+ if (!entry || entry.kind !== "resource" || !entry.primaryIdentifier || entry.primaryIdentifier.length === 0)
43
+ return undefined;
44
+ return entry.primaryIdentifier;
45
+ }
36
46
  /**
37
47
  * The Cloud Control identifier the declared props spell, or undefined when the
38
48
  * type has no primary identifier on record or any part of it is absent or
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "algorithm": "sha256",
3
3
  "artifacts": {
4
- "manifest.json": "a9698194fd64833276748ca73f7dd76cdeba7eb601c2c1dbe54b3df942372742",
4
+ "manifest.json": "ddbc53f1ebd4efc8c7dacf2241417c6b7a330224549ae2cbe2a3f84b2481b13a",
5
5
  "meta.json": "7de63d55427041907cd0fbdc504fc496d381e2bfebeae2fe9d48f1847ed29faf",
6
6
  "types/index.d.ts": "8651f9ae166668f4311eea1fe61c3fe235f345947951c1d23d1df24a4fd3384f",
7
7
  "rules/hardcoded-region.ts": "957eadcaa9f39cc17d21437565d7a94607d9b082cf28918b178fa067f07498a9",
@@ -75,5 +75,5 @@
75
75
  "skills/chant-aws-eks.md": "8789255709ff004ad0a875fd5999edcdc66fc6e33d710db058d9f42703bcfdfe",
76
76
  "skills/chant-aws-carve-terraform.md": "a6f528c814024422744118abbfd9bbf26f3d60c599e90c3f186f8b76e1e38a51"
77
77
  },
78
- "composite": "f3afc081ad543cdb1d742c0ff9b8030e2b0082d606b776380e4659d834f7adab"
78
+ "composite": "4b4254374ba7c2da9da3950ab7a20461fd2e9b815158be029a7a65ad7f6830ea"
79
79
  }
@@ -0,0 +1,10 @@
1
+ import type { RefRule } from "@intentius/chant/graph-refs";
2
+ /** JSON text as a value: an object passes through, a string is parsed, and one that is URL-encoded is decoded first. */
3
+ export declare function parseJsonText(v: unknown): unknown;
4
+ /** Where each kind keeps a policy document, as a path from its attrs. */
5
+ export declare const POLICY_DOCUMENTS: ReadonlyArray<{
6
+ from: string;
7
+ path: string;
8
+ }>;
9
+ /** The catalog's rules that read JSON text. */
10
+ export declare function jsonTextRules(): RefRule[];
@@ -0,0 +1,114 @@
1
+ /** The values at `path` (`a.b`, `arr[].c`) of `obj`, objects and strings kept as they are. */
2
+ function rawAt(obj, path) {
3
+ let cur = [obj];
4
+ for (const step of path.split(".")) {
5
+ const isArray = step.endsWith("[]");
6
+ const key = isArray ? step.slice(0, -2) : step;
7
+ const next = [];
8
+ for (const c of cur) {
9
+ if (!c || typeof c !== "object")
10
+ continue;
11
+ const v = c[key];
12
+ if (v === undefined)
13
+ continue;
14
+ if (isArray) {
15
+ if (Array.isArray(v))
16
+ next.push(...v);
17
+ }
18
+ else {
19
+ next.push(v);
20
+ }
21
+ }
22
+ cur = next;
23
+ }
24
+ return cur;
25
+ }
26
+ /** JSON text as a value: an object passes through, a string is parsed, and one that is URL-encoded is decoded first. */
27
+ export function parseJsonText(v) {
28
+ if (typeof v !== "string")
29
+ return v;
30
+ for (const text of [v, safeDecode(v)]) {
31
+ if (text === undefined)
32
+ continue;
33
+ try {
34
+ return JSON.parse(text);
35
+ }
36
+ catch {
37
+ /* try the next spelling */
38
+ }
39
+ }
40
+ return undefined;
41
+ }
42
+ function safeDecode(s) {
43
+ try {
44
+ return decodeURIComponent(s);
45
+ }
46
+ catch {
47
+ return undefined;
48
+ }
49
+ }
50
+ const strings = (v) => (typeof v === "string" ? [v] : Array.isArray(v) ? v.filter((x) => typeof x === "string") : []);
51
+ /** The ARN-shaped strings of a list of values; wildcards and plain names are left to match nothing. */
52
+ const arns = (vs) => [...new Set(vs.filter((s) => s.startsWith("arn:")))];
53
+ const redrivePaths = ["RedrivePolicy", "Attributes.RedrivePolicy"];
54
+ function redriveRule(base) {
55
+ return {
56
+ from: "AWS::SQS::Queue",
57
+ path: `${base}.deadLetterTargetArn`,
58
+ targetKind: "AWS::SQS::Queue",
59
+ relation: "reference",
60
+ label: "dead-letter queue",
61
+ viaAttr: "RedrivePolicy",
62
+ optional: true,
63
+ join(holder, find) {
64
+ const out = [];
65
+ for (const doc of rawAt(holder.attrs, base)) {
66
+ for (const arn of arns(strings(parseJsonText(doc)?.deadLetterTargetArn))) {
67
+ out.push({ value: arn, targets: find(arn).filter((n) => n.kind === "AWS::SQS::Queue") });
68
+ }
69
+ }
70
+ return out;
71
+ },
72
+ };
73
+ }
74
+ /** Where each kind keeps a policy document, as a path from its attrs. */
75
+ export const POLICY_DOCUMENTS = [
76
+ { from: "AWS::IAM::Role", path: "AssumeRolePolicyDocument" },
77
+ { from: "AWS::IAM::Role", path: "Policies[].PolicyDocument" },
78
+ { from: "AWS::IAM::ManagedPolicy", path: "PolicyDocument" },
79
+ { from: "AWS::IAM::Policy", path: "PolicyDocument" },
80
+ { from: "AWS::SQS::QueuePolicy", path: "PolicyDocument" },
81
+ { from: "AWS::S3::BucketPolicy", path: "PolicyDocument" },
82
+ { from: "AWS::SQS::Queue", path: "Policy" },
83
+ { from: "AWS::SQS::Queue", path: "Attributes.Policy" },
84
+ ];
85
+ const POLICY_VALUES = [
86
+ { path: "Statement[].Resource", label: "grants on" },
87
+ { path: "Statement[].Principal.AWS", label: "trusts" },
88
+ ];
89
+ function policyRules() {
90
+ return POLICY_DOCUMENTS.flatMap(({ from, path: docPath }) => POLICY_VALUES.map(({ path: valuePath, label }) => ({
91
+ from,
92
+ path: `${docPath}.${valuePath}`,
93
+ relation: "reference",
94
+ label,
95
+ optional: true,
96
+ join(holder, find) {
97
+ const out = [];
98
+ for (const doc of rawAt(holder.attrs, docPath)) {
99
+ // A statement may be one object where the document would have a list.
100
+ const parsed = parseJsonText(doc);
101
+ const statements = parsed && typeof parsed === "object" ? parsed.Statement : undefined;
102
+ const list = Array.isArray(statements) ? statements : statements ? [statements] : [];
103
+ for (const arn of arns(list.flatMap((s) => rawAt(s, valuePath.replace(/^Statement\[\]\./, "")).flatMap(strings)))) {
104
+ out.push({ value: arn, targets: find(arn) });
105
+ }
106
+ }
107
+ return out;
108
+ },
109
+ })));
110
+ }
111
+ /** The catalog's rules that read JSON text. */
112
+ export function jsonTextRules() {
113
+ return [...redrivePaths.map(redriveRule), ...policyRules()];
114
+ }
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aws",
3
- "version": "0.124.103",
3
+ "version": "0.124.104",
4
4
  "chantVersion": ">=0.1.0",
5
5
  "namespace": "AWS",
6
6
  "intrinsics": [
package/dist/plugin.js CHANGED
@@ -23,7 +23,7 @@ import { awsDeepNormalizationHooks, observeResourcesDeepAws } from "./deep-obser
23
23
  import { awsDisruption } from "./disruption.js";
24
24
  import { awsReferenceCatalog } from "./reference-catalog.js";
25
25
  import { AMBIENT_KINDS } from "./ambient.js";
26
- import { canDescribe, describeOwnProperties, stampRegion } from "./properties.js";
26
+ import { canDescribe, describeCloudControlProperties, describeOwnProperties, stampRegion } from "./properties.js";
27
27
  import { stampProviderDefaults } from "./defaults.js";
28
28
  import { resolveTemplateAttrs } from "./live-attrs.js";
29
29
  import { CFParser } from "./import/parser.js";
@@ -685,7 +685,7 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
685
685
  const stackMarker = stackTags ? readOwnership(stackTags, AWS_TAG_OWNERSHIP_KEYS) : undefined;
686
686
  const stackOwnership = stackTags === undefined ? "unknown" : stackMarker ? "owned" : "foreign";
687
687
  // `owned: true` withheld nothing, so say why whenever the marker did not resolve.
688
- const notes = options.owned && stackMarker === undefined ? unresolvedNotes : undefined;
688
+ let notes = options.owned && stackMarker === undefined ? unresolvedNotes : undefined;
689
689
  // The outputs are the stack's, not any member's (#1279). They used to be
690
690
  // copied onto every resource's `attributes`, so a VPC carried the stack's
691
691
  // `expWebIp` and no `CidrBlock`. They ride the envelope once, keyed by the
@@ -724,7 +724,16 @@ aws cloudformation wait stack-update-complete --stack-name my-app-prod`,
724
724
  // the stack's exports replicated onto every member, so no instance carried
725
725
  // its own `VpcId`.
726
726
  const own = await describeOwnProperties(resources, options.region);
727
- const withProperties = stampProviderDefaults(stampRegion(own.resources, options.region));
727
+ // The other kinds' own properties (#4525), read through Cloud Control and
728
+ // normalized as an index of the same account is, so `attr:` answers the
729
+ // same under `search --live` and `search --index`. A kind it could not
730
+ // read keeps its identity and gets a note, not a hole: before this read
731
+ // existed those resources carried no properties and were observed.
732
+ const cc = await describeCloudControlProperties(own.resources, client);
733
+ const ccNotes = [...cc.failures.values()].map((detail) => `[aws] ${detail}; those resources carry their stack identity without their properties`);
734
+ if (ccNotes.length > 0)
735
+ notes = [...(notes ?? []), ...ccNotes];
736
+ const withProperties = stampProviderDefaults(stampRegion(cc.resources, options.region));
728
737
  // The own-property read is still a CLI shell-out while the stack reads are
729
738
  // not (#1206), so the two halves can now fail independently. When the
730
739
  // enrichment could not run at all, the resources it would have described are
@@ -21,6 +21,7 @@
21
21
  * kept underneath its own properties, which win a name collision because they
22
22
  * are the resource's.
23
23
  */
24
+ import type { AwsReadClientOptions } from "./api/read-client.js";
24
25
  import type { ResourceMetadata } from "@intentius/chant/lexicon";
25
26
  /**
26
27
  * Stamp the region each resource was observed in (#1279).
@@ -62,3 +63,28 @@ export interface OwnPropertiesResult {
62
63
  * has to declare rather than a thinner set of facts.
63
64
  */
64
65
  export declare function describeOwnProperties(resources: Record<string, ResourceMetadata>, region?: string): Promise<OwnPropertiesResult>;
66
+ /** What {@link describeCloudControlProperties} read, and why each kind it could not read failed. */
67
+ export interface CloudControlPropertiesResult {
68
+ resources: Record<string, ResourceMetadata>;
69
+ /** Why each failed kind failed, keyed by CloudFormation type. */
70
+ failures: Map<string, string>;
71
+ }
72
+ /**
73
+ * Every other stack member's own properties, through Cloud Control (#4525).
74
+ *
75
+ * {@link DESCRIBE} covers four EC2 kinds, so a bucket or a role read through
76
+ * the stack carried no properties at all, and `chant search "attr:Path=/"
77
+ * --live` matched nothing that the same query over an index of the same
78
+ * account matched. The index lists through Cloud Control and normalizes each
79
+ * model with the deep-observe hooks (`typeListing`, chant#4521). This reads
80
+ * the same model for the same resource and normalizes it the same way, so a
81
+ * bound row has the same attributes on both paths.
82
+ *
83
+ * A kind is read when its primary identifier is one part: CloudFormation's
84
+ * physical id for it is then the Cloud Control identifier. `GetResource` per
85
+ * resource; an endpoint that answers `UnsupportedOperation` (floci) gets one
86
+ * `ListResources` for the kind, joined back by identifier. Best-effort per
87
+ * kind: a kind that fails keeps the stack's identity and status, and its
88
+ * failure is reported for the caller to note.
89
+ */
90
+ export declare function describeCloudControlProperties(resources: Record<string, ResourceMetadata>, client: AwsReadClientOptions): Promise<CloudControlPropertiesResult>;
@@ -164,3 +164,78 @@ export async function describeOwnProperties(resources, region) {
164
164
  }
165
165
  return { resources: merged, transportFailed: failures.size === wanted.size, failures };
166
166
  }
167
+ /**
168
+ * Every other stack member's own properties, through Cloud Control (#4525).
169
+ *
170
+ * {@link DESCRIBE} covers four EC2 kinds, so a bucket or a role read through
171
+ * the stack carried no properties at all, and `chant search "attr:Path=/"
172
+ * --live` matched nothing that the same query over an index of the same
173
+ * account matched. The index lists through Cloud Control and normalizes each
174
+ * model with the deep-observe hooks (`typeListing`, chant#4521). This reads
175
+ * the same model for the same resource and normalizes it the same way, so a
176
+ * bound row has the same attributes on both paths.
177
+ *
178
+ * A kind is read when its primary identifier is one part: CloudFormation's
179
+ * physical id for it is then the Cloud Control identifier. `GetResource` per
180
+ * resource; an endpoint that answers `UnsupportedOperation` (floci) gets one
181
+ * `ListResources` for the kind, joined back by identifier. Best-effort per
182
+ * kind: a kind that fails keeps the stack's identity and status, and its
183
+ * failure is reported for the caller to note.
184
+ */
185
+ export async function describeCloudControlProperties(resources, client) {
186
+ const { primaryIdentifierParts } = await import("./identity-observe.js");
187
+ const wanted = new Map();
188
+ for (const [name, meta] of Object.entries(resources)) {
189
+ if (!meta.physicalId || canDescribe(meta.type))
190
+ continue;
191
+ if (primaryIdentifierParts(meta.type)?.length !== 1)
192
+ continue;
193
+ const byId = wanted.get(meta.type) ?? new Map();
194
+ byId.set(meta.physicalId, [...(byId.get(meta.physicalId) ?? []), name]);
195
+ wanted.set(meta.type, byId);
196
+ }
197
+ const failures = new Map();
198
+ if (wanted.size === 0)
199
+ return { resources, failures };
200
+ const { normalizeDeepProperties } = await import("@intentius/chant/deep-observation");
201
+ const { awsDeepNormalizationHooks } = await import("./deep-observe.js");
202
+ const { AwsReadError, getResource, listResources } = await import("./api/read-client.js");
203
+ const merged = { ...resources };
204
+ const detail = (err) => err instanceof AwsReadError && err.code ? `${err.code}: ${err.message}` : err instanceof Error ? err.message : String(err);
205
+ for (const [kind, byId] of wanted) {
206
+ const found = new Map();
207
+ try {
208
+ let listed = false;
209
+ for (const id of byId.keys()) {
210
+ try {
211
+ const d = await getResource(kind, id, client);
212
+ if (d)
213
+ found.set(id, d.properties);
214
+ }
215
+ catch (err) {
216
+ if (!(err instanceof AwsReadError) || err.code !== "UnsupportedOperation")
217
+ throw err;
218
+ listed = true;
219
+ break;
220
+ }
221
+ }
222
+ if (listed) {
223
+ for (const d of await listResources(kind, client)) {
224
+ if (byId.has(d.identifier))
225
+ found.set(d.identifier, d.properties);
226
+ }
227
+ }
228
+ }
229
+ catch (err) {
230
+ failures.set(kind, `Cloud Control read of ${kind} failed: ${detail(err)}`);
231
+ continue;
232
+ }
233
+ for (const [id, properties] of found) {
234
+ const attrs = normalizeDeepProperties(properties, { entityType: kind, side: "live", hooks: awsDeepNormalizationHooks });
235
+ for (const name of byId.get(id) ?? []) {
236
+ merged[name] = { ...merged[name], attributes: { ...(merged[name].attributes ?? {}), ...attrs } };
237
+ }
238
+ }
239
+ }
240
+ return { resources: merged, failures };
241
+ }
@@ -1,3 +1,4 @@
1
+ import { jsonTextRules } from "./json-text-references.js";
1
2
  /**
2
3
  * AWS reference catalog (#778, epic #776 v1) — how observed AWS resources
3
4
  * reference each other, so `chant graph --live` can reconstruct the topology.
@@ -138,6 +139,11 @@ export const awsReferenceCatalog = {
138
139
  // latency record for gcp points at gcp.three-cloud.example.). Optional,
139
140
  // since most record values are addresses or hostnames outside it.
140
141
  { from: "AWS::Route53::RecordSet", path: "ResourceRecords[]", targetKind: "AWS::Route53::RecordSet", relation: "reference", label: "aliases", optional: true },
142
+ // ── ARNs inside JSON text (#5285) ──
143
+ // A queue's RedrivePolicy and the Resource and Principal ARNs of a policy
144
+ // document, each at a named path (./json-text-references.ts). Indexed
145
+ // nodes only: a declared graph's rules read values, not JSON text.
146
+ ...jsonTextRules(),
141
147
  ],
142
148
  // Tags that name a cloud id in their key or value (behold#1023 Q5). Used
143
149
  // over indexed nodes only. No rule matches equal tag values in general.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intentius/chant-lexicon-aws",
3
- "version": "0.124.103",
3
+ "version": "0.124.104",
4
4
  "description": "AWS CloudFormation lexicon for chant — declarative IaC in TypeScript",
5
5
  "license": "Apache-2.0",
6
6
  "homepage": "https://intentius.io/chant",
@@ -82,6 +82,6 @@
82
82
  "typescript": "^5.9.3"
83
83
  },
84
84
  "peerDependencies": {
85
- "@intentius/chant": "^0.124.104"
85
+ "@intentius/chant": "^0.124.105"
86
86
  }
87
87
  }