@intentius/behold 0.17.0 → 0.19.0

package/example-choudoufu-estate/team-c/behaviour.live.json

@@ -0,0 +1,179 @@
+{
+  "meta": {
+    "engine": "behold-fixture",
+    "version": "0",
+    "at": {
+      "traffic": "100 rps, p50"
+    }
+  },
+  "entities": {
+    "aws_iam_role.team_c": {
+      "at": {
+        "traffic": "100 rps, p50"
+      },
+      "cost": {
+        "perHour": 0.0004,
+        "currency": "USD"
+      },
+      "headroom": {
+        "cpu": 0.9,
+        "latency": 0.85
+      },
+      "errorRate": 0.001,
+      "resilience": {
+        "failure": "one zone lost",
+        "verdict": "survives"
+      },
+      "provenance": {
+        "engine": "behold-fixture",
+        "version": "0",
+        "tolerance": "fixture",
+        "basis": "modeled"
+      }
+    },
+    "aws_iam_role_policy.team_c_inline": {
+      "at": {
+        "traffic": "100 rps, p50"
+      },
+      "cost": {
+        "perHour": 0.0002,
+        "currency": "USD"
+      },
+      "headroom": {
+        "cpu": 0.84,
+        "latency": 0.76
+      },
+      "errorRate": 0.001,
+      "resilience": {
+        "failure": "one zone lost",
+        "verdict": "survives"
+      },
+      "provenance": {
+        "engine": "behold-fixture",
+        "version": "0",
+        "tolerance": "fixture",
+        "basis": "modeled"
+      }
+    },
+    "aws_iam_policy.team_c": {
+      "at": {
+        "traffic": "100 rps, p50"
+      },
+      "cost": {
+        "perHour": 0.0002,
+        "currency": "USD"
+      },
+      "headroom": {
+        "cpu": 0.78,
+        "latency": 0.67
+      },
+      "errorRate": 0.001,
+      "resilience": {
+        "failure": "one zone lost",
+        "verdict": "survives"
+      },
+      "provenance": {
+        "engine": "behold-fixture",
+        "version": "0",
+        "tolerance": "fixture",
+        "basis": "modeled"
+      }
+    },
+    "aws_iam_role_policy_attachment.team_c": {
+      "at": {
+        "traffic": "100 rps, p50"
+      },
+      "cost": {
+        "perHour": 0.0001,
+        "currency": "USD"
+      },
+      "headroom": {
+        "cpu": 0.72,
+        "latency": 0.58
+      },
+      "errorRate": 0.001,
+      "resilience": {
+        "failure": "one zone lost",
+        "verdict": "survives"
+      },
+      "provenance": {
+        "engine": "behold-fixture",
+        "version": "0",
+        "tolerance": "fixture",
+        "basis": "modeled"
+      }
+    },
+    "aws_cloudwatch_log_group.team_c_0": {
+      "at": {
+        "traffic": "100 rps, p50"
+      },
+      "cost": {
+        "perHour": 0.0416,
+        "currency": "USD"
+      },
+      "headroom": {
+        "cpu": 0.66,
+        "latency": 0.49
+      },
+      "errorRate": 0.0004,
+      "resilience": {
+        "failure": "one zone lost",
+        "verdict": "survives"
+      },
+      "provenance": {
+        "engine": "behold-fixture",
+        "version": "0",
+        "tolerance": "fixture",
+        "basis": "modeled"
+      }
+    },
+    "aws_cloudwatch_log_group.team_c_1": {
+      "at": {
+        "traffic": "100 rps, p50"
+      },
+      "cost": {
+        "perHour": 0.0312,
+        "currency": "USD"
+      },
+      "headroom": {
+        "cpu": 0.6,
+        "latency": 0.85
+      },
+      "errorRate": 0.0004,
+      "resilience": {
+        "failure": "one zone lost",
+        "verdict": "survives"
+      },
+      "provenance": {
+        "engine": "behold-fixture",
+        "version": "0",
+        "tolerance": "fixture",
+        "basis": "modeled"
+      }
+    },
+    "aws_cloudwatch_log_group.team_c_2": {
+      "at": {
+        "traffic": "100 rps, p50"
+      },
+      "cost": {
+        "perHour": 0.0208,
+        "currency": "USD"
+      },
+      "headroom": {
+        "cpu": 0.54,
+        "latency": 0.76
+      },
+      "errorRate": 0.0004,
+      "resilience": {
+        "failure": "one zone lost",
+        "verdict": "survives"
+      },
+      "provenance": {
+        "engine": "behold-fixture",
+        "version": "0",
+        "tolerance": "fixture",
+        "basis": "modeled"
+      }
+    }
+  }
+}

package/example-choudoufu-estate/team-c/main.tf

@@ -0,0 +1,51 @@
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "= 6.58.0"
+    }
+  }
+  live {
+    estate = "tlmig-sample-team-c"
+  }
+}
+
+provider "aws" {
+  region = "us-east-1"
+}
+
+resource "aws_iam_role" "team_c" {
+  name               = "tlmig-sample-team-c-role"
+  assume_role_policy = jsonencode({ Version = "2012-10-17", Statement = [{ Effect = "Allow", Principal = { Service = "ec2.amazonaws.com" }, Action = "sts:AssumeRole" }] })
+}
+
+resource "aws_iam_role_policy" "team_c_inline" {
+  name   = "tlmig-sample-team-c-inline"
+  role   = aws_iam_role.team_c.id
+  policy = jsonencode({ Version = "2012-10-17", Statement = [{ Effect = "Allow", Action = ["logs:CreateLogStream"], Resource = "*" }] })
+}
+
+resource "aws_iam_policy" "team_c" {
+  name   = "tlmig-sample-team-c-policy"
+  policy = jsonencode({ Version = "2012-10-17", Statement = [{ Effect = "Allow", Action = ["logs:PutLogEvents"], Resource = "*" }] })
+}
+
+resource "aws_iam_role_policy_attachment" "team_c" {
+  role       = aws_iam_role.team_c.name
+  policy_arn = aws_iam_policy.team_c.arn
+}
+
+resource "aws_cloudwatch_log_group" "team_c_0" {
+  name              = "/tlmig-sample/team-c/svc-0"
+  retention_in_days = 1
+}
+
+resource "aws_cloudwatch_log_group" "team_c_1" {
+  name              = "/tlmig-sample/team-c/svc-1"
+  retention_in_days = 1
+}
+
+resource "aws_cloudwatch_log_group" "team_c_2" {
+  name              = "/tlmig-sample/team-c/svc-2"
+  retention_in_days = 1
+}

package/example-flux-estate/package-lock.json

@@ -561,9 +561,9 @@
       }
     },
     "node_modules/@kubernetes/client-node/node_modules/js-yaml": {
-      "version": "5.4.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-5.4.1.tgz",
-      "integrity": "sha512-28R/k+NAjeuf7+CKlTxWZVExJGwVVLwY06DgEnOMz2gEpfNkDcD7QvyiVPT0xy0XXhU8vHsd4Ot42OOPdJG7dQ==",
+      "version": "5.4.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-5.4.2.tgz",
+      "integrity": "sha512-m+aqu+LwO1O6sIopafj8HUVl5aawITwZQe/yHpMCKjaWBaA/d07B/QdMb3529REftiU+RMMHL3Vlsw3hON7vWg==",
       "funding": [
         {
           "type": "github",
@@ -1113,9 +1113,9 @@
       }
     },
     "node_modules/js-yaml": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
-      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz",
+      "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==",
       "funding": [
         {
           "type": "github",

package/example-k8s/package-lock.json

@@ -555,9 +555,9 @@
       }
     },
     "node_modules/@kubernetes/client-node/node_modules/js-yaml": {
-      "version": "5.4.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-5.4.1.tgz",
-      "integrity": "sha512-28R/k+NAjeuf7+CKlTxWZVExJGwVVLwY06DgEnOMz2gEpfNkDcD7QvyiVPT0xy0XXhU8vHsd4Ot42OOPdJG7dQ==",
+      "version": "5.4.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-5.4.2.tgz",
+      "integrity": "sha512-m+aqu+LwO1O6sIopafj8HUVl5aawITwZQe/yHpMCKjaWBaA/d07B/QdMb3529REftiU+RMMHL3Vlsw3hON7vWg==",
       "funding": [
         {
           "type": "github",
@@ -1187,9 +1187,9 @@
       }
     },
     "node_modules/js-yaml": {
-      "version": "4.3.1",
-      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.1.tgz",
-      "integrity": "sha512-CY6crGq313MX8GkwvB7tzgp99vjQxY1++5y10/BKN/GUfHqWaOGQMNZkBvqSzsZKWk/ijwHlWzzkLulsGHhjWQ==",
+      "version": "4.3.2",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz",
+      "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==",
       "funding": [
         {
           "type": "github",

package/example-terraform-estate/README.md

@@ -0,0 +1,109 @@
+# example-terraform-estate
+
+A multi-root Terraform estate, declared only. No cloud account, no Docker, no
+`terraform` binary — behold reads the HCL through chant's terraform lexicon and
+draws what it finds.
+
+```sh
+npx @intentius/behold demo terraform-estate
+```
+
+## What it declares
+
+Two roots that are applied separately, plus the shared module both are built
+on. 25 resources, drawing 37 cards and 31 edges at the `resources` zoom.
+
+| directory | what it is |
+|---|---|
+| `envs/prod` | The environment root: a VPC with three subnets, a route table and an edge security group, an artifacts bucket with its versioning/public-access/encryption siblings, and two calls to the shared service module. |
+| `platform` | The estate-wide root, applied separately: the permissions boundary every service role attaches, a deploy role, the KMS key and alias, an audit log group. It declares **no provider block** — it inherits one where it is used. |
+| `modules/service` | The shared module `envs/prod` calls twice. An IAM role and inline policy, a log group, a work queue with its dead-letter queue, a task security group. |
+| `backends` | A backend fragment, copied into a root when one is initialised. |
+| `envs/dev` | Not built yet. A README and no `.tf`. |
+
+## What each directory is there to show
+
+Discovery has to tell five things apart, and this estate is built to be each of
+them. A root is a directory with a `.tf` declaring a line-start `terraform {` or
+`provider "` block beside a `resource`, `data` or `module` block — a regex probe
+at depth, never an HCL parse.
+
+**`envs/prod` is the obvious root.** Provider block, resources, module calls.
+
+**`platform` is the root that has no provider block.** The naive reading of "a
+root configures a provider" would miss it. It is a root because it declares
+resources beside a `terraform` block, and it is applied on its own.
+
+**`modules/service` is the case that defeats the probe.** Its `versions.tf` is
+byte-for-byte `envs/prod/versions.tf` — the same `required_version`, the same
+`required_providers`. Nothing in the file's content says which of the two is a
+root. What separates them is that this one sits under a `modules/` segment,
+Terraform's own standard module structure, and the roots that call it draw its
+blocks already. Drawing it again would double every card in it.
+
+**`backends` has a `terraform` block and nothing to draw.** No resource, no
+data source, no module call. It is reported as skipped rather than drawn as an
+empty box — a box with nothing in it is a question, and the note answers it.
+
+**`envs/dev` is neither drawn nor reported.** It holds no `.tf` at all, so
+there is nothing here that looks like Terraform and nothing to say about it.
+Silence is the right answer; reporting it would be noise about every directory
+in every repository.
+
+The graph's status line says all of this:
+
+```
+2 roots — prod, platform; skipped backends (no resource, data or module block —
+nothing to draw), modules/service (called as a module, never applied on its own)
+```
+
+## The edge that is not drawn
+
+`platform` declares the KMS key and its alias. `envs/prod` reads it back:
+
+```hcl
+data "aws_kms_key" "estate" {
+  key_id = "alias/${var.name}-estate"
+}
+```
+
+That is a real cross-root reference, and it is how a multi-root estate is
+actually wired — two roots applied separately, neither a module of the other,
+joined by a name one publishes and the other looks up.
+
+**behold draws no edge for it**, and that is deliberate. Both ends carry the
+same unresolved `${var.name}` interpolation, so matching them would be a
+coincidence of variable naming rather than a relationship either root states.
+It was measured on a real estate and refused ([#381]). The data source card says
+what it reads instead, which is a claim the estate does make.
+
+Module calls *do* draw: each `module` block expands into its own contents under
+`module.checkout/…`, with the reference edges chant's lexicon resolves from the
+HCL.
+
+## It needs the lexicon
+
+behold parses no HCL and ships no HCL parser. The reading goes through
+`@intentius/chant-lexicon-terraform`, which loads `@cdktf/hcl2json` underneath —
+a ~1.8 MB wasm blob. Both are declared as optional peers and behold does not
+install them, so that every user who serves an ordinary chant project does not
+carry an HCL parser they will never run:
+
+```sh
+npm install --no-save @intentius/chant-lexicon-terraform @cdktf/hcl2json
+```
+
+Without them the demo refuses with that exact line and says where it looked.
+
+## Not the carve demo
+
+`behold demo carve` also involves Terraform and answers a different question.
+This estate asks **what is in my Terraform** — draw it, box it by root, tell the
+roots from the modules. The carve demo asks **what would it cost to leave**:
+`chant carve advise` ranks each resource by peelability and the walkthrough
+carves one across the line.
+
+Nothing here is being migrated. There is no chant project beside it, no
+peelability score on any card, and no stepper.
+
+[#381]: https://github.com/INTENTIUS/behold/issues/381

package/example-terraform-estate/backends/backend.s3.tf

@@ -0,0 +1,10 @@
+# A backend fragment, copied into a root when one is initialised. It declares
+# a `terraform` block and nothing to draw, which is why discovery reports it as
+# skipped rather than drawing an empty box for it.
+terraform {
+  backend "s3" {
+    bucket = "waterline-tfstate"
+    key    = "prod/terraform.tfstate"
+    region = "us-east-1"
+  }
+}

package/example-terraform-estate/envs/dev/README.md

@@ -0,0 +1,5 @@
+# envs/dev
+
+Not built yet. This directory holds no `.tf` at all, which is why discovery
+neither draws it nor reports it as skipped: there is nothing here that looks
+like Terraform, so there is nothing to say about it.

package/example-terraform-estate/envs/prod/data.tf

@@ -0,0 +1,18 @@
+data "aws_caller_identity" "current" {}
+
+data "aws_region" "current" {}
+
+# The cross-root read, and what behold does with it.
+#
+# `platform` declares this key and its alias; this root reads it back by alias
+# rather than by a reference Terraform could resolve, because the two roots are
+# applied separately and neither is a module of the other. That is how a real
+# multi-root estate is wired, and it is also why NO EDGE is drawn between them:
+# both ends carry the same unresolved `${var.name}` interpolation, so a match
+# would be a coincidence of variable naming rather than a stated relationship.
+# behold measured that and refused it (INTENTIUS/behold#381). What you get
+# instead is this card, saying exactly what it reads — which is a claim the
+# estate actually makes.
+data "aws_kms_key" "estate" {
+  key_id = "alias/${var.name}-estate"
+}

package/example-terraform-estate/envs/prod/network.tf

@@ -0,0 +1,80 @@
+resource "aws_vpc" "main" {
+  cidr_block           = var.vpc_cidr
+  enable_dns_hostnames = true
+  enable_dns_support   = true
+
+  tags = { Name = "${var.name}-vpc" }
+}
+
+resource "aws_internet_gateway" "main" {
+  vpc_id = aws_vpc.main.id
+
+  tags = { Name = "${var.name}-igw" }
+}
+
+resource "aws_subnet" "public_a" {
+  vpc_id                  = aws_vpc.main.id
+  cidr_block              = cidrsubnet(var.vpc_cidr, 8, 0)
+  availability_zone       = "${var.region}a"
+  map_public_ip_on_launch = true
+
+  tags = { Name = "${var.name}-public-a" }
+}
+
+resource "aws_subnet" "public_b" {
+  vpc_id                  = aws_vpc.main.id
+  cidr_block              = cidrsubnet(var.vpc_cidr, 8, 1)
+  availability_zone       = "${var.region}b"
+  map_public_ip_on_launch = true
+
+  tags = { Name = "${var.name}-public-b" }
+}
+
+resource "aws_subnet" "private_a" {
+  vpc_id            = aws_vpc.main.id
+  cidr_block        = cidrsubnet(var.vpc_cidr, 8, 10)
+  availability_zone = "${var.region}a"
+
+  tags = { Name = "${var.name}-private-a" }
+}
+
+resource "aws_route_table" "public" {
+  vpc_id = aws_vpc.main.id
+
+  route {
+    cidr_block = "0.0.0.0/0"
+    gateway_id = aws_internet_gateway.main.id
+  }
+
+  tags = { Name = "${var.name}-public" }
+}
+
+resource "aws_route_table_association" "public_a" {
+  subnet_id      = aws_subnet.public_a.id
+  route_table_id = aws_route_table.public.id
+}
+
+resource "aws_route_table_association" "public_b" {
+  subnet_id      = aws_subnet.public_b.id
+  route_table_id = aws_route_table.public.id
+}
+
+resource "aws_security_group" "edge" {
+  name        = "${var.name}-edge"
+  description = "Ingress for the public tier."
+  vpc_id      = aws_vpc.main.id
+
+  ingress {
+    from_port   = 443
+    to_port     = 443
+    protocol    = "tcp"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}

package/example-terraform-estate/envs/prod/outputs.tf

@@ -0,0 +1,13 @@
+output "vpc_id" {
+  description = "The network everything in this environment sits in."
+  value       = aws_vpc.main.id
+}
+
+output "artifacts_bucket" {
+  value = aws_s3_bucket.artifacts.bucket
+}
+
+output "service_role_arns" {
+  description = "One per service module, for the platform root to reference back."
+  value       = [module.checkout.role_arn, module.ledger.role_arn]
+}

package/example-terraform-estate/envs/prod/provider.tf

@@ -0,0 +1,10 @@
+provider "aws" {
+  region = var.region
+
+  default_tags {
+    tags = {
+      Estate      = "waterline"
+      Environment = "prod"
+    }
+  }
+}

package/example-terraform-estate/envs/prod/services.tf

@@ -0,0 +1,21 @@
+module "checkout" {
+  source = "../../modules/service"
+
+  name            = "${var.name}-checkout"
+  subnet_ids      = [aws_subnet.private_a.id]
+  boundary_arn    = data.aws_iam_policy.boundary.arn
+  log_kms_key_arn = data.aws_kms_key.estate.arn
+}
+
+module "ledger" {
+  source = "../../modules/service"
+
+  name            = "${var.name}-ledger"
+  subnet_ids      = [aws_subnet.private_a.id]
+  boundary_arn    = data.aws_iam_policy.boundary.arn
+  log_kms_key_arn = data.aws_kms_key.estate.arn
+}
+
+data "aws_iam_policy" "boundary" {
+  name = "${var.name}-boundary"
+}

package/example-terraform-estate/envs/prod/storage.tf

@@ -0,0 +1,31 @@
+resource "aws_s3_bucket" "artifacts" {
+  bucket = "${var.name}-artifacts"
+}
+
+resource "aws_s3_bucket_versioning" "artifacts" {
+  bucket = aws_s3_bucket.artifacts.id
+
+  versioning_configuration {
+    status = "Enabled"
+  }
+}
+
+resource "aws_s3_bucket_public_access_block" "artifacts" {
+  bucket = aws_s3_bucket.artifacts.id
+
+  block_public_acls       = true
+  block_public_policy     = true
+  ignore_public_acls      = true
+  restrict_public_buckets = true
+}
+
+resource "aws_s3_bucket_server_side_encryption_configuration" "artifacts" {
+  bucket = aws_s3_bucket.artifacts.id
+
+  rule {
+    apply_server_side_encryption_by_default {
+      sse_algorithm     = "aws:kms"
+      kms_master_key_id = data.aws_kms_key.estate.arn
+    }
+  }
+}

package/example-terraform-estate/envs/prod/variables.tf

@@ -0,0 +1,17 @@
+variable "region" {
+  description = "The region every resource in this root is created in."
+  type        = string
+  default     = "us-east-1"
+}
+
+variable "name" {
+  description = "Prefix for every resource this root names."
+  type        = string
+  default     = "waterline-prod"
+}
+
+variable "vpc_cidr" {
+  description = "The network this environment sits in."
+  type        = string
+  default     = "10.40.0.0/16"
+}

package/example-terraform-estate/envs/prod/versions.tf

@@ -0,0 +1,10 @@
+terraform {
+  required_version = ">= 1.9.0"
+
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 6.0"
+    }
+  }
+}

package/example-terraform-estate/modules/service/main.tf

@@ -0,0 +1,58 @@
+resource "aws_iam_role" "this" {
+  name                 = "${var.name}-role"
+  permissions_boundary = var.boundary_arn
+
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect    = "Allow"
+      Principal = { Service = "ecs-tasks.amazonaws.com" }
+      Action    = "sts:AssumeRole"
+    }]
+  })
+}
+
+resource "aws_iam_role_policy" "this" {
+  name = "${var.name}-inline"
+  role = aws_iam_role.this.id
+
+  policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [{
+      Effect   = "Allow"
+      Action   = ["sqs:ReceiveMessage", "sqs:DeleteMessage", "sqs:GetQueueAttributes"]
+      Resource = aws_sqs_queue.work.arn
+    }]
+  })
+}
+
+resource "aws_cloudwatch_log_group" "this" {
+  name              = "/service/${var.name}"
+  retention_in_days = 14
+  kms_key_id        = var.log_kms_key_arn
+}
+
+resource "aws_sqs_queue" "work" {
+  name                       = "${var.name}-work"
+  visibility_timeout_seconds = 60
+  redrive_policy = jsonencode({
+    deadLetterTargetArn = aws_sqs_queue.dead.arn
+    maxReceiveCount     = 5
+  })
+}
+
+resource "aws_sqs_queue" "dead" {
+  name = "${var.name}-dead"
+}
+
+resource "aws_security_group" "task" {
+  name        = "${var.name}-task"
+  description = "Egress only; the task reaches the queue and the log group."
+
+  egress {
+    from_port   = 0
+    to_port     = 0
+    protocol    = "-1"
+    cidr_blocks = ["0.0.0.0/0"]
+  }
+}