@checkstack/ui 1.10.0 → 1.12.0

package/src/components/CodeEditor/scriptContext.ts

@@ -89,6 +89,22 @@ interface HealthCheckScriptResult {
 interface HealthCheckScriptContext {
   /** Strongly-typed collector configuration. */
   readonly config: ${configType};
+  /** Metadata about the health check this run is for. */
+  readonly check: {
+    /** The health check configuration id. */
+    readonly id: string;
+    /** The health check's display name (falls back to the id). */
+    readonly name: string;
+    /** The configured run interval, in seconds. */
+    readonly intervalSeconds: number;
+  };
+  /** Metadata about the system this check runs for. */
+  readonly system: {
+    /** The system id. */
+    readonly id: string;
+    /** The system's display name (falls back to the id). */
+    readonly name: string;
+  };
 }
 
 /**
@@ -328,6 +344,51 @@ const SAFE_SHELL_VARS: ShellEnvVar[] = [
   { name: "SHELL", description: "User's login shell." },
 ];
 
+/**
+ * Run-context vars the satellite injects into every shell health-check
+ * run, describing the check + system it's for. Mirrors the reserved
+ * `CHECKSTACK_*` keys set by `healthcheck-script-backend`'s shell
+ * collector. User-supplied `env` values override these.
+ */
+const HEALTHCHECK_RUN_CONTEXT_VARS: ShellEnvVar[] = [
+  { name: "CHECKSTACK_CHECK_ID", description: "This health check's configuration id." },
+  {
+    name: "CHECKSTACK_CHECK_NAME",
+    description: "This health check's display name (falls back to the id).",
+  },
+  {
+    name: "CHECKSTACK_CHECK_INTERVAL_SECONDS",
+    description: "The configured run interval, in seconds.",
+  },
+  { name: "CHECKSTACK_SYSTEM_ID", description: "The id of the system being checked." },
+  {
+    name: "CHECKSTACK_SYSTEM_NAME",
+    description: "The system's display name (falls back to the id).",
+  },
+];
+
+/** A valid POSIX shell identifier — only these can be referenced as `$NAME`. */
+const SHELL_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/**
+ * Turn a user's custom `env` object (e.g. a script action's or health
+ * check's "Env (JSON)" field) into `$`-completion hints. Defensive about
+ * the loosely-typed form value: non-objects yield nothing, and only keys
+ * that are valid shell identifiers are surfaced (a `$my-var` completion
+ * wouldn't be usable). Exported so editors that build their shell env
+ * suggestions outside the `*ScriptContext` helpers (e.g. the automation
+ * action editor) can merge custom env keys the same way.
+ */
+export function customShellEnvVars(env: unknown): ShellEnvVar[] {
+  if (typeof env !== "object" || env === null || Array.isArray(env)) return [];
+  return Object.keys(env)
+    .filter((name) => SHELL_IDENTIFIER.test(name))
+    .map((name) => ({
+      name,
+      description: "Custom variable from this check's Env (JSON) field.",
+    }));
+}
+
 /**
  * Vars injected by the integration platform on every delivery. Per-
  * payload-field `PAYLOAD_*` vars are appended at call time based on the
@@ -406,6 +467,13 @@ function flattenSchemaToEnvVars(
  */
 export function healthcheckScriptContext(input: {
   collectorConfigSchema?: JsonSchemaProperty;
+  /**
+   * The collector's current `env` value (the "Env (JSON)" field). Its
+   * keys are surfaced as `$`-completions so a user's own declared vars
+   * autocomplete alongside the whitelist + reserved run-context vars.
+   * Typed `unknown` because it comes from the loosely-typed form value.
+   */
+  customEnv?: unknown;
 }): ScriptEditorContext {
   const configType = input.collectorConfigSchema
     ? jsonSchemaToTypeScript(input.collectorConfigSchema)
@@ -418,7 +486,14 @@ export function healthcheckScriptContext(input: {
       javascript: HEALTHCHECK_INLINE_TS_STARTER,
       shell: HEALTHCHECK_SHELL_STARTER,
     },
-    shellEnvVars: SAFE_SHELL_VARS,
+    // Most-relevant-first: the user's own declared env, then this check's
+    // run-context metadata, then the generic OS whitelist (the suggest list
+    // is ordered by insertion index, so order here is what the user sees).
+    shellEnvVars: [
+      ...customShellEnvVars(input.customEnv),
+      ...HEALTHCHECK_RUN_CONTEXT_VARS,
+      ...SAFE_SHELL_VARS,
+    ],
   };
 }
 

package/src/components/CodeEditor/scriptDiagnostics.test.ts

@@ -0,0 +1,135 @@
+import { describe, expect, it } from "bun:test";
+import {
+  buildValidationSource,
+  flattenDiagnosticMessage,
+  mapWorkerDiagnostics,
+  offsetToPosition,
+  type RawTsDiagnostic,
+} from "./scriptDiagnostics";
+
+describe("offsetToPosition", () => {
+  it("returns 1-based line/column", () => {
+    const text = "ab\ncde\nf";
+    expect(offsetToPosition(text, 0)).toEqual({ line: 1, column: 1 });
+    expect(offsetToPosition(text, 1)).toEqual({ line: 1, column: 2 });
+    // offset 3 is the 'c' (first char after the first newline)
+    expect(offsetToPosition(text, 3)).toEqual({ line: 2, column: 1 });
+    expect(offsetToPosition(text, 7)).toEqual({ line: 3, column: 1 });
+  });
+
+  it("clamps an out-of-range offset to the text length", () => {
+    expect(offsetToPosition("ab", 999)).toEqual({ line: 1, column: 3 });
+  });
+});
+
+describe("flattenDiagnosticMessage", () => {
+  it("passes through a plain string", () => {
+    expect(flattenDiagnosticMessage("boom")).toBe("boom");
+  });
+
+  it("flattens a nested chain depth-first", () => {
+    expect(
+      flattenDiagnosticMessage({
+        messageText: "top",
+        next: [
+          { messageText: "child-a" },
+          { messageText: "child-b", next: [{ messageText: "grandchild" }] },
+        ],
+      }),
+    ).toBe("top child-a child-b grandchild");
+  });
+});
+
+describe("buildValidationSource", () => {
+  it("prepends the type defs and reports the prefix line count", () => {
+    const { text, prependedLineCount } = buildValidationSource({
+      typeDefinitions: "declare const context: { x: number };", // 1 line
+      source: "context.x;",
+    });
+    expect(prependedLineCount).toBe(1);
+    expect(text).toBe("declare const context: { x: number };\ncontext.x;");
+  });
+
+  it("counts multi-line type defs", () => {
+    const { prependedLineCount } = buildValidationSource({
+      typeDefinitions: "line1\nline2\nline3",
+      source: "x",
+    });
+    expect(prependedLineCount).toBe(3);
+  });
+});
+
+describe("mapWorkerDiagnostics", () => {
+  // 2 lines of type defs prepended; user source starts at combined line 3.
+  const { text, prependedLineCount } = buildValidationSource({
+    typeDefinitions: "declare const context: {\n  readonly a: number;\n};",
+    source: "const z = context.b;\n", // `b` doesn't exist -> error on user line 1
+  });
+
+  const errorOffset = text.indexOf("context.b") + "context.".length; // points at `b`
+
+  it("shifts a real type error back onto the user's source line", () => {
+    const diagnostics: RawTsDiagnostic[] = [
+      {
+        start: errorOffset,
+        length: 1,
+        category: 1, // Error
+        code: 2339,
+        messageText: "Property 'b' does not exist on type",
+      },
+    ];
+    const mapped = mapWorkerDiagnostics({
+      diagnostics,
+      validationText: text,
+      prependedLineCount,
+    });
+    expect(mapped).toHaveLength(1);
+    expect(mapped[0]).toMatchObject({
+      severity: "error",
+      line: 1,
+      message: "Property 'b' does not exist on type",
+    });
+  });
+
+  it("drops ignored codes (lazy-ATA module resolution, top-level return)", () => {
+    const diagnostics: RawTsDiagnostic[] = [
+      { start: errorOffset, category: 1, code: 2307, messageText: "Cannot find module 'lodash'" },
+      { start: errorOffset, category: 1, code: 1108, messageText: "A 'return' statement" },
+    ];
+    expect(
+      mapWorkerDiagnostics({ diagnostics, validationText: text, prependedLineCount }),
+    ).toEqual([]);
+  });
+
+  it("drops diagnostics that land inside the prepended type-def prefix", () => {
+    const diagnostics: RawTsDiagnostic[] = [
+      { start: 0, category: 1, code: 2300, messageText: "noise in generated types" },
+    ];
+    expect(
+      mapWorkerDiagnostics({ diagnostics, validationText: text, prependedLineCount }),
+    ).toEqual([]);
+  });
+
+  it("drops non-error/-warning categories and unpositioned diagnostics", () => {
+    const diagnostics: RawTsDiagnostic[] = [
+      { start: errorOffset, category: 2, code: 9999, messageText: "suggestion" },
+      { category: 1, code: 2339, messageText: "global, no position" },
+    ];
+    expect(
+      mapWorkerDiagnostics({ diagnostics, validationText: text, prependedLineCount }),
+    ).toEqual([]);
+  });
+
+  it("keeps warnings", () => {
+    const diagnostics: RawTsDiagnostic[] = [
+      { start: errorOffset, category: 0, code: 6133, messageText: "'z' is declared but never read" },
+    ];
+    const mapped = mapWorkerDiagnostics({
+      diagnostics,
+      validationText: text,
+      prependedLineCount,
+    });
+    expect(mapped).toHaveLength(1);
+    expect(mapped[0]?.severity).toBe("warning");
+  });
+});

package/src/components/CodeEditor/scriptDiagnostics.ts

@@ -0,0 +1,172 @@
+// Pure helpers for the headless script validator (`validateScripts.ts`).
+//
+// Kept free of any `monaco` / browser import so this logic is unit-testable
+// under bun. The browser-only worker glue lives in `validateScripts.ts` and
+// composes these helpers.
+//
+// Strategy: to type-check a user script against its generated `context.d.ts`
+// WITHOUT polluting the shared TS service's global scope (which would collide
+// with any mounted editor's own `declare const context`), we PREPEND the
+// generated type declarations onto the user's source and validate that single
+// combined file. Inside one module/script file the prepended `declare const
+// context` is in scope for the user's code below it, but it never leaks to
+// other files. Diagnostics that land in the prepended region are dropped, and
+// the rest are shifted back by the number of prepended lines so positions map
+// onto the user's original source.
+
+/** A type error/warning located in the user's original (un-prepended) source. */
+export interface ScriptDiagnostic {
+  severity: "error" | "warning";
+  /** Flattened, human-readable message. */
+  message: string;
+  /** 1-based line in the user's source. */
+  line: number;
+  /** 1-based column. */
+  column: number;
+}
+
+/**
+ * Diagnostic codes ignored during headless validation because they reflect the
+ * sandbox/loading model rather than a real mistake in the user's logic:
+ *
+ *  - 1108: a top-level `return` is legal (the runtime wraps scripts in an async
+ *    IIFE) - same suppression the editor applies.
+ *  - 2307 / 2792: "cannot find module 'x'". Type acquisition (ATA) is lazy and
+ *    only runs for the editor that is open, so a collapsed-card script's
+ *    imports have no fetched types yet. Flagging these would be a false
+ *    positive, so module-resolution failures are not surfaced here (the
+ *    backend typecheck - deferred - is the place to enforce imports).
+ *  - 7016: "could not find a declaration file for module 'x'" - same reason.
+ */
+export const IGNORED_DIAGNOSTIC_CODES: ReadonlySet<number> = new Set([
+  1108, 2307, 2792, 7016,
+]);
+
+// `ts.DiagnosticCategory`: Warning = 0, Error = 1, Suggestion = 2, Message = 3.
+const CATEGORY_ERROR = 1;
+const CATEGORY_WARNING = 0;
+
+/**
+ * Minimal shape of a TypeScript worker diagnostic (subset of monaco's
+ * `Diagnostic`). `messageText` is either a string or a nested chain.
+ */
+export interface RawTsDiagnostic {
+  start?: number;
+  length?: number;
+  messageText: string | DiagnosticMessageChain;
+  category: number;
+  code: number;
+}
+
+interface DiagnosticMessageChain {
+  messageText: string;
+  next?: DiagnosticMessageChain[];
+}
+
+/** Flatten a (possibly nested) diagnostic message chain to a single string. */
+export function flattenDiagnosticMessage(
+  messageText: string | DiagnosticMessageChain,
+): string {
+  if (typeof messageText === "string") {
+    return messageText;
+  }
+  const parts: string[] = [];
+  const walk = (chain: DiagnosticMessageChain): void => {
+    parts.push(chain.messageText);
+    for (const child of chain.next ?? []) {
+      walk(child);
+    }
+  };
+  walk(messageText);
+  return parts.join(" ");
+}
+
+/** Convert a 0-based character offset into a 1-based {line, column}. */
+export function offsetToPosition(
+  text: string,
+  offset: number,
+): { line: number; column: number } {
+  let line = 1;
+  let column = 1;
+  const end = Math.min(offset, text.length);
+  for (let i = 0; i < end; i++) {
+    if (text[i] === "\n") {
+      line += 1;
+      column = 1;
+    } else {
+      column += 1;
+    }
+  }
+  return { line, column };
+}
+
+/**
+ * Build the combined source to validate: the generated `typeDefinitions`
+ * (the `declare const context` + any ambient augmentations) prepended to the
+ * user's source. Returns the combined text plus the number of lines the prefix
+ * occupies, so diagnostics can be shifted back onto the user's source.
+ */
+export function buildValidationSource({
+  typeDefinitions,
+  source,
+}: {
+  typeDefinitions: string;
+  source: string;
+}): { text: string; prependedLineCount: number } {
+  // The prefix occupies one line per line of `typeDefinitions`; the trailing
+  // "\n" we add then places the user's source on the next line. So the user's
+  // line N maps to combined line N + prependedLineCount.
+  const prependedLineCount = typeDefinitions.split("\n").length;
+  return {
+    text: `${typeDefinitions}\n${source}`,
+    prependedLineCount,
+  };
+}
+
+/**
+ * Map raw worker diagnostics onto the user's source: drop ignored codes,
+ * non-error/-warning categories, unpositioned (global) diagnostics, and any
+ * that fall inside the prepended type-definition prefix; shift the rest back.
+ */
+export function mapWorkerDiagnostics({
+  diagnostics,
+  validationText,
+  prependedLineCount,
+}: {
+  diagnostics: RawTsDiagnostic[];
+  validationText: string;
+  prependedLineCount: number;
+}): ScriptDiagnostic[] {
+  const result: ScriptDiagnostic[] = [];
+  for (const diagnostic of diagnostics) {
+    if (IGNORED_DIAGNOSTIC_CODES.has(diagnostic.code)) {
+      continue;
+    }
+    const severity =
+      diagnostic.category === CATEGORY_ERROR
+        ? "error"
+        : diagnostic.category === CATEGORY_WARNING
+          ? "warning"
+          : undefined;
+    if (severity === undefined) {
+      continue;
+    }
+    if (diagnostic.start === undefined) {
+      // No position - a whole-file diagnostic. Not attributable to a user line,
+      // and the inline strategy shouldn't produce these; skip.
+      continue;
+    }
+    const position = offsetToPosition(validationText, diagnostic.start);
+    if (position.line <= prependedLineCount) {
+      // Lands in the generated prefix, not the user's code.
+      continue;
+    }
+    result.push({
+      severity,
+      message: flattenDiagnosticMessage(diagnostic.messageText),
+      line: position.line - prependedLineCount,
+      column: position.column,
+    });
+  }
+  return result;
+}

package/src/components/CodeEditor/templateValidation.ts

@@ -0,0 +1,51 @@
+// Shared bits for template-aware language validation (monaco -> @typefox
+// migration). Markup editors (json / yaml / xml) hold a TEMPLATE that renders
+// to the target language, not the language itself: a value can be templated in
+// any position, including unquoted ones (e.g. a number `timeout: {{x}}`). So we
+// validate "is this valid once the templates are filled in?" - substitute each
+// `{{ ... }}` with a same-length neutral value, then parse with a real parser.
+//
+// Per-language validators live in validate{Json,Yaml,Xml}Template.ts and all
+// return TemplateDiagnostic[]; the editor maps offsets to monaco markers.
+
+export interface TemplateDiagnostic {
+  /** 0-based character offset into the ORIGINAL text. */
+  offset: number;
+  /** Length of the offending span (>= 1). */
+  length: number;
+  /** Human-readable message. */
+  message: string;
+}
+
+// `[^{}]*` (not `[^}]*`) so an unclosed `{{` can't swallow up to a later `}}`.
+const TEMPLATE_PATTERN = /\{\{[^{}]*\}\}/g;
+
+/**
+ * Replace each `{{ ... }}` with `0` padded to the same length with spaces - a
+ * neutral value token, valid in value positions (a number followed by
+ * whitespace) and harmless inside strings/text. Same length keeps byte offsets
+ * identical, so parser offsets map 1:1 onto the original text.
+ */
+export const substituteTemplates = (text: string): string =>
+  text.replaceAll(
+    TEMPLATE_PATTERN,
+    (match) => `0${" ".repeat(match.length - 1)}`,
+  );
+
+/** Convert a 1-based line/column (some parsers report this) to a 0-based offset. */
+export const lineColumnToOffset = ({
+  text,
+  line,
+  column,
+}: {
+  text: string;
+  line: number;
+  column: number;
+}): number => {
+  const lines = text.split("\n");
+  let offset = 0;
+  for (let index = 0; index < line - 1 && index < lines.length; index += 1) {
+    offset += (lines[index]?.length ?? 0) + 1; // +1 for the newline
+  }
+  return offset + Math.max(column - 1, 0);
+};

package/src/components/CodeEditor/types.ts

@@ -0,0 +1,168 @@
+// Shared, pure type definitions for the CodeEditor public API.
+//
+// NOTE: this file MUST stay free of monaco / @codingame / vite imports so that
+// SSR/test/node paths can reference these types (and the package barrel can
+// re-export them) without pulling in the browser-only editor stack.
+
+export type CodeEditorLanguage =
+  | "json"
+  | "yaml"
+  | "xml"
+  | "markdown"
+  | "javascript"
+  | "typescript"
+  | "shell";
+
+/**
+ * A single payload property available for templating. Used by both the
+ * Monaco-backed `CodeEditor` and the lightweight single-line
+ * `TemplateValueInput` for the simple "insert a `{{ path }}` reference" flow.
+ */
+export interface TemplateProperty {
+  /** Full canonical path to the property, e.g., "trigger.payload.title". */
+  path: string;
+  /**
+   * Runtime-parseable `{{ }}` insertion text, e.g.
+   * `artifacts["integration-jira.issue"].issueKey`. When present this is
+   * what gets inserted; consumers fall back to `path` when it's absent.
+   */
+  templateRef?: string;
+  /** Type label rendered on the right, e.g. "string", "number". */
+  type: string;
+  /** Optional description of the property. */
+  description?: string;
+  /**
+   * Known discrete values for this field, when the schema declares an `enum`.
+   * Consumed by the template-completion provider to suggest concrete values
+   * after a comparator (e.g. `"low"` / `"high"` for a severity field).
+   */
+  enumValues?: Array<string | number | boolean>;
+}
+
+/**
+ * A single environment variable available to shell scripts. Surfaced as a
+ * completion item after the user types `$` or `${` in shell mode.
+ */
+export interface ShellEnvVar {
+  /** Variable name without the leading `$`, e.g. `EVENT_ID`. */
+  name: string;
+  /** Optional description shown in the completion popup. */
+  description?: string;
+  /** Optional example value shown in the completion item detail. */
+  example?: string;
+}
+
+/** One declaration file returned by an `AcquireTypes` resolver. */
+export interface AcquiredTypeFile {
+  /**
+   * Real `node_modules/...`-relative path (e.g.
+   * `node_modules/@types/lodash/index.d.ts`). Registered at `file:///<path>`
+   * so TypeScript's NodeJs + `@types` resolution can find it.
+   */
+  path: string;
+  /** Verbatim declaration content (UNWRAPPED — no `declare module` envelope). */
+  content: string;
+}
+
+/**
+ * Resolver for lazy Automatic Type Acquisition (ATA). Given a bare package
+ * specifier (e.g. `lodash`), returns the declaration-file closure to register
+ * with the TypeScript service (own types and/or the `@types/*` companion).
+ * Returns an empty array when the package has no acquirable types. Plugin-
+ * agnostic: the concrete fetch (route URL + lockfile hash + auth) is injected
+ * by the consumer (see `@checkstack/script-packages-frontend`).
+ */
+export type AcquireTypes = (
+  specifier: string,
+) => Promise<AcquiredTypeFile[]>;
+
+/**
+ * An externally-supplied diagnostic to render as an inline squiggle. Positions
+ * are 1-based line/column (the editor's convention). Callers compute these from
+ * their own validation (e.g. mapping a definition issue path back to a YAML
+ * node range) and pass them via `markers`.
+ */
+export interface EditorMarker {
+  startLineNumber: number;
+  startColumn: number;
+  endLineNumber: number;
+  endColumn: number;
+  message: string;
+  severity?: "error" | "warning" | "info";
+}
+
+export interface CodeEditorProps {
+  /** Unique identifier for the editor. */
+  id?: string;
+  /** Current value of the editor. */
+  value: string;
+  /** Callback when the value changes. */
+  onChange: (value: string) => void;
+  /** Language for syntax highlighting. */
+  language?: CodeEditorLanguage;
+  /** Minimum height of the editor, as a CSS length (e.g. "240px"). */
+  minHeight?: string;
+  /** Whether the editor is read-only. */
+  readOnly?: boolean;
+  /** Placeholder text when empty. */
+  placeholder?: string;
+  /**
+   * TypeScript type definitions to inject for IntelliSense (the `context.d.ts`).
+   * Generated from JSON schemas for context-aware autocomplete. For
+   * `typescript` / `javascript` editors, non-identifier object keys in these
+   * definitions (e.g. artifact ids) are offered as `["key"]` bracket
+   * completions automatically.
+   */
+  typeDefinitions?: string;
+  /**
+   * Optional template properties for autocomplete. When provided, typing "{{"
+   * triggers autocomplete with the available template variables.
+   */
+  templateProperties?: TemplateProperty[];
+  /**
+   * Optional environment-variable hints for shell mode. When provided and
+   * `language === "shell"`, they autocomplete after `$` and `${`.
+   */
+  shellEnvVars?: ShellEnvVar[];
+  /**
+   * Externally-computed diagnostics rendered as inline squiggles (under a
+   * dedicated marker owner, so they coexist with the editor's own language
+   * diagnostics).
+   */
+  markers?: EditorMarker[];
+  /**
+   * Lazy Automatic Type Acquisition resolver. When provided (TS/JS editors),
+   * the editor parses bare `import`/`require` specifiers from the buffer and
+   * calls this for each NEW package, registering the returned declaration
+   * files so `import { x } from "pkg"` autocompletes. Injected by the
+   * consumer so `@checkstack/ui` stays plugin-agnostic.
+   */
+  acquireTypes?: AcquireTypes;
+  /**
+   * Identity of the current package install (the lockfile hash). When it
+   * changes (a new install), the editor resets its acquired-set so types
+   * refresh against the new install.
+   */
+  acquireResetKey?: string;
+  /**
+   * Importable installed package NAMES (TS/JS editors). When provided, the
+   * editor suggests these while the cursor is inside an import specifier
+   * string (`import {} from "lod"` -> `lodash`), solving the lazy-ATA
+   * catch-22 where no module is registered until its name is typed. Must
+   * already exclude `@types/*` companions. Injected by the consumer.
+   */
+  importablePackages?: string[];
+  /**
+   * Whether to show the "expand editor" affordance that opens the editor in a
+   * large full-screen overlay for comfortably editing big scripts. Defaults to
+   * `true`. Set `false` to suppress it (e.g. for tiny single-line snippets).
+   */
+  allowPopout?: boolean;
+  /**
+   * Optional override for the overlay dialog title. When omitted, the title is
+   * derived from `language` (e.g. "Edit script - TypeScript"). Lets a consumer
+   * surface a field-specific label (e.g. a DynamicForm field name) while
+   * keeping `@checkstack/ui` plugin-agnostic.
+   */
+  title?: string;
+}

package/src/components/CodeEditor/validateJsonTemplate.test.ts

@@ -0,0 +1,61 @@
+import { describe, it, expect } from "bun:test";
+import { validateJsonTemplate } from "./validateJsonTemplate";
+
+describe("validateJsonTemplate", () => {
+  it("accepts valid JSON", () => {
+    expect(validateJsonTemplate('{"a": 1, "b": "two"}')).toEqual([]);
+  });
+
+  it("accepts empty content", () => {
+    expect(validateJsonTemplate("")).toEqual([]);
+    expect(validateJsonTemplate("  \n ")).toEqual([]);
+  });
+
+  it("accepts a template as a quoted string value", () => {
+    expect(
+      validateJsonTemplate('{"repo": "{{trigger.payload.repository}}"}'),
+    ).toEqual([]);
+  });
+
+  it("accepts a template embedded inside a string", () => {
+    expect(validateJsonTemplate('{"msg": "build {{id}} done"}')).toEqual([]);
+  });
+
+  it("accepts an UNQUOTED template value (e.g. a number)", () => {
+    // This is the case a plain JSON validator would reject.
+    expect(
+      validateJsonTemplate('{"timeout": {{trigger.payload.timeout}}}'),
+    ).toEqual([]);
+  });
+
+  it("accepts a template as an array element", () => {
+    expect(validateJsonTemplate('{"items": [{{count}}, 2]}')).toEqual([]);
+  });
+
+  it("flags a genuine structural error (missing comma)", () => {
+    const diagnostics = validateJsonTemplate('{"a": 1 "b": 2}');
+    expect(diagnostics.length).toBeGreaterThan(0);
+  });
+
+  it("flags an unclosed object", () => {
+    const diagnostics = validateJsonTemplate('{"a": 1');
+    expect(diagnostics.length).toBeGreaterThan(0);
+  });
+
+  it("flags a genuine error even when templates are present, at the right offset", () => {
+    // The `2` is missing its preceding colon; offset must point into the
+    // ORIGINAL text (same-length substitution preserves offsets).
+    const text = '{"a": {{x}}, "b" 2}';
+    const diagnostics = validateJsonTemplate(text);
+    expect(diagnostics.length).toBeGreaterThan(0);
+    // The error should land at/after the `2`, not inside the template.
+    const firstOffset = diagnostics[0]?.offset ?? -1;
+    expect(text.slice(firstOffset, firstOffset + 1)).toBe("2");
+  });
+
+  it("does not let an unclosed `{{` swallow a later template", () => {
+    // `{{` on its own is not a complete template, so substitution leaves it;
+    // the real `{{y}}` value is still substituted and the JSON stays valid.
+    expect(validateJsonTemplate('{"a": "{{", "b": {{y}}}')).toEqual([]);
+  });
+});