@intentius/chant-lexicon-aws 0.124.46 → 0.124.49

package/src/testdata/cfn-member/stack.yaml

@@ -0,0 +1,36 @@
+AWSTemplateFormatVersion: "2010-09-09"
+Parameters:
+  Env:
+    Type: String
+Resources:
+  Assets:
+    Type: AWS::S3::Bucket
+    Properties:
+      BucketName: !Sub "assets-${Env}-${AWS::Region}"
+  WebRole:
+    Type: AWS::IAM::Role
+    Properties:
+      AssumeRolePolicyDocument:
+        Statement: []
+  WebPolicy:
+    Type: AWS::IAM::Policy
+    Properties:
+      PolicyName: web
+      Roles:
+        - !Ref WebRole
+      PolicyDocument:
+        Statement:
+          - Effect: Allow
+            Action: s3:GetObject
+            Resource: !Sub "${Assets.Arn}/*"
+  Db:
+    Type: AWS::RDS::DBInstance
+    DependsOn: WebRole
+    Properties:
+      DBInstanceClass: db.t3.micro
+      Tags:
+        - Key: bucket
+          Value: !GetAtt Assets.DomainName
+Outputs:
+  Bucket:
+    Value: !Ref Assets

package/src/workspace-kinds.test.ts

@@ -0,0 +1,47 @@
+/**
+ * The cloudformation and cdk member kinds this lexicon supplies to a chant
+ * workspace (#3179): data in `workspace-kinds.json`, exported at
+ * `./workspace-kinds`.
+ */
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { describeWorkspaceKindConformance } from "@intentius/chant-test-utils";
+import { checkMemberFile, loadMemberFileSchema, readPackageKinds } from "../../../packages/core/src/workspace/kinds";
+
+const packageDir = join(import.meta.dirname, "..");
+
+/** What each kind's own file must do: pass for a good one, fail for a bad one (#3672). */
+function memberFileChecks(kind: string, good: string, bad: string): void {
+  describe(`${kind} member file`, () => {
+    const memberFile = readPackageKinds(packageDir).kinds.find((k) => k.name === kind)!.memberFile!;
+    it("names a schema that loads", () => {
+      expect(loadMemberFileSchema(memberFile, packageDir)).toBeUndefined();
+    });
+    it("passes a valid file", () => {
+      expect(checkMemberFile(memberFile, memberFile.path, good)).toEqual([]);
+    });
+    it("fails an invalid one", () => {
+      expect(checkMemberFile(memberFile, memberFile.path, bad).length).toBeGreaterThan(0);
+    });
+  });
+}
+
+const template = "AWSTemplateFormatVersion: '2010-09-09'\nResources:\n  B:\n    Type: AWS::S3::Bucket\n";
+
+describeWorkspaceKindConformance({
+  packageDir,
+  scenarios: [
+    { name: "a YAML template", kind: "cloudformation", files: { "stack.yaml": template }, claims: true },
+    { name: "a JSON template with only Resources", kind: "cloudformation", files: { "stack.json": '{"Resources": {}}' }, claims: true },
+    { name: "a YAML template using short-form tags", kind: "cloudformation", files: { "stack.yml": template + "Outputs:\n  N:\n    Value: !Ref B\n    Export:\n      Name: !Sub \"${AWS::StackName}-n\"\n" }, claims: true },
+    { name: "a template one level down", kind: "cloudformation", files: { "infra/stack.yaml": template }, claims: false },
+    { name: "a Kubernetes manifest", kind: "cloudformation", files: { "deploy.yaml": "apiVersion: apps/v1\nkind: Deployment\n" }, claims: false },
+    { name: "a package.json", kind: "cloudformation", files: { "package.json": '{"name": "x"}' }, claims: false },
+    { name: "a CDK app", kind: "cdk", files: { "cdk.json": '{"app": "npx ts-node bin/app.ts"}', "package.json": "{}" }, claims: true },
+    { name: "a CDK app one level down", kind: "cdk", files: { "infra/cdk.json": "{}" }, claims: false },
+    // cloudformation (320) outranks cdk (315) when both claim a directory.
+    { name: "a CDK app with a template beside it", kind: "cloudformation", files: { "cdk.json": '{"app": "x"}', "stack.yaml": template }, claims: true },
+  ],
+});
+
+memberFileChecks("cdk", '{"app": "npx ts-node bin/app.ts"}', '{"context": {}}');

package/src/workspace-member.test.ts

@@ -0,0 +1,94 @@
+/**
+ * The cloudformation member kind's graph block (#3179): the reader project the
+ * kind's graph config describes, run through chant graph over a fixture
+ * template. Nothing here calls AWS.
+ */
+import { afterEach, describe, expect, test, vi } from "vitest";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import type { GraphIR } from "@intentius/chant/graph-ir";
+import { runGraph } from "@intentius/chant/cli/handlers/graph";
+import { readPackageKinds, substituteGraphConfig } from "../../../packages/core/src/workspace/kinds";
+import { awsPlugin } from "./plugin";
+
+const here = dirname(fileURLToPath(import.meta.url));
+const packageDir = join(here, "..");
+const member = join(here, "testdata", "cfn-member");
+
+const scratch: string[] = [];
+afterEach(async () => {
+  vi.restoreAllMocks();
+  await Promise.all(scratch.splice(0).map((d) => rm(d, { recursive: true, force: true })));
+});
+
+async function graphOf(dir: string, kind = "cloudformation"): Promise<{ ir: GraphIR; err: string[]; exit: number }> {
+  const graph = readPackageKinds(packageDir).kinds.find((k) => k.name === kind)!.graph!;
+  expect(graph.lexicon).toBe("aws");
+  const config = substituteGraphConfig(graph.config, { member: "net", dir, workspace: dirname(dir) });
+  const project = await mkdtemp(join(tmpdir(), "chant-cfn-member-"));
+  scratch.push(project);
+  await writeFile(join(project, "chant.config.json"), JSON.stringify({ lexicons: ["aws"], aws: config, graph: { lint: "report" } }));
+  const out: string[] = [];
+  const err: string[] = [];
+  vi.spyOn(console, "log").mockImplementation((line: unknown) => void out.push(String(line)));
+  vi.spyOn(console, "error").mockImplementation((line: unknown) => void err.push(String(line)));
+  const cwd = process.cwd();
+  process.chdir(project);
+  try {
+    const exit = await runGraph({ args: { command: "graph", path: ".", format: "ir" } as never, plugins: [awsPlugin], serializers: [] });
+    return { ir: exit === 0 ? (JSON.parse(out.join("\n")) as GraphIR) : { nodes: [], edges: [], groups: {} }, err, exit };
+  } finally {
+    process.chdir(cwd);
+  }
+}
+
+describe("cloudformation member graph block (#3179)", () => {
+  test("a template's resources are nodes", async () => {
+    const { ir, err, exit } = await graphOf(member);
+    expect(exit, err.join("\n")).toBe(0);
+    expect(ir.nodes.map((n) => [n.id, n.kind]).sort()).toEqual([
+      ["net/Assets", "AWS::S3::Bucket"],
+      ["net/Db", "AWS::RDS::DBInstance"],
+      ["net/WebPolicy", "AWS::IAM::Policy"],
+      ["net/WebRole", "AWS::IAM::Role"],
+    ]);
+    expect(ir.meta?.awsMember).toEqual({ templates: ["stack.yaml"], objects: 4 });
+  });
+
+  test("Ref, GetAtt, Sub and DependsOn are edges; parameters and pseudo parameters are not", async () => {
+    const { ir } = await graphOf(member);
+    const edges = ir.edges.map((e) => `${e.from} -> ${e.to} via ${e.viaAttr}${e.toAttr ? ` (${e.toAttr})` : ""}`).sort();
+    expect(edges).toEqual([
+      "net/Db -> net/Assets via Tags (DomainName)",
+      "net/Db -> net/WebRole via DependsOn",
+      "net/WebPolicy -> net/Assets via PolicyDocument (Arn)",
+      "net/WebPolicy -> net/WebRole via Roles",
+    ]);
+  });
+});
+
+describe("cdk member graph block (#3179)", () => {
+  test("the synthesized assembly's templates are read; the app is not run", async () => {
+    const { ir, err, exit } = await graphOf(join(here, "testdata", "cdk-member"), "cdk");
+    expect(exit, err.join("\n")).toBe(0);
+    expect(ir.nodes.map((n) => n.id).sort()).toEqual(["net/HandlerGHI789", "net/HandlerRoleDEF456", "net/QueueABC123"]);
+    expect(ir.edges.map((e) => `${e.from} -> ${e.to} via ${e.viaAttr}`).sort()).toEqual([
+      "net/HandlerGHI789 -> net/HandlerRoleDEF456 via DependsOn",
+      "net/HandlerGHI789 -> net/HandlerRoleDEF456 via Role",
+      "net/HandlerGHI789 -> net/QueueABC123 via Environment",
+    ]);
+    expect(ir.meta?.awsMember).toEqual({ templates: ["AppStack.template.json"], objects: 3, synthesized: true });
+  });
+
+  test("an app with no assembly says synthesized: false and what to run", async () => {
+    const { ir, err, exit } = await graphOf(join(here, "testdata", "cdk-unsynthesized"), "cdk");
+    expect(exit, err.join("\n")).toBe(0);
+    expect(ir.nodes).toEqual([]);
+    const report = ir.meta?.awsMember as { synthesized: boolean; reason: string };
+    expect(report.synthesized).toBe(false);
+    expect(report.reason).toMatch(/cdk synth/);
+    expect(err.join("\n")).toMatch(/was not read/);
+  });
+});

package/src/workspace-member.ts

@@ -0,0 +1,197 @@
+/**
+ * Reading a cloudformation workspace member into the graph (#3179).
+ *
+ * `chant workspace graph` writes a reader project for a member of kind
+ * `cloudformation`, with `aws.member` in its config (see `workspace-kinds.json`).
+ * The plugin's `buildRoots` hook calls {@link readCloudFormationMember}: each
+ * CloudFormation template directly in the member's directory is parsed with the
+ * import parser's YAML schema (short-form tags included), and every resource
+ * becomes a node keyed `<label>/<LogicalId>`.
+ *
+ * Edges come from what the template says: `Ref`, `Fn::GetAtt` and the `${...}`
+ * references in `Fn::Sub`, wherever they sit in a resource's properties, plus
+ * `DependsOn`. Parameters, pseudo parameters and names that are not a resource
+ * of the same template (`AWS::Region`, an `Fn::ImportValue`) draw no edge.
+ * Nothing runs and no AWS call is made.
+ *
+ * A `cdk` member is read the same way from the cloud assembly its app already
+ * synthesized (`cdk.out`, or the `output` its cdk.json names): the assembly's
+ * `*.template.json` files are CloudFormation templates, and core's CDK
+ * assembly reader says whether the directory is one. chant does not run the
+ * app. With no assembly there is nothing to read, and the report says
+ * `synthesized: false` with the reason.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+import yaml from "js-yaml";
+import { DECLARABLE_MARKER, type Declarable } from "@intentius/chant/declarable";
+import type { EntityReference } from "@intentius/chant/graph-ir";
+import { isCloudAssembly } from "@intentius/chant/cdk/assembly";
+import { CF_SCHEMA } from "./import/parser";
+
+export interface AwsMemberConfig {
+  /** `cloudformation` (the default) or `cdk`. */
+  kind?: "cloudformation" | "cdk";
+  /** The member's directory, absolute. */
+  dir: string;
+  /** Names the entities (`<label>/Bucket`): the member's name. */
+  label?: string;
+}
+
+/** What the read found, carried on the graph's `meta.awsMember`. */
+export interface AwsMemberReport {
+  /** The template files read, relative to the member's directory (or its assembly's). */
+  templates: string[];
+  objects: number;
+  /** CDK only: false when the app has no synthesized assembly to read. */
+  synthesized?: boolean;
+  /** Why nothing was read; set with `synthesized: false`. */
+  reason?: string;
+}
+
+type Template = { Resources?: Record<string, { Type?: unknown; Properties?: Record<string, unknown>; DependsOn?: unknown }> };
+type Name = { id: string; attr?: string };
+
+function parseTemplate(text: string): Template | undefined {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    try {
+      parsed = yaml.load(text, { schema: CF_SCHEMA });
+    } catch {
+      return undefined;
+    }
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+  const t = parsed as Record<string, unknown>;
+  // The probe's two claims: a format version, or a Resources section.
+  const resources = t.Resources;
+  if (t.AWSTemplateFormatVersion === undefined && (!resources || typeof resources !== "object")) return undefined;
+  return t as Template;
+}
+
+/** Logical ids named by `${X}` and `${X.Attr}` in an `Fn::Sub` string, with the attribute when one is named. */
+function subReferences(text: string): Name[] {
+  const out: Name[] = [];
+  for (const m of text.matchAll(/\$\{([^}!][^}]*)\}/g)) {
+    const [id, ...rest] = m[1]!.trim().split(".");
+    if (id) out.push({ id, ...(rest.length ? { attr: rest.join(".") } : {}) });
+  }
+  return out;
+}
+
+/** Every name a value reaches through Ref, Fn::GetAtt or Fn::Sub. */
+function collectNames(value: unknown, out: Name[]): void {
+  if (Array.isArray(value)) {
+    for (const v of value) collectNames(v, out);
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  for (const [k, v] of Object.entries(value)) {
+    if (k === "Ref" && typeof v === "string") {
+      out.push({ id: v });
+    } else if (k === "Fn::GetAtt") {
+      const [id, attr] = Array.isArray(v) ? v : typeof v === "string" ? [v.slice(0, v.indexOf(".")), v.slice(v.indexOf(".") + 1)] : [];
+      if (typeof id === "string" && id) out.push({ id, ...(typeof attr === "string" && attr ? { attr } : {}) });
+    } else if (k === "Fn::Sub") {
+      const text = Array.isArray(v) ? v[0] : v;
+      if (typeof text === "string") out.push(...subReferences(text));
+      if (Array.isArray(v)) collectNames(v[1], out);
+    } else {
+      collectNames(v, out);
+    }
+  }
+}
+
+/** The directory a CDK app synthesizes into: cdk.json's `output`, else `cdk.out`. */
+function cdkOutput(dir: string): string {
+  try {
+    const output = (JSON.parse(readFileSync(join(dir, "cdk.json"), "utf-8")) as { output?: unknown }).output;
+    if (typeof output === "string" && output) return output;
+  } catch {
+    /* no readable cdk.json: the default */
+  }
+  return "cdk.out";
+}
+
+export function readCloudFormationMember(opts: { member: AwsMemberConfig }): {
+  entities: Map<string, Declarable>;
+  warnings: string[];
+  report: AwsMemberReport;
+} {
+  const { member } = opts;
+  const label = member.label ?? basename(member.dir);
+  const warnings: string[] = [];
+  const templates: Array<{ file: string; template: Template }> = [];
+  let source = member.dir;
+  if (member.kind === "cdk") {
+    source = join(member.dir, cdkOutput(member.dir));
+    if (!isCloudAssembly(source)) {
+      const reason = `no synthesized cloud assembly at ${source}; run \`cdk synth\` in the app, and chant will read the templates it writes`;
+      warnings.push(`cdk member "${label}" was not read: ${reason}`);
+      return { entities: new Map(), warnings, report: { templates: [], objects: 0, synthesized: false, reason } };
+    }
+  }
+  const pattern = member.kind === "cdk" ? /\.template\.json$/ : /\.(ya?ml|json|template)$/;
+  for (const file of readdirSync(source).filter((f) => pattern.test(f)).sort()) {
+    const template = parseTemplate(readFileSync(join(source, file), "utf-8"));
+    if (template) templates.push({ file, template });
+  }
+
+  const entities = new Map<string, Declarable>();
+  for (const { file, template } of templates) {
+    // One template per member is the usual case and keeps ids short; two share a directory, so the file name qualifies them.
+    const prefix = templates.length === 1 ? label : `${label}/${basename(file, extname(file)).replace(/\.template$/, "")}`;
+    const resources = Object.entries(template.Resources ?? {}).filter(([, r]) => typeof r?.Type === "string");
+    const keyOf = new Map(resources.map(([id]) => [id, `${prefix}/${id}`]));
+    for (const [id, resource] of resources) {
+      const references = new Map<string, EntityReference>();
+      const add = (name: Name, via: string) => {
+        const to = keyOf.get(name.id);
+        if (!to || to === keyOf.get(id)) return;
+        references.set(`${to}|${via}|${name.attr ?? ""}`, { to, viaAttr: via, ...(name.attr ? { toAttr: name.attr } : {}) });
+      };
+      for (const [prop, value] of Object.entries(resource.Properties ?? {})) {
+        const names: Name[] = [];
+        collectNames(value, names);
+        for (const n of names) add(n, prop);
+      }
+      const dependsOn = resource.DependsOn;
+      for (const d of Array.isArray(dependsOn) ? dependsOn : dependsOn === undefined ? [] : [dependsOn]) {
+        if (typeof d === "string") add({ id: d }, "DependsOn");
+      }
+      const entity = {
+        lexicon: "aws",
+        entityType: resource.Type as string,
+        kind: "resource",
+        props: { ...(resource.Properties ?? {}) },
+        references: [...references.values()],
+        [DECLARABLE_MARKER]: true,
+      } as unknown as Declarable;
+      entities.set(keyOf.get(id)!, entity);
+    }
+  }
+  if (templates.length === 0) warnings.push(`${member.kind ?? "cloudformation"} member "${label}" has no CloudFormation template directly in ${source}`);
+
+  return {
+    entities,
+    warnings,
+    report: { templates: templates.map((t) => t.file), objects: entities.size, ...(member.kind === "cdk" ? { synthesized: true } : {}) },
+  };
+}
+
+let lastReport: AwsMemberReport | undefined;
+
+/**
+ * The report of the read in this process. `graphMeta` receives only the
+ * entities, so the hook that read the member leaves its report here for the
+ * hook that publishes it; `chant graph` runs the two in order in one process.
+ */
+export function setLastMemberReport(report: AwsMemberReport | undefined): void {
+  lastReport = report;
+}
+
+export function lastMemberReport(): AwsMemberReport | undefined {
+  return lastReport;
+}

package/workspace-kinds.json

@@ -0,0 +1,66 @@
+{
+  "$comment": "Member kinds this lexicon supplies to a chant workspace (#3179). chant reads this file as data and never imports the lexicon. The cloudformation graph block (#3179) reads the template as data (src/workspace-member.ts). The cdk graph block reads the cloud assembly the app already synthesized (cdk.out, or the output cdk.json names) with the same template reader; chant never runs the app, and with no assembly the member says synthesized: false on meta.awsMember.",
+  "schema": 1,
+  "kinds": [
+    {
+      "name": "cloudformation",
+      "description": "a CloudFormation template: a YAML or JSON file with AWSTemplateFormatVersion or Resources at its top",
+      "precedence": 320,
+      "probe": {
+        "anyDocument": {
+          "in": [
+            "*.yaml",
+            "*.yml",
+            "*.json",
+            "*.template"
+          ],
+          "match": [
+            {
+              "/AWSTemplateFormatVersion": [
+                "*"
+              ]
+            },
+            {
+              "/Resources": [
+                "*"
+              ]
+            }
+          ]
+        }
+      },
+      "graph": {
+        "lexicon": "aws",
+        "config": {
+          "member": {
+            "dir": "{dir}",
+            "label": "{member}"
+          }
+        }
+      }
+    },
+    {
+      "name": "cdk",
+      "description": "an AWS CDK app, with a cdk.json in its directory",
+      "precedence": 315,
+      "probe": {
+        "anyFile": [
+          "cdk.json"
+        ]
+      },
+      "memberFile": {
+        "path": "cdk.json",
+        "schema": "schemas/cdk.schema.json"
+      },
+      "graph": {
+        "lexicon": "aws",
+        "config": {
+          "member": {
+            "kind": "cdk",
+            "dir": "{dir}",
+            "label": "{member}"
+          }
+        }
+      }
+    }
+  ]
+}