@intentius/chant-lexicon-render 0.53.0

package/src/codegen/naming.ts

@@ -0,0 +1,55 @@
+/**
+ * Render naming strategy — maps Render::{Group}::{Kind} type names to
+ * user-friendly TypeScript class names.
+ */
+
+import {
+  NamingStrategy as CoreNamingStrategy,
+  type NamingConfig,
+  type NamingInput,
+} from "@intentius/chant/codegen/naming";
+import { renderShortName, renderServiceName, type RenderParseResult } from "../spec/parse";
+
+export { propertyTypeName, extractDefName } from "@intentius/chant/codegen/naming";
+
+const renderNamingConfig: NamingConfig = {
+  priorityNames: {
+    "Render::Services::WebService": "WebService",
+    "Render::Services::StaticSite": "StaticSite",
+    "Render::Services::PrivateService": "PrivateService",
+    "Render::Services::BackgroundWorker": "BackgroundWorker",
+    "Render::Services::CronJob": "CronJob",
+    "Render::Datastores::Postgres": "Postgres",
+    "Render::Datastores::KeyValue": "KeyValue",
+    "Render::Config::EnvGroup": "EnvGroup",
+    "Render::Projects::Project": "Project",
+    "Render::Projects::Environment": "Environment",
+  },
+
+  priorityAliases: {},
+
+  priorityPropertyAliases: {},
+
+  serviceAbbreviations: {
+    Services: "Services",
+    Datastores: "Datastores",
+    Config: "Config",
+    Projects: "Projects",
+  },
+
+  shortName: renderShortName,
+  serviceName: renderServiceName,
+};
+
+/**
+ * Render-specific naming strategy. Extends the core strategy with the render config.
+ */
+export class NamingStrategy extends CoreNamingStrategy {
+  constructor(results: RenderParseResult[]) {
+    const inputs: NamingInput[] = results.map((r) => ({
+      typeName: r.resource.typeName,
+      propertyTypes: r.propertyTypes,
+    }));
+    super(inputs, renderNamingConfig);
+  }
+}

package/src/codegen/package.ts

@@ -0,0 +1,30 @@
+import { packagePipeline, collectSkills } from "@intentius/chant/codegen/package";
+import { generate } from "./generate";
+import { renderPlugin } from "../plugin";
+import { readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+
+/**
+ * Package the render lexicon for distribution.
+ */
+export async function packageLexicon(options?: { verbose?: boolean; force?: boolean }) {
+  // This file is src/codegen/package.ts — rules and skills are collected
+  // relative to src/, so srcDir must be the parent of this directory.
+  const srcDir = dirname(dirname(fileURLToPath(import.meta.url)));
+  const pkgJson = JSON.parse(readFileSync(join(srcDir, "..", "package.json"), "utf-8"));
+
+  const { spec, stats } = await packagePipeline({
+    generate: (opts) => generate({ verbose: opts?.verbose, force: opts?.force }),
+    buildManifest: (_genResult) => ({
+      name: "render",
+      version: pkgJson.version ?? "0.0.0",
+      chantVersion: ">=0.1.0",
+      namespace: "Render",
+    }),
+    srcDir,
+    collectSkills: () => collectSkills(renderPlugin.skills?.() ?? []),
+  });
+
+  return { spec, stats };
+}

package/src/composites/render-deploy.ts

@@ -0,0 +1,133 @@
+/**
+ * render deploy Op — `build → renderApply [→ verify]` on the local executor.
+ * The peer of `flyDeploy`, for a platform with no local emulator: it targets a
+ * real Render workspace with a `RENDER_API_KEY`.
+ *
+ * The phases compose modeled activities, no raw shell:
+ *   Build    run the project's `build:render` npm script → the serialized plan
+ *   Apply    `renderApply` the plan straight to the Render Public API (creates
+ *            or PATCHes each resource by name, waits each created service's
+ *            deploy to `live`, prunes owned-only when asked)
+ *   Verify   optional: GET a public URL and assert on its body
+ *
+ * The activity steps are the generic `activity(fn, args)` builder tagged with
+ * the exported activity function names the render lexicon contributes
+ * (`renderApply`/`renderDelete` from `src/op/activities`). The core activity
+ * registry resolves them by name when a project lists the `render` lexicon.
+ */
+
+import { Op, phase, build, activity, httpCheck } from "@intentius/chant/op";
+import type { OpResource } from "@intentius/chant/op";
+import type { ActivityStep } from "@intentius/chant/op";
+
+/** Options for the render apply step (mirror `RenderApplyArgs`, minus `planPath`). */
+export interface RenderApplyStepOpts {
+  /** API base URL override. Default: `RENDER_API_BASE_URL` env, else api.render.com. */
+  endpoint?: string;
+  /** Bearer token. Default: `RENDER_API_KEY`. */
+  token?: string;
+  /** Workspace id for `$owner` markers. Default: `RENDER_OWNER_ID`, else the sole visible owner. */
+  ownerId?: string;
+  /** Prune chant-owned services/env groups the plan no longer declares. Destructive — off by default. */
+  prune?: boolean;
+  /** Deploy wait tuning. */
+  wait?: Record<string, unknown>;
+  /** Activity profile override. */
+  profile?: ActivityStep["profile"];
+}
+
+/**
+ * Apply the serialized render plan straight to the Render Public API — the
+ * typed twin of `flyApplyStep`. Resolves to the `renderApply` activity.
+ * Defaults to the `longInfra` profile (a first deploy builds and can take
+ * minutes); override via `opts.profile`.
+ */
+export const renderApplyStep = (planPath: string, opts?: RenderApplyStepOpts): ActivityStep => {
+  const { profile, ...rest } = opts ?? {};
+  return activity("renderApply", { planPath, ...(rest as Record<string, unknown>) }, profile ?? "longInfra");
+};
+
+/**
+ * Delete everything the plan declares, in reverse order — the teardown twin.
+ * Resolves to the `renderDelete` activity.
+ */
+export const renderDeleteStep = (planPath: string, opts?: RenderApplyStepOpts): ActivityStep => {
+  const { profile, ...rest } = opts ?? {};
+  return activity("renderDelete", { planPath, ...(rest as Record<string, unknown>) }, profile ?? "longInfra");
+};
+
+/** Options for {@link renderDeploy}. */
+export interface RenderDeployOpts {
+  /** Op name (the `chant run <name>` target). Default: `render`. */
+  name?: string;
+  /** Op overview line. */
+  overview?: string;
+  /** Temporal task queue (unused by the local executor). Default: `local-render`. */
+  taskQueue?: string;
+  /** Directory the `build:render` script and plan path are relative to. Default: `.`. */
+  path?: string;
+  /** npm build script to run. Default: `build:render`. */
+  buildScript?: string;
+  /** Path to the serialized render plan the build writes. Default: `dist/render.json`. */
+  planPath?: string;
+  /** API base URL override (a local stand-in). Default: real Render via `RENDER_API_BASE_URL` / `RENDER_API_KEY`. */
+  endpoint?: string;
+  /** Workspace id. Default: `RENDER_OWNER_ID`, else the sole visible owner. */
+  ownerId?: string;
+  /** Prune declared-then-removed owned resources on apply. Off by default. */
+  prune?: boolean;
+  /** Deploy wait tuning passed through to `renderApply`. */
+  wait?: Record<string, unknown>;
+  /**
+   * A public URL to GET after apply, with the text it must contain. When set,
+   * the Op adds a Verify phase. Omitted → no Verify (the Apply step still
+   * waits each created service's deploy to `live`).
+   */
+  verify?: { url: string; contains?: string; retries?: number; intervalMs?: number };
+  /** Add a Teardown phase that deletes what the plan declares. Off by default. */
+  teardown?: boolean;
+}
+
+/**
+ * Build a render deploy Op: build the plan, apply it to the workspace, verify
+ * a URL when asked, tear down when asked. See the module docstring.
+ */
+export function renderDeploy(opts: RenderDeployOpts = {}): InstanceType<typeof OpResource> {
+  const path = opts.path ?? ".";
+  const planPath = opts.planPath ?? "dist/render.json";
+
+  const applyOpts: RenderApplyStepOpts = {
+    ...(opts.endpoint ? { endpoint: opts.endpoint } : {}),
+    ...(opts.ownerId ? { ownerId: opts.ownerId } : {}),
+    ...(opts.prune ? { prune: true } : {}),
+    ...(opts.wait ? { wait: opts.wait } : {}),
+  };
+
+  const phases = [
+    phase("Build", [build(path, { script: opts.buildScript ?? "build:render" })]),
+    phase("Apply", [renderApplyStep(planPath, applyOpts)]),
+  ];
+
+  if (opts.verify) {
+    phases.push(
+      phase("Verify", [
+        httpCheck(opts.verify.url, {
+          ...(opts.verify.contains ? { contains: opts.verify.contains } : {}),
+          retries: opts.verify.retries ?? 30,
+          intervalMs: opts.verify.intervalMs ?? 5000,
+        }),
+      ]),
+    );
+  }
+
+  if (opts.teardown) {
+    phases.push(phase("Teardown", [renderDeleteStep(planPath, applyOpts)]));
+  }
+
+  return Op({
+    name: opts.name ?? "render",
+    overview: opts.overview ?? "Render: build the plan, apply it to the workspace over the Public API, verify",
+    taskQueue: opts.taskQueue ?? "local-render",
+    phases,
+  });
+}

package/src/coverage.ts

@@ -0,0 +1,49 @@
+/**
+ * Coverage analysis for the render lexicon — how much of the generated Render
+ * API surface the lexicon's typed resources cover. Thin wrapper over the shared
+ * `computeCoverage`, mirroring the fly/gcp peers.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  computeCoverage,
+  overallPct,
+  formatSummary,
+  formatVerbose,
+  checkThresholds,
+  type CoverageReport,
+  type CoverageThresholds,
+} from "@intentius/chant/codegen/coverage";
+
+export type { CoverageReport, CoverageThresholds };
+export { computeCoverage, overallPct, formatSummary, formatVerbose, checkThresholds };
+
+/** Run coverage analysis for the render lexicon. */
+export async function analyzeRenderCoverage(opts?: {
+  basePath?: string;
+  verbose?: boolean;
+  minOverall?: number;
+}): Promise<CoverageReport> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  const lexiconPath = join(basePath, "src", "generated", "lexicon-render.json");
+
+  if (!existsSync(lexiconPath)) {
+    throw new Error(`Generated lexicon not found at ${lexiconPath}. Run "chant dev generate" first.`);
+  }
+
+  const report = computeCoverage(readFileSync(lexiconPath, "utf-8"));
+
+  console.error(opts?.verbose ? formatVerbose(report) : formatSummary(report));
+
+  if (typeof opts?.minOverall === "number") {
+    const result = checkThresholds(report, { minOverallPct: opts.minOverall });
+    if (!result.ok) {
+      for (const v of result.violations) console.error(`  FAIL: ${v}`);
+      throw new Error("Coverage below threshold");
+    }
+  }
+
+  return report;
+}

package/src/describe-resources.test.ts

@@ -0,0 +1,143 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { Declarable } from "@intentius/chant";
+import { resolveAttrRefs } from "@intentius/chant/discovery/resolve";
+import { serializeRender } from "./serializer";
+import { describeResources } from "./describe-resources";
+import { FakeRender } from "./op/activities/fake-render";
+import { renderApply } from "./op/activities/render-apply";
+import { WebService, WebServiceDetails, Postgres, Disk, CustomDomain, EnvGroup } from "./generated/index";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+function stack(...entries: Array<[string, unknown]>): Map<string, Declarable> {
+  return new Map(entries as Array<[string, Declarable]>);
+}
+
+function build(entities: Map<string, Declarable>): { buildOutput: string; entities: Map<string, { entityType: string; props: Record<string, unknown> }> } {
+  resolveAttrRefs(entities);
+  const buildOutput = serializeRender(entities);
+  const meta = new Map<string, { entityType: string; props: Record<string, unknown> }>();
+  for (const [name, e] of entities) {
+    meta.set(name, { entityType: (e as unknown as { entityType: string }).entityType, props: (e as unknown as { props: Record<string, unknown> }).props ?? {} });
+  }
+  return { buildOutput, entities: meta };
+}
+
+const base = (b: ReturnType<typeof build>) => ({
+  environment: "dev",
+  buildOutput: b.buildOutput,
+  entityNames: [...b.entities.keys()],
+  entities: b.entities,
+  endpoint: "http://fake/v1",
+});
+
+describe("render describeResources", () => {
+  afterEach(() => {
+    delete process.env.RENDER_OWNER_ID;
+  });
+
+  it("reports absent before apply and present (with verdicts) after", async () => {
+    process.env.RENDER_OWNER_ID = "tea-1";
+    const fake = new FakeRender();
+    const w = new WebService({ name: "web", serviceDetails: new WebServiceDetails({ runtime: "docker" }) });
+    const b = build(stack(["web", w], ["db", new Postgres({ name: "db", plan: "free", version: "16" })], ["disk", new Disk({ name: "data", sizeGB: 1, mountPath: "/d", serviceId: w })]));
+
+    const before = await describeResources(base(b), fake.http());
+    expect(before.observation).toBe("v1");
+    expect(before.resources).toEqual({});
+    expect(before.unobserved).toBeUndefined();
+
+    const dir = mkdtempSync(join(tmpdir(), "render-obs-"));
+    const planPath = join(dir, "render.json");
+    writeFileSync(planPath, b.buildOutput);
+    await renderApply({ planPath, endpoint: "http://fake/v1", wait: { intervalMs: 0 } }, undefined, fake.http());
+
+    const after = await describeResources(base(b), fake.http());
+    expect(Object.keys(after.resources).sort()).toEqual(["db", "disk", "web"]);
+    expect(after.resources.web.ownership).toBe("owned");
+    expect(after.resources.web.type).toBe("Render::Services::WebService");
+    expect(after.resources.web.physicalId).toMatch(/^srv-/);
+    expect(after.resources.db.ownership).toBe("unknown");
+    // Service boundary: the disk inherits its owned parent's verdict.
+    expect(after.resources.disk.ownership).toBe("owned");
+    expect(after.resources.disk.attributes?.serviceId).toBe(after.resources.web.physicalId);
+  });
+
+  it("disks and domains inherit a foreign parent's verdict, and undeclared ones under an owned service are owned orphans", async () => {
+    process.env.RENDER_OWNER_ID = "tea-1";
+    const fake = new FakeRender();
+    const foreign = fake.seed("/services", { name: "theirs", type: "web_service", ownerId: "tea-1", envVars: [] });
+    fake.seed("/disks", { name: "fd", sizeGB: 1, mountPath: "/d", serviceId: foreign.id });
+    const w = new WebService({ name: "web", serviceDetails: new WebServiceDetails({ runtime: "docker" }) });
+    const b = build(
+      stack(
+        ["web", w],
+        ["disk", new Disk({ name: "data", sizeGB: 1, mountPath: "/d", serviceId: w })],
+        ["fdisk", new Disk({ name: "fd", sizeGB: 1, mountPath: "/d", serviceId: foreign.id as string })],
+      ),
+    );
+    const dir = mkdtempSync(join(tmpdir(), "render-obs-"));
+    const planPath = join(dir, "render.json");
+    writeFileSync(planPath, b.buildOutput);
+    await renderApply({ planPath, endpoint: "http://fake/v1", wait: { intervalMs: 0 } }, undefined, fake.http());
+    const webId = fake.service("web")!.id as string;
+    fake.seed("/disks", { name: "stray", sizeGB: 1, mountPath: "/s", serviceId: webId });
+    fake.domains.set(webId, [{ id: "cd-1", name: "stray.example.com", verificationStatus: "unverified" }]);
+
+    const out = await describeResources(base(b), fake.http());
+    expect(out.resources.disk.ownership).toBe("owned");
+    expect(out.resources.fdisk.ownership).toBe("foreign");
+    expect(out.resources["Disk/stray"]).toMatchObject({ ownership: "owned", type: "Render::Services::Disk" });
+    expect(out.resources["CustomDomain/stray.example.com"]).toMatchObject({ ownership: "owned", status: "unverified" });
+
+    const owned = await describeResources({ ...base(b), owned: true }, fake.http());
+    expect(owned.resources.fdisk).toBeUndefined();
+    expect(owned.unobserved?.fdisk.reason).toBe("filtered");
+    expect(owned.resources.disk.ownership).toBe("owned");
+  });
+
+  it("marks an unmarked live service foreign, and withholds it under --owned", async () => {
+    process.env.RENDER_OWNER_ID = "tea-1";
+    const fake = new FakeRender();
+    fake.seed("/services", { name: "web", type: "web_service", ownerId: "tea-1", envVars: [{ key: "A", value: "1" }] });
+    const b = build(stack(["web", new WebService({ name: "web", serviceDetails: new WebServiceDetails({ runtime: "docker" }) })]));
+
+    const all = await describeResources(base(b), fake.http());
+    expect(all.resources.web.ownership).toBe("foreign");
+
+    const owned = await describeResources({ ...base(b), owned: true }, fake.http());
+    expect(owned.resources.web).toBeUndefined();
+    expect(owned.unobserved?.web.reason).toBe("filtered");
+  });
+
+  it("returns undeclared chant-marked services and env groups as owned orphans", async () => {
+    process.env.RENDER_OWNER_ID = "tea-1";
+    const fake = new FakeRender();
+    fake.seed("/services", { name: "stale", type: "cron_job", ownerId: "tea-1", envVars: [{ key: "CHANT_MANAGED_BY", value: "chant" }] });
+    fake.seed("/services", { name: "theirs", type: "web_service", ownerId: "tea-1", envVars: [] });
+    fake.seed("/env-groups", { name: "old", ownerId: "tea-1", envVars: [{ key: "CHANT_MANAGED_BY", value: "chant" }] });
+    const b = build(stack(["g", new EnvGroup({ name: "g", envVars: [] })]));
+
+    const out = await describeResources(base(b), fake.http());
+    expect(Object.keys(out.resources).sort()).toEqual(["CronJob/stale", "EnvGroup/old"]);
+    expect(out.resources["CronJob/stale"].ownership).toBe("owned");
+    expect(out.resources["CronJob/stale"].type).toBe("Render::Services::CronJob");
+  });
+
+  it("with no build output, every declared entity is unobserved (read-failed), not absent", async () => {
+    const fake = new FakeRender();
+    const b = build(stack(["web", new WebService({ name: "web", serviceDetails: new WebServiceDetails({ runtime: "docker" }) })]));
+    const out = await describeResources({ ...base(b), buildOutput: "" }, fake.http());
+    expect(out.resources).toEqual({});
+    expect(out.unobserved?.web.reason).toBe("read-failed");
+  });
+
+  it("an owner that cannot be resolved is no-credentials for every entity", async () => {
+    const fake = new FakeRender();
+    fake.owners.push({ id: "tea-2", name: "B", email: "", type: "team" });
+    const b = build(stack(["web", new WebService({ name: "web", serviceDetails: new WebServiceDetails({ runtime: "docker" }) })]));
+    const out = await describeResources(base(b), fake.http());
+    expect(out.unobserved?.web.reason).toBe("no-credentials");
+  });
+});