@intentius/chant-lexicon-render 0.53.0

package/src/generated/lexicon-render.json

@@ -0,0 +1,304 @@
+{
+  "Autoscaling": {
+    "resourceType": "Render::Services::Autoscaling",
+    "kind": "property",
+    "lexicon": "render",
+    "constraints": {
+      "enabled": {
+        "default": false
+      }
+    }
+  },
+  "AutoscalingCriteria": {
+    "resourceType": "Render::Services::AutoscalingCriteria",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "AutoscalingCriterion": {
+    "resourceType": "Render::Services::AutoscalingCriterion",
+    "kind": "property",
+    "lexicon": "render",
+    "constraints": {
+      "enabled": {
+        "default": false
+      }
+    }
+  },
+  "BackgroundWorker": {
+    "resourceType": "Render::Services::BackgroundWorker",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "BackgroundWorkerDetails": {
+    "resourceType": "Render::Services::BackgroundWorkerDetails",
+    "kind": "property",
+    "lexicon": "render",
+    "constraints": {
+      "numInstances": {
+        "minimum": 1,
+        "default": 1
+      }
+    }
+  },
+  "BuildFilter": {
+    "resourceType": "Render::Services::BuildFilter",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "CidrBlockAndDescription": {
+    "resourceType": "Render::Services::CidrBlockAndDescription",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "CronJob": {
+    "resourceType": "Render::Services::CronJob",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "CronJobDetails": {
+    "resourceType": "Render::Services::CronJobDetails",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "CustomDomain": {
+    "resourceType": "Render::Services::CustomDomain",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "Disk": {
+    "resourceType": "Render::Services::Disk",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "DockerDetails": {
+    "resourceType": "Render::Services::DockerDetails",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "EnvGroup": {
+    "resourceType": "Render::Config::EnvGroup",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "EnvVar": {
+    "resourceType": "Render::Services::EnvVar",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "Environment": {
+    "resourceType": "Render::Projects::Environment",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "GeneratedEnvVar": {
+    "resourceType": "Render::Services::GeneratedEnvVar",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "Header": {
+    "resourceType": "Render::Services::Header",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "Image": {
+    "resourceType": "Render::Services::Image",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "KeyValue": {
+    "resourceType": "Render::Datastores::KeyValue",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "MaintenanceMode": {
+    "resourceType": "Render::Services::MaintenanceMode",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "NativeEnvironmentDetails": {
+    "resourceType": "Render::Services::NativeEnvironmentDetails",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "Postgres": {
+    "resourceType": "Render::Datastores::Postgres",
+    "kind": "resource",
+    "lexicon": "render",
+    "constraints": {
+      "databaseName": {
+        "default": "randomly generated"
+      },
+      "databaseUser": {
+        "default": "randomly generated"
+      },
+      "enableHighAvailability": {
+        "default": false
+      },
+      "plan": {
+        "enum": [
+          "free",
+          "starter",
+          "standard",
+          "pro",
+          "pro_plus",
+          "custom",
+          "basic_256mb",
+          "basic_1gb",
+          "basic_4gb",
+          "pro_4gb",
+          "pro_8gb",
+          "pro_16gb",
+          "pro_32gb",
+          "pro_64gb",
+          "pro_128gb",
+          "pro_192gb",
+          "pro_256gb",
+          "pro_384gb",
+          "pro_512gb",
+          "accelerated_16gb",
+          "accelerated_32gb",
+          "accelerated_64gb",
+          "accelerated_128gb",
+          "accelerated_256gb",
+          "accelerated_384gb",
+          "accelerated_512gb",
+          "accelerated_768gb",
+          "accelerated_1024gb",
+          "0.1c-256mb",
+          "0.5c-1g",
+          "1c-2g",
+          "1c-4g",
+          "2c-4g",
+          "2c-8g",
+          "2c-16g",
+          "4c-16g",
+          "4c-32g",
+          "8c-32g",
+          "8c-64g",
+          "16c-64g",
+          "16c-128g",
+          "32c-128g",
+          "32c-256g",
+          "48c-192g",
+          "48c-384g",
+          "64c-256g",
+          "64c-512g",
+          "96c-384g",
+          "96c-768g",
+          "128c-512g",
+          "128c-1024g"
+        ]
+      },
+      "enableDiskAutoscaling": {
+        "default": false
+      },
+      "connectionPool": {
+        "default": "none"
+      }
+    }
+  },
+  "Previews": {
+    "resourceType": "Render::Services::Previews",
+    "kind": "property",
+    "lexicon": "render",
+    "constraints": {
+      "generation": {
+        "default": "off",
+        "enum": [
+          "off",
+          "manual",
+          "automatic"
+        ]
+      }
+    }
+  },
+  "PrivateService": {
+    "resourceType": "Render::Services::PrivateService",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "PrivateServiceDetails": {
+    "resourceType": "Render::Services::PrivateServiceDetails",
+    "kind": "property",
+    "lexicon": "render",
+    "constraints": {
+      "numInstances": {
+        "minimum": 1,
+        "default": 1
+      }
+    }
+  },
+  "Project": {
+    "resourceType": "Render::Projects::Project",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "ProjectEnvironment": {
+    "resourceType": "Render::Services::ProjectEnvironment",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "ReadReplica": {
+    "resourceType": "Render::Services::ReadReplica",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "RegistryCredential": {
+    "resourceType": "Render::Config::RegistryCredential",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "Route": {
+    "resourceType": "Render::Services::Route",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "SecretFile": {
+    "resourceType": "Render::Services::SecretFile",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "ServiceDisk": {
+    "resourceType": "Render::Services::ServiceDisk",
+    "kind": "property",
+    "lexicon": "render",
+    "constraints": {
+      "sizeGB": {
+        "minimum": 1
+      }
+    }
+  },
+  "StaticSite": {
+    "resourceType": "Render::Services::StaticSite",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "StaticSiteDetails": {
+    "resourceType": "Render::Services::StaticSiteDetails",
+    "kind": "property",
+    "lexicon": "render"
+  },
+  "WebService": {
+    "resourceType": "Render::Services::WebService",
+    "kind": "resource",
+    "lexicon": "render"
+  },
+  "WebServiceDetails": {
+    "resourceType": "Render::Services::WebServiceDetails",
+    "kind": "property",
+    "lexicon": "render",
+    "constraints": {
+      "numInstances": {
+        "minimum": 1
+      },
+      "plan": {
+        "default": "0.5c-512mb"
+      }
+    }
+  },
+  "Webhook": {
+    "resourceType": "Render::Config::Webhook",
+    "kind": "resource",
+    "lexicon": "render"
+  }
+}

package/src/generated/runtime.ts

@@ -0,0 +1,4 @@
+/**
+ * Runtime factory constructors — re-exported from core.
+ */
+export { createResource, createProperty } from "@intentius/chant/runtime";

package/src/index.ts

@@ -0,0 +1,30 @@
+// Plugin
+export { renderPlugin } from "./plugin";
+
+// Serializer (+ the marker shapes the applier resolves)
+export { renderSerializer, isRefMarker, isAttrMarker, isOwnerMarker } from "./serializer";
+export type { RenderPlan, RenderRequest, RefMarker, AttrMarker, OwnerMarker } from "./serializer";
+
+// Pseudo-parameters — environment-resolved values (`Render.OwnerId`,
+// `Render.Region`) usable in place of hard-coded strings.
+export { Render, OwnerId, Region, PseudoParameter } from "./pseudo";
+
+// Ownership marker convention (env-var keys on services and env groups)
+export { RENDER_ENV_OWNERSHIP_KEYS } from "./ownership";
+
+// The resource catalog: entity type → REST collection, identity, ordering.
+export { CATALOG, ENTITY_TYPES, SERVICE_TYPE_OF, catalogEntry, isServiceEntityType } from "./catalog";
+export type { CatalogEntry, EntityType } from "./catalog";
+
+// Deploy Op composite + typed step builders. `renderDeploy` returns a
+// `build → renderApply [→ verify] [→ teardown]` Op; the step builders wrap the
+// generic `activity()` so the render activities resolve by name.
+export { renderDeploy, renderApplyStep, renderDeleteStep } from "./composites/render-deploy";
+export type { RenderDeployOpts, RenderApplyStepOpts } from "./composites/render-deploy";
+
+// Generated resources — export everything from generated index.
+// Provides `WebService`, `StaticSite`, `PrivateService`, `BackgroundWorker`,
+// `CronJob`, `Postgres`, `KeyValue`, `EnvGroup`, `Project`, `Environment`,
+// `Disk`, `CustomDomain`, `RegistryCredential`, `Webhook`, and the property
+// types (`WebServiceDetails`, `Image`, `ServiceDisk`, ...) for authoring.
+export * from "./generated/index";

package/src/lint/audit-catalog.ts

@@ -0,0 +1,47 @@
+/**
+ * The render lexicon's chant audit catalog — metadata for the REN post-synth
+ * checks, contributed via `renderPlugin.auditCatalog()`.
+ *
+ * All entries carry `yamlBased: false`: each check reads the chant model
+ * (`ctx.entities`) rather than the emitted plan, because what they need — the
+ * runtime, the plan tier, whether a source was named — lives in the typed
+ * graph. So they fire on `chant build` and cannot fire on an audit of a
+ * standalone Render config.
+ */
+
+import type { RuleMeta } from "@intentius/chant/audit/catalog";
+
+/** Entity-based rule: everything render ships. */
+function rule(
+  id: string,
+  tier: RuleMeta["tier"],
+  category: RuleMeta["category"],
+  title: string,
+  remediation: string,
+): RuleMeta {
+  return { id, tier, fixKind: "guidance", category, title, remediation, yamlBased: false };
+}
+
+export const renderAuditCatalog: Record<string, RuleMeta> = {
+  REN010: rule(
+    "REN010",
+    "merge-worthy",
+    "correctness",
+    "Native-runtime service has no build/start command",
+    "Set `envSpecificDetails: new NativeEnvironmentDetails({ buildCommand, startCommand })` on the service.",
+  ),
+  REN011: rule(
+    "REN011",
+    "merge-worthy",
+    "correctness",
+    "Service has no source (repo or image)",
+    "Set `repo` for a git-backed service, or `image: new Image({ imagePath })` for an image-backed one.",
+  ),
+  REN012: rule(
+    "REN012",
+    "merge-worthy",
+    "correctness",
+    "Free-plan service configured to scale or mount a disk",
+    "Move the service to a paid instance type, or drop numInstances/autoscaling/disk.",
+  ),
+};

package/src/lint/post-synth/index.ts

@@ -0,0 +1,11 @@
+// Code generated by chant generate. DO NOT EDIT.
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+import { ren010 } from "./ren010-native-runtime-requires-commands";
+import { ren011 } from "./ren011-service-requires-source";
+import { ren012 } from "./ren012-free-plan-cannot-scale";
+
+export const postSynthChecks: PostSynthCheck[] = [
+  ren010,
+  ren011,
+  ren012,
+];

package/src/lint/post-synth/post-synth.test.ts

@@ -0,0 +1,151 @@
+import { describe, test, expect } from "vitest";
+import type { Declarable } from "@intentius/chant";
+import type { PostSynthContext } from "@intentius/chant/lint/post-synth";
+import { ren010 } from "./ren010-native-runtime-requires-commands";
+import { ren011 } from "./ren011-service-requires-source";
+import { ren012 } from "./ren012-free-plan-cannot-scale";
+import { postSynthChecks } from "./index";
+import {
+  WebService,
+  WebServiceDetails,
+  NativeEnvironmentDetails,
+  DockerDetails,
+  StaticSite,
+  StaticSiteDetails,
+  Image,
+  ServiceDisk,
+  Postgres,
+} from "../../generated/index";
+
+function ctx(...entries: Array<[string, unknown]>): PostSynthContext {
+  const entities = new Map(entries as Array<[string, Declarable]>);
+  return {
+    outputs: new Map(),
+    entities,
+    buildResult: { outputs: new Map(), entities, warnings: [], errors: [], sourceFileCount: 1 },
+  };
+}
+
+const REPO = "https://github.com/render-examples/express-hello-world";
+
+describe("render post-synth checks", () => {
+  test("the barrel exports the three checks", () => {
+    expect(postSynthChecks.map((c) => c.id)).toEqual(["REN010", "REN011", "REN012"]);
+  });
+
+  describe("REN010: native runtime requires build/start commands", () => {
+    test("flags a node service with no envSpecificDetails", () => {
+      const diags = ren010.check(ctx(["web", new WebService({ name: "web", repo: REPO, serviceDetails: new WebServiceDetails({ runtime: "node" }) })]));
+      expect(diags).toHaveLength(1);
+      expect(diags[0].checkId).toBe("REN010");
+      expect(diags[0].severity).toBe("error");
+      expect(diags[0].message).toContain("buildCommand or startCommand");
+    });
+
+    test("passes a node service with both commands (instance and inline forms)", () => {
+      expect(
+        ren010.check(
+          ctx([
+            "web",
+            new WebService({
+              name: "web",
+              repo: REPO,
+              serviceDetails: new WebServiceDetails({
+                runtime: "node",
+                envSpecificDetails: new NativeEnvironmentDetails({ buildCommand: "npm ci", startCommand: "npm start" }),
+              }),
+            }),
+          ]),
+        ),
+      ).toHaveLength(0);
+      expect(
+        ren010.check(
+          ctx([
+            "web",
+            new WebService({
+              name: "web",
+              repo: REPO,
+              serviceDetails: { runtime: "python", envSpecificDetails: { buildCommand: "pip install -r requirements.txt", startCommand: "gunicorn app:app" } } as unknown as InstanceType<typeof WebServiceDetails>,
+            }),
+          ]),
+        ),
+      ).toHaveLength(0);
+    });
+
+    test("ignores docker/image runtimes, static sites, and non-services", () => {
+      expect(
+        ren010.check(
+          ctx(
+            ["d", new WebService({ name: "d", repo: REPO, serviceDetails: new WebServiceDetails({ runtime: "docker", envSpecificDetails: new DockerDetails({}) }) })],
+            ["i", new WebService({ name: "i", image: new Image({ imagePath: "nginx" }), serviceDetails: new WebServiceDetails({ runtime: "image" }) })],
+            ["s", new StaticSite({ name: "s", repo: REPO, serviceDetails: new StaticSiteDetails({}) })],
+            ["db", new Postgres({ name: "db", plan: "free", version: "16" })],
+          ),
+        ),
+      ).toHaveLength(0);
+    });
+  });
+
+  describe("REN011: service requires a source", () => {
+    test("flags a service with neither repo nor image", () => {
+      const diags = ren011.check(ctx(["web", new WebService({ name: "web", serviceDetails: new WebServiceDetails({ runtime: "docker" }) })]));
+      expect(diags).toHaveLength(1);
+      expect(diags[0].checkId).toBe("REN011");
+      expect(diags[0].message).toContain("neither a repo nor an image");
+    });
+
+    test("flags runtime image without an image", () => {
+      const diags = ren011.check(ctx(["web", new WebService({ name: "web", repo: REPO, serviceDetails: new WebServiceDetails({ runtime: "image" }) })]));
+      expect(diags).toHaveLength(1);
+      expect(diags[0].message).toContain('runtime "image"');
+    });
+
+    test("passes a repo-backed and an image-backed service", () => {
+      expect(
+        ren011.check(
+          ctx(
+            ["r", new WebService({ name: "r", repo: REPO, serviceDetails: new WebServiceDetails({ runtime: "docker" }) })],
+            ["i", new WebService({ name: "i", image: new Image({ imagePath: "docker.io/library/nginx:latest" }), serviceDetails: new WebServiceDetails({ runtime: "image" }) })],
+          ),
+        ),
+      ).toHaveLength(0);
+    });
+  });
+
+  describe("REN012: free plan cannot scale", () => {
+    test("flags numInstances, autoscaling, and disk on free", () => {
+      const diags = ren012.check(
+        ctx([
+          "web",
+          new WebService({
+            name: "web",
+            repo: REPO,
+            serviceDetails: new WebServiceDetails({
+              runtime: "docker",
+              plan: "free",
+              numInstances: 3,
+              autoscaling: { enabled: true, min: 1, max: 3, criteria: { cpu: { enabled: true, percentage: 70 }, memory: { enabled: false, percentage: 70 } } },
+              disk: new ServiceDisk({ name: "data", mountPath: "/data" }),
+            }),
+          }),
+        ]),
+      );
+      expect(diags).toHaveLength(1);
+      expect(diags[0].checkId).toBe("REN012");
+      expect(diags[0].message).toContain("numInstances: 3");
+      expect(diags[0].message).toContain("autoscaling");
+      expect(diags[0].message).toContain("a disk");
+    });
+
+    test("passes a free single-instance service and a scaled paid one", () => {
+      expect(
+        ren012.check(
+          ctx(
+            ["f", new WebService({ name: "f", repo: REPO, serviceDetails: new WebServiceDetails({ runtime: "docker", plan: "free" }) })],
+            ["p", new WebService({ name: "p", repo: REPO, serviceDetails: new WebServiceDetails({ runtime: "docker", plan: "standard", numInstances: 3 }) })],
+          ),
+        ),
+      ).toHaveLength(0);
+    });
+  });
+});

package/src/lint/post-synth/ren010-native-runtime-requires-commands.ts

@@ -0,0 +1,47 @@
+/**
+ * REN010: A native-runtime service must say how to build and start.
+ *
+ * Render's native runtimes (node, python, ruby, go, rust, elixir) need a
+ * `buildCommand` and a `startCommand` in `envSpecificDetails`; without them the
+ * API rejects the create (or, on some paths, accepts it and the first deploy
+ * fails). `docker` reads a Dockerfile and `image` pulls a prebuilt image, so
+ * neither needs commands. Static sites have no runtime.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { ENTITY_TYPES } from "../../catalog";
+import { readProps, entityTypeOf, isService, kindOf } from "./render-helpers";
+
+const NATIVE_RUNTIMES = new Set(["node", "python", "ruby", "go", "rust", "elixir"]);
+
+export const ren010: PostSynthCheck = {
+  id: "REN010",
+  description: "A native-runtime service must set envSpecificDetails.buildCommand and startCommand",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of ctx.entities) {
+      if (!isService(entity) || entityTypeOf(entity) === ENTITY_TYPES.staticSite) continue;
+      const details = readProps(readProps(entity).serviceDetails);
+      const runtime = details.runtime;
+      if (typeof runtime !== "string" || !NATIVE_RUNTIMES.has(runtime)) continue;
+
+      const env = readProps(details.envSpecificDetails);
+      const missing: string[] = [];
+      if (typeof env.buildCommand !== "string" || env.buildCommand.length === 0) missing.push("buildCommand");
+      if (typeof env.startCommand !== "string" || env.startCommand.length === 0) missing.push("startCommand");
+      if (missing.length > 0) {
+        diagnostics.push({
+          checkId: "REN010",
+          severity: "error",
+          message: `${kindOf(entity)} "${name}" uses the ${runtime} runtime but sets no ${missing.join(" or ")} — add envSpecificDetails: new NativeEnvironmentDetails({ buildCommand, startCommand })`,
+          entity: name,
+          lexicon: "render",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/ren011-service-requires-source.ts

@@ -0,0 +1,50 @@
+/**
+ * REN011: A service needs a source — a repo or an image.
+ *
+ * Every Render service is either git-backed (`repo`, built on Render) or
+ * image-backed (`image.imagePath`, pulled from a registry). One that names
+ * neither has nothing to deploy and is rejected at create time; one that uses
+ * the `image` runtime without an `image` is the same mistake spelled
+ * differently. Static sites are always git-backed.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readProps, isService, kindOf } from "./render-helpers";
+
+export const ren011: PostSynthCheck = {
+  id: "REN011",
+  description: "A service must have a repo (git-backed) or an image (image-backed)",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of ctx.entities) {
+      if (!isService(entity)) continue;
+      const props = readProps(entity);
+      const repo = typeof props.repo === "string" && props.repo.length > 0;
+      const imagePath = readProps(props.image).imagePath;
+      const image = typeof imagePath === "string" && imagePath.length > 0;
+      const runtime = readProps(props.serviceDetails).runtime;
+
+      if (!repo && !image) {
+        diagnostics.push({
+          checkId: "REN011",
+          severity: "error",
+          message: `${kindOf(entity)} "${name}" has neither a repo nor an image — set repo: "https://github.com/…" or image: new Image({ imagePath: "docker.io/…" })`,
+          entity: name,
+          lexicon: "render",
+        });
+      } else if (runtime === "image" && !image) {
+        diagnostics.push({
+          checkId: "REN011",
+          severity: "error",
+          message: `${kindOf(entity)} "${name}" uses runtime "image" but sets no image.imagePath`,
+          entity: name,
+          lexicon: "render",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};