@intentius/chant-lexicon-render 0.53.0

package/src/lint/post-synth/ren012-free-plan-cannot-scale.ts

@@ -0,0 +1,43 @@
+/**
+ * REN012: The free instance type cannot scale.
+ *
+ * Render's `free` plan runs a single instance and cannot autoscale; a
+ * `numInstances > 1` or an enabled `autoscaling` block on a free service is
+ * rejected at create/patch time. Persistent disks are also unavailable on
+ * free. Catch all three at synth time with a message that says which.
+ */
+
+import type { PostSynthCheck, PostSynthContext, PostSynthDiagnostic } from "@intentius/chant/lint/post-synth";
+import { readProps, isService, kindOf } from "./render-helpers";
+
+export const ren012: PostSynthCheck = {
+  id: "REN012",
+  description: "A free-plan service cannot set numInstances > 1, autoscaling, or a disk",
+
+  check(ctx: PostSynthContext): PostSynthDiagnostic[] {
+    const diagnostics: PostSynthDiagnostic[] = [];
+
+    for (const [name, entity] of ctx.entities) {
+      if (!isService(entity)) continue;
+      const details = readProps(readProps(entity).serviceDetails);
+      if (details.plan !== "free") continue;
+
+      const problems: string[] = [];
+      if (typeof details.numInstances === "number" && details.numInstances > 1) problems.push(`numInstances: ${details.numInstances}`);
+      const autoscaling = readProps(details.autoscaling);
+      if (autoscaling.enabled === true) problems.push("autoscaling");
+      if (details.disk !== undefined) problems.push("a disk");
+      if (problems.length > 0) {
+        diagnostics.push({
+          checkId: "REN012",
+          severity: "error",
+          message: `${kindOf(entity)} "${name}" is on the free plan but sets ${problems.join(", ")} — the free instance type runs one instance, cannot autoscale, and has no persistent disk; pick a paid plan (starter or above)`,
+          entity: name,
+          lexicon: "render",
+        });
+      }
+    }
+
+    return diagnostics;
+  },
+};

package/src/lint/post-synth/render-helpers.ts

@@ -0,0 +1,38 @@
+/**
+ * Shared helpers for the render post-synth checks. Not a check itself, so the
+ * generated barrel skips it (the scanner only picks up exported PostSynthChecks).
+ */
+
+import { isServiceEntityType } from "../../catalog";
+
+/**
+ * Read an entity or property's constructor props. Nested Declarables
+ * (WebServiceDetails, Image, ServiceDisk) stash their args under a
+ * non-enumerable `props`; a plain inline object carries them directly. Handle
+ * both so a check behaves the same whether the user authored
+ * `serviceDetails: { runtime }` or `serviceDetails: new WebServiceDetails({ runtime })`.
+ */
+export function readProps(value: unknown): Record<string, unknown> {
+  if (value && typeof value === "object") {
+    const nested = (value as { props?: unknown }).props;
+    if (nested && typeof nested === "object") return nested as Record<string, unknown>;
+    return value as Record<string, unknown>;
+  }
+  return {};
+}
+
+/** The entityType of a declarable, or undefined. */
+export function entityTypeOf(value: unknown): string | undefined {
+  return (value as { entityType?: string } | undefined)?.entityType;
+}
+
+/** True when the entity is one of the five service kinds. */
+export function isService(value: unknown): boolean {
+  return isServiceEntityType(entityTypeOf(value));
+}
+
+/** The short kind (`WebService`) from an entity type, for messages. */
+export function kindOf(value: unknown): string {
+  const t = entityTypeOf(value) ?? "";
+  return t.slice(t.lastIndexOf("::") + 2);
+}

package/src/lint/rules/index.ts

@@ -0,0 +1,11 @@
+import type { LintRule } from "@intentius/chant/lint/rule";
+import { validRegionRule } from "./valid-region";
+import { noSecretLiteralsRule } from "./no-secret-literals";
+import { validCronScheduleRule } from "./valid-cron-schedule";
+
+export { validRegionRule } from "./valid-region";
+export { noSecretLiteralsRule } from "./no-secret-literals";
+export { validCronScheduleRule, isValidCronSchedule } from "./valid-cron-schedule";
+
+/** All lint rules provided by the render lexicon. */
+export const rules: LintRule[] = [validRegionRule, noSecretLiteralsRule, validCronScheduleRule];

package/src/lint/rules/no-secret-literals.ts

@@ -0,0 +1,73 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * Env-var keys that carry a credential. Kept conservative on purpose — an
+ * inline value under one of these keys is very likely a real secret.
+ */
+const SECRET_KEY_PATTERN = /(?:^|[_-])(?:password|passwd|secret|token|api[_-]?key|apikey|access[_-]?key|secret[_-]?key|private[_-]?key|client[_-]?secret|credential|auth[_-]?token)(?:$|[_-])/i;
+
+/**
+ * Values that are references or placeholders, not literal secrets: shell/
+ * interpolation references ($FOO, ${FOO}) and secret-manager style references.
+ */
+const REFERENCE_VALUE_PATTERN = /^(?:\$\{?[A-Za-z0-9_]+\}?|(?:secret|ref|env|vault):\S+)$/;
+
+/**
+ * REN002: No secret literals in env vars
+ *
+ * Flags an `envVars` (or `secretFiles`) entry whose `key` looks like a
+ * credential and whose `value` is a plain string literal. Render can generate
+ * the value (`generateValue: true`), it can come from an EnvGroup or from
+ * another resource's attribute (`db.internalConnectionString`), or from the
+ * process environment at build time — anything but a literal in source that
+ * ends up in git and in the build output.
+ */
+export const noSecretLiteralsRule: LintRule = {
+  id: "REN002",
+  severity: "warning",
+  category: "security",
+  description: "Secret env-var values must not be written inline — use generateValue, an EnvGroup, or a reference",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function literalOf(init: ts.Expression): string | undefined {
+      return ts.isStringLiteral(init) || ts.isNoSubstitutionTemplateLiteral(init) ? init.text : undefined;
+    }
+
+    function visit(node: ts.Node): void {
+      // `{ key: "DB_PASSWORD", value: "hunter2" }` — an object literal with a
+      // secret-looking `key` and a literal `value`.
+      if (ts.isObjectLiteralExpression(node)) {
+        let key: string | undefined;
+        let valueNode: ts.Expression | undefined;
+        for (const prop of node.properties) {
+          if (!ts.isPropertyAssignment(prop)) continue;
+          const name = prop.name.getText(sourceFile).replace(/^["']|["']$/g, "");
+          if (name === "key") key = literalOf(prop.initializer);
+          if (name === "value") valueNode = prop.initializer;
+        }
+        if (key && valueNode) {
+          const value = literalOf(valueNode);
+          if (value !== undefined && value.length >= 4 && SECRET_KEY_PATTERN.test(key) && !REFERENCE_VALUE_PATTERN.test(value.trim())) {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(valueNode.getStart(sourceFile));
+            diagnostics.push({
+              file: sourceFile.fileName,
+              line: line + 1,
+              column: character + 1,
+              ruleId: "REN002",
+              severity: "warning",
+              message: `Possible inline secret for env var "${key}". Use \`generateValue: true\`, an EnvGroup, a resource attribute (e.g. db.internalConnectionString), or process.env — not a literal.`,
+            });
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lint/rules/rules.test.ts

@@ -0,0 +1,73 @@
+import { describe, test, expect } from "vitest";
+import * as ts from "typescript";
+import { validRegionRule } from "./valid-region";
+import { noSecretLiteralsRule } from "./no-secret-literals";
+import { validCronScheduleRule, isValidCronSchedule } from "./valid-cron-schedule";
+import type { LintContext } from "@intentius/chant/lint/rule";
+
+function createContext(code: string, fileName = "infra.ts"): LintContext {
+  const sourceFile = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true);
+  return { sourceFile, entities: [], filePath: fileName };
+}
+
+describe("Render lint rules", () => {
+  describe("REN001: valid region", () => {
+    test("flags an unknown region", () => {
+      const diags = validRegionRule.check(createContext(`new WebServiceDetails({ runtime: "node", region: "narnia" });`));
+      expect(diags).toHaveLength(1);
+      expect(diags[0].ruleId).toBe("REN001");
+      expect(diags[0].severity).toBe("error");
+      expect(diags[0].message).toContain("narnia");
+    });
+
+    test("passes every known region", () => {
+      for (const r of ["frankfurt", "oregon", "ohio", "singapore", "virginia"]) {
+        expect(validRegionRule.check(createContext(`new Postgres({ name: "db", region: "${r}" });`))).toHaveLength(0);
+      }
+    });
+
+    test("ignores a non-literal region", () => {
+      expect(validRegionRule.check(createContext(`new KeyValue({ region: Render.Region });`))).toHaveLength(0);
+    });
+  });
+
+  describe("REN002: no secret literals", () => {
+    test("flags a literal value under a secret-looking key", () => {
+      const diags = noSecretLiteralsRule.check(createContext(`envVars: [{ key: "DATABASE_PASSWORD", value: "hunter22" }]`));
+      expect(diags).toHaveLength(1);
+      expect(diags[0].ruleId).toBe("REN002");
+      expect(diags[0].severity).toBe("warning");
+      expect(diags[0].message).toContain("DATABASE_PASSWORD");
+    });
+
+    test("passes generateValue, references, placeholders, and non-secret keys", () => {
+      expect(noSecretLiteralsRule.check(createContext(`[{ key: "API_KEY", generateValue: true }]`))).toHaveLength(0);
+      expect(noSecretLiteralsRule.check(createContext(`[{ key: "API_KEY", value: db.internalConnectionString }]`))).toHaveLength(0);
+      expect(noSecretLiteralsRule.check(createContext(`[{ key: "API_KEY", value: process.env.API_KEY! }]`))).toHaveLength(0);
+      expect(noSecretLiteralsRule.check(createContext(`[{ key: "API_KEY", value: "$API_KEY" }]`))).toHaveLength(0);
+      expect(noSecretLiteralsRule.check(createContext(`[{ key: "LOG_LEVEL", value: "debug" }]`))).toHaveLength(0);
+    });
+  });
+
+  describe("REN003: valid cron schedule", () => {
+    test("isValidCronSchedule accepts standard five-field expressions", () => {
+      for (const ok of ["0 * * * *", "*/15 * * * *", "0 0 1 * *", "30 2 * * 1-5", "0,30 * * * *", "0 9-17/2 * * 1,3,5"]) {
+        expect(isValidCronSchedule(ok), ok).toBe(true);
+      }
+      for (const bad of ["@hourly", "* * * * * *", "0 * * *", "every hour", ""]) {
+        expect(isValidCronSchedule(bad), bad).toBe(false);
+      }
+    });
+
+    test("flags an invalid schedule literal", () => {
+      const diags = validCronScheduleRule.check(createContext(`new CronJobDetails({ runtime: "docker", schedule: "@hourly" });`));
+      expect(diags).toHaveLength(1);
+      expect(diags[0].ruleId).toBe("REN003");
+      expect(diags[0].message).toContain("@hourly");
+    });
+
+    test("passes a valid schedule", () => {
+      expect(validCronScheduleRule.check(createContext(`new CronJobDetails({ runtime: "docker", schedule: "0 * * * *" });`))).toHaveLength(0);
+    });
+  });
+});

package/src/lint/rules/valid-cron-schedule.ts

@@ -0,0 +1,51 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/** One cron field: `*`, a number, a range, a list, or any of those with a `/step`. */
+const FIELD = String.raw`(?:\*|\d+(?:-\d+)?)(?:,(?:\*|\d+(?:-\d+)?))*(?:\/\d+)?`;
+const CRON_5 = new RegExp(`^${FIELD}(?:\\s+${FIELD}){4}$`);
+
+/** True for a standard five-field cron expression (Render accepts no seconds field or macros). */
+export function isValidCronSchedule(s: string): boolean {
+  return CRON_5.test(s.trim());
+}
+
+/**
+ * REN003: Valid cron schedule
+ *
+ * A CronJob's `schedule` must be a standard five-field cron expression
+ * (`minute hour day-of-month month day-of-week`). Render rejects `@hourly`-style
+ * macros and six-field (seconds) expressions at create time; catch them at build.
+ */
+export const validCronScheduleRule: LintRule = {
+  id: "REN003",
+  severity: "error",
+  category: "correctness",
+  description: "A cron job schedule must be a five-field cron expression",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isPropertyAssignment(node) && node.name.getText(sourceFile) === "schedule") {
+        const init = node.initializer;
+        if (ts.isStringLiteral(init) && !isValidCronSchedule(init.text)) {
+          const { line, character } = sourceFile.getLineAndCharacterOfPosition(init.getStart(sourceFile));
+          diagnostics.push({
+            file: sourceFile.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "REN003",
+            severity: "error",
+            message: `Invalid cron schedule "${init.text}". Use five fields, e.g. "0 * * * *" (hourly) or "*/15 * * * *" (every 15 minutes); Render accepts no @macros or seconds field.`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lint/rules/valid-region.ts

@@ -0,0 +1,49 @@
+import type { LintRule, LintDiagnostic, LintContext } from "@intentius/chant/lint/rule";
+import * as ts from "typescript";
+
+/**
+ * Render's regions, per the `region` enum in the Public API spec. The generated
+ * types already narrow `region` to this union, so a typo is a compile error in
+ * a typed project; this rule gives the same answer with a clearer message, and
+ * fires in contexts the type checker does not reach (a `.js` stack, a value
+ * that has been widened to `string`).
+ */
+export const KNOWN_REGIONS = new Set<string>(["frankfurt", "oregon", "ohio", "singapore", "virginia"]);
+
+/**
+ * REN001: Valid Render region
+ *
+ * A service, datastore, or Key Value `region` must be a Render region.
+ */
+export const validRegionRule: LintRule = {
+  id: "REN001",
+  severity: "error",
+  category: "correctness",
+  description: "A region must be a Render region (frankfurt, oregon, ohio, singapore, virginia)",
+
+  check(context: LintContext): LintDiagnostic[] {
+    const { sourceFile } = context;
+    const diagnostics: LintDiagnostic[] = [];
+
+    function visit(node: ts.Node): void {
+      if (ts.isPropertyAssignment(node) && node.name.getText(sourceFile) === "region") {
+        const init = node.initializer;
+        if (ts.isStringLiteral(init) && init.text.length > 0 && !KNOWN_REGIONS.has(init.text)) {
+          const { line, character } = sourceFile.getLineAndCharacterOfPosition(init.getStart(sourceFile));
+          diagnostics.push({
+            file: sourceFile.fileName,
+            line: line + 1,
+            column: character + 1,
+            ruleId: "REN001",
+            severity: "error",
+            message: `Unknown Render region "${init.text}". Use one of: ${[...KNOWN_REGIONS].join(", ")}.`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    }
+
+    visit(sourceFile);
+    return diagnostics;
+  },
+};

package/src/lsp/completions.test.ts

@@ -0,0 +1,28 @@
+import { describe, expect, it } from "vitest";
+import { completions } from "./completions";
+
+describe("render LSP completions", () => {
+  it("returns nothing for a non-constructor context", () => {
+    const items = completions({
+      uri: "file:///a.ts",
+      content: "const x = 42",
+      position: { line: 0, character: 12 },
+      wordAtCursor: "42",
+      linePrefix: "const x = 42",
+    });
+    expect(items).toHaveLength(0);
+  });
+
+  it("completes resource classes after `new`", () => {
+    const items = completions({
+      uri: "file:///infra.ts",
+      content: "const web = new Web",
+      position: { line: 0, character: 19 },
+      wordAtCursor: "Web",
+      linePrefix: "const web = new Web",
+    });
+    const labels = items.map((c) => c.label);
+    expect(labels).toContain("WebService");
+    expect(labels).toContain("Webhook");
+  });
+});

package/src/lsp/completions.ts

@@ -0,0 +1,22 @@
+import { createRequire } from "module";
+import type { CompletionContext, CompletionItem } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconCompletions, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-render.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide render completions based on context — the resource classes
+ * (WebService, Postgres, EnvGroup, ...) and their property entities, from the
+ * generated registry.
+ */
+export function completions(ctx: CompletionContext): CompletionItem[] {
+  return lexiconCompletions(ctx, getIndex(), "Render resource");
+}

package/src/lsp/hover.test.ts

@@ -0,0 +1,32 @@
+import { describe, expect, it } from "vitest";
+import { hover } from "./hover";
+
+describe("render LSP hover", () => {
+  it("returns undefined for an unknown word", () => {
+    expect(
+      hover({ uri: "file:///a.ts", content: "const x = 42", position: { line: 0, character: 8 }, word: "x", lineText: "const x = 42" }),
+    ).toBeUndefined();
+  });
+
+  it("describes a resource with its collection and marker, and a property as nested", () => {
+    const web = hover({
+      uri: "file:///infra.ts",
+      content: "new WebService({})",
+      position: { line: 0, character: 6 },
+      word: "WebService",
+      lineText: "new WebService({})",
+    });
+    expect(web?.contents).toContain("Render::Services::WebService");
+    expect(web?.contents).toContain("POST /services");
+    expect(web?.contents).toContain("CHANT_MANAGED_BY");
+
+    const details = hover({
+      uri: "file:///infra.ts",
+      content: "new WebServiceDetails({})",
+      position: { line: 0, character: 6 },
+      word: "WebServiceDetails",
+      lineText: "new WebServiceDetails({})",
+    });
+    expect(details?.contents).toContain("Property");
+  });
+});

package/src/lsp/hover.ts

@@ -0,0 +1,50 @@
+import { createRequire } from "module";
+import type { HoverContext, HoverInfo } from "@intentius/chant/lsp/types";
+import { LexiconIndex, lexiconHover, type LexiconEntry } from "@intentius/chant/lsp/lexicon-providers";
+import { CATALOG } from "../catalog";
+const require = createRequire(import.meta.url);
+
+let cachedIndex: LexiconIndex | null = null;
+
+function getIndex(): LexiconIndex {
+  if (cachedIndex) return cachedIndex;
+  const data = require("../generated/lexicon-render.json") as Record<string, LexiconEntry>;
+  cachedIndex = new LexiconIndex(data);
+  return cachedIndex;
+}
+
+/**
+ * Provide hover information for render entity types.
+ */
+export function hover(ctx: HoverContext): HoverInfo | undefined {
+  return lexiconHover(ctx, getIndex(), resourceHover);
+}
+
+function resourceHover(className: string, entry: LexiconEntry): HoverInfo | undefined {
+  const lines: string[] = [];
+
+  lines.push(`**${className}**`);
+  lines.push("");
+  lines.push(`Render type: \`${entry.resourceType}\``);
+  lines.push("");
+  const cat = CATALOG[entry.resourceType];
+  if (entry.kind === "resource" && cat) {
+    lines.push(`*Resource — created with \`POST ${cat.collection}\` on the Render Public API and reconciled by name*`);
+    if (cat.marked) {
+      lines.push("");
+      lines.push("Carries chant's `CHANT_MANAGED_BY` env-var ownership marker; eligible for owned-only prune.");
+    } else if (cat.boundary === "service") {
+      lines.push("");
+      lines.push("Inherits its parent service's ownership verdict (service boundary); pruned when the service is chant-owned and this is undeclared.");
+    } else {
+      lines.push("");
+      lines.push("No ownership marker channel: verdict is `unknown`; never auto-pruned.");
+    }
+  } else if (entry.kind === "resource") {
+    lines.push("*Resource — a Render Public API object*");
+  } else {
+    lines.push("*Property — a nested value in a Render resource declaration*");
+  }
+
+  return { contents: lines.join("\n") };
+}