@telorun/assert 0.1.0

package/src/events.ts

@@ -0,0 +1,140 @@
+import { Static, Type } from "@sinclair/typebox";
+import { ResourceContext } from "@telorun/sdk";
+
+const FilterEntry = Type.Object({
+  type: Type.String(),
+});
+
+const ExpectEntry = Type.Object({
+  event: Type.String(),
+  payload: Type.Optional(Type.Record(Type.String(), Type.Any())),
+});
+
+export const schema = Type.Object({
+  metadata: Type.Object({
+    name: Type.String(),
+  }),
+  filter: Type.Optional(Type.Array(FilterEntry)),
+  expect: Type.Array(ExpectEntry),
+});
+
+type AssertManifest = Static<typeof schema>;
+
+type CapturedEvent = {
+  name: string;
+  payload?: any;
+};
+
+type ExpectEntry = Static<typeof ExpectEntry>;
+
+type MatchResult =
+  | { status: "matched"; entry: ExpectEntry; actual: CapturedEvent }
+  | { status: "payload-mismatch"; entry: ExpectEntry; actual: CapturedEvent }
+  | { status: "not-found"; entry: ExpectEntry };
+
+function matchesPattern(pattern: string, eventName: string): boolean {
+  if (pattern === "*") return true;
+  if (pattern === eventName) return true;
+  if (!pattern.includes("*")) return false;
+  const patternParts = pattern.split(".");
+  const eventParts = eventName.split(".");
+  if (patternParts.length !== eventParts.length) return false;
+  for (let i = 0; i < patternParts.length; i++) {
+    if (patternParts[i] !== "*" && patternParts[i] !== eventParts[i]) return false;
+  }
+  return true;
+}
+
+function matchesPayload(actual: any, expected: Record<string, any>): boolean {
+  for (const [key, value] of Object.entries(expected)) {
+    if (actual == null) return false;
+    if (typeof value === "object" && value !== null) {
+      if (!matchesPayload(actual[key], value)) return false;
+    } else {
+      if (actual[key] !== value) return false;
+    }
+  }
+  return true;
+}
+
+export async function create(manifest: AssertManifest, ctx: ResourceContext) {
+  const useColor = (ctx.stderr as any).isTTY ?? false;
+  const c = (code: string, text: string) => (useColor ? `\x1b[${code}m${text}\x1b[0m` : text);
+  const bold = (t: string) => c("1", t);
+  const red = (t: string) => c("31", t);
+  const green = (t: string) => c("32", t);
+  const yellow = (t: string) => c("33", t);
+  const dim = (t: string) => c("2", t);
+
+  function buildReport(name: string, captured: CapturedEvent[], expect: ExpectEntry[]) {
+    const results: MatchResult[] = [];
+    let pos = 0;
+
+    for (const entry of expect) {
+      let found = false;
+      while (pos < captured.length) {
+        const ev = captured[pos++];
+        if (matchesPattern(entry.event, ev.name)) {
+          if (!entry.payload || matchesPayload(ev.payload, entry.payload)) {
+            results.push({ status: "matched", entry, actual: ev });
+          } else {
+            results.push({ status: "payload-mismatch", entry, actual: ev });
+          }
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        results.push({ status: "not-found", entry });
+      }
+    }
+
+    const failures = results.filter((r) => r.status !== "matched");
+
+    let report =
+      bold(
+        failures.length > 0
+          ? red(`Assert.Events.${name}: assertion failed`)
+          : green(`Assert.Events.${name}: assertion passed`),
+      ) + "\n";
+    for (const result of results) {
+      if (result.status === "matched") {
+        report += `  ${green("✓")} ${dim(result.actual.name)}\n`;
+      } else if (result.status === "not-found") {
+        report += `  ${red("✗")} ${result.entry.event}  ${dim("← not found in stream")}\n`;
+        if (result.entry.payload) {
+          report += `       ${dim("expected payload:")} ${yellow(JSON.stringify(result.entry.payload))}\n`;
+        }
+      } else if (result.status === "payload-mismatch") {
+        report += `  ${red("✗")} ${result.actual.name}\n`;
+        report += `       ${dim("expected payload:")} ${yellow(JSON.stringify(result.entry.payload))}\n`;
+        report += `       ${dim("actual payload:  ")} ${red(JSON.stringify(result.actual.payload))}\n`;
+      }
+    }
+
+    return { report, passed: failures.length === 0 };
+  }
+
+  const captured: CapturedEvent[] = [];
+  const filters = manifest.filter ?? [{ type: "*" }];
+
+  ctx.on("*", (event) => {
+    if (filters.some((f) => matchesPattern(f.type, event.name))) {
+      captured.push({ name: event.name, payload: event.payload });
+    }
+  });
+
+  return {
+    run: async () => {
+      const report = buildReport(manifest.metadata.name, captured, manifest.expect);
+      if (report) {
+        if (report.passed) {
+          ctx.stdout.write(report.report);
+        } else {
+          ctx.stderr.write(report.report);
+          ctx.requestExit(1);
+        }
+      }
+    },
+  };
+}

package/src/manifest.ts

@@ -0,0 +1,198 @@
+import { DEFAULT_MANIFEST_FILENAME, Loader, StaticAnalyzer, flattenForAnalyzer, type AnalysisDiagnostic, type ManifestSource } from "@telorun/analyzer";
+import type { ResourceContext, Runnable } from "@telorun/sdk";
+import * as fs from "fs/promises";
+import * as path from "path";
+
+interface ExpectError {
+  code?: string;
+  message?: string;
+}
+
+interface ManifestAssertManifest {
+  metadata: { name: string; module?: string };
+  source: string;
+  expect: {
+    errors?: ExpectError[];
+    warnings?: ExpectError[];
+    loadError?: string;
+  };
+}
+
+class LocalFileSource implements ManifestSource {
+  supports(p: string): boolean {
+    return (
+      p.startsWith("file://") ||
+      p.startsWith("/") ||
+      p.startsWith("./") ||
+      p.startsWith("../") ||
+      (!p.includes("://") && !p.includes("@"))
+    );
+  }
+
+  async read(p: string): Promise<{ text: string; source: string }> {
+    const norm = p.startsWith("file://") ? new URL(p).pathname : p;
+    const resolved = path.resolve(norm);
+    const stat = await fs.stat(resolved);
+    const filePath = stat.isDirectory() ? path.join(resolved, DEFAULT_MANIFEST_FILENAME) : resolved;
+    const text = await fs.readFile(filePath, "utf-8");
+    return { text, source: `file://${filePath}` };
+  }
+
+  async readAll(p: string): Promise<string[]> {
+    const norm = p.startsWith("file://") ? new URL(p).pathname : p;
+    const resolved = path.resolve(norm);
+    const stat = await fs.stat(resolved);
+    if (stat.isDirectory()) {
+      const entries = await fs.readdir(resolved);
+      return entries
+        .filter((e) => e.endsWith(".yaml") || e.endsWith(".yml"))
+        .map((e) => `file://${path.join(resolved, e)}`);
+    }
+    return [`file://${resolved}`];
+  }
+
+  resolveRelative(base: string, relative: string): string {
+    const basePath = base.startsWith("file://") ? new URL(base).pathname : base;
+    const baseDir = basePath.endsWith("/") ? basePath : path.dirname(basePath);
+    return `file://${path.resolve(baseDir, relative)}`;
+  }
+}
+
+function matchesDiagnostic(diag: AnalysisDiagnostic, expected: ExpectError): boolean {
+  if (expected.code && diag.code !== expected.code) return false;
+  if (expected.message && !diag.message.includes(expected.message)) return false;
+  return true;
+}
+
+export async function create(
+  manifest: ManifestAssertManifest,
+  ctx: ResourceContext,
+): Promise<Runnable> {
+  return {
+    run: async () => {
+      const useColor = (ctx.stderr as any).isTTY ?? false;
+      const c = (code: string, text: string) => (useColor ? `\x1b[${code}m${text}\x1b[0m` : text);
+      const bold = (t: string) => c("1", t);
+      const red = (t: string) => c("31", t);
+      const green = (t: string) => c("32", t);
+      const dim = (t: string) => c("2", t);
+
+      const name = manifest.metadata.name;
+      const loader = new Loader([new LocalFileSource()]);
+      const analyzer = new StaticAnalyzer();
+
+      const resolvedUrl = new URL(manifest.source, ctx.moduleContext.source).toString();
+      let manifests;
+      try {
+        const graph = await loader.loadGraph(resolvedUrl);
+        if (graph.errors.length > 0) throw graph.errors[0].error;
+        manifests = flattenForAnalyzer(graph);
+      } catch (err) {
+        const errMsg = err instanceof Error ? err.message : String(err);
+        if (manifest.expect.loadError) {
+          if (errMsg.includes(manifest.expect.loadError)) {
+            ctx.stdout.write(
+              bold(green(`Assert.Manifest.${name}: assertion passed`)) +
+                "\n  " + green("✓") + " " + dim(`load error: ${errMsg}`) + "\n",
+            );
+          } else {
+            ctx.stderr.write(
+              bold(red(`Assert.Manifest.${name}: assertion failed`)) +
+                "\n  " + red("✗") + ` expected load error containing "${manifest.expect.loadError}"` +
+                "\n  " + dim(`actual: ${errMsg}`) + "\n",
+            );
+            ctx.requestExit(1);
+          }
+          return;
+        }
+        ctx.stderr.write(
+          bold(red(`Assert.Manifest.${name}: failed to load "${manifest.source}"`)) +
+            "\n  " + errMsg + "\n",
+        );
+        ctx.requestExit(1);
+        return;
+      }
+
+      if (manifest.expect.loadError) {
+        ctx.stderr.write(
+          bold(red(`Assert.Manifest.${name}: assertion failed`)) +
+            "\n  " + red("✗") + ` expected load error containing "${manifest.expect.loadError}" but manifest loaded successfully\n`,
+        );
+        ctx.requestExit(1);
+        return;
+      }
+
+      const diagnostics = analyzer.analyze(manifests);
+      const errors = diagnostics.filter((d) => d.severity === 1); // DiagnosticSeverity.Error = 1
+      const warnings = diagnostics.filter((d) => d.severity === 2); // DiagnosticSeverity.Warning = 2
+      const expectedErrors = manifest.expect.errors ?? [];
+      const expectedWarnings = manifest.expect.warnings ?? [];
+      const failures: string[] = [];
+      const matched: string[] = [];
+
+      if (expectedErrors.length === 0) {
+        // Expect zero errors — any error is a failure
+        if (errors.length > 0) {
+          for (const d of errors) {
+            failures.push(`unexpected error: [${d.code}] ${d.message}`);
+          }
+        } else {
+          matched.push("no errors");
+        }
+      } else {
+        for (const expected of expectedErrors) {
+          const match = errors.find((d) => matchesDiagnostic(d, expected));
+          if (match) {
+            matched.push(
+              `${expected.code ?? "*"}${expected.message ? ` (${expected.message})` : ""}`,
+            );
+          } else {
+            failures.push(
+              `expected error ${expected.code ?? "*"}${expected.message ? ` containing "${expected.message}"` : ""} — not found`,
+            );
+          }
+        }
+      }
+
+      // Warnings are checked only when the caller declares expect.warnings. Unexpected
+      // warnings are not failures (unlike errors) — warnings are advisory and may exist
+      // on manifests that are otherwise valid. When expect.warnings is present, every
+      // listed warning must be found; extras are ignored.
+      if (expectedWarnings.length > 0) {
+        for (const expected of expectedWarnings) {
+          const match = warnings.find((d) => matchesDiagnostic(d, expected));
+          if (match) {
+            matched.push(
+              `warning ${expected.code ?? "*"}${expected.message ? ` (${expected.message})` : ""}`,
+            );
+          } else {
+            failures.push(
+              `expected warning ${expected.code ?? "*"}${expected.message ? ` containing "${expected.message}"` : ""} — not found`,
+            );
+          }
+        }
+      }
+
+      const passedLines = matched.map((m) => `  ${green("✓")} ${dim(m)}\n`).join("");
+      if (failures.length > 0) {
+        const failedLines = failures.map((f) => `  ${red("✗")} ${f}\n`).join("");
+        const actualLines =
+          errors.length > 0 || warnings.length > 0
+            ? `  ${dim("actual diagnostics:")}\n` +
+              [...errors, ...warnings]
+                .map((d) => `    ${dim(`[${d.code}] ${d.message}`)}\n`)
+                .join("")
+            : `  ${dim("no diagnostics produced")}\n`;
+        ctx.stderr.write(
+          bold(red(`Assert.Manifest.${name}: assertion failed`)) + "\n" +
+            passedLines + failedLines + actualLines,
+        );
+        ctx.requestExit(1);
+      } else {
+        ctx.stdout.write(
+          bold(green(`Assert.Manifest.${name}: assertion passed`)) + "\n" + passedLines,
+        );
+      }
+    },
+  };
+}

package/src/matches.ts

@@ -0,0 +1,69 @@
+import { InvokeError, ResourceContext } from "@telorun/sdk";
+import { Static, Type } from "@sinclair/typebox";
+import { createColors } from "./colors.js";
+
+export const schema = Type.Object({
+  metadata: Type.Object({
+    name: Type.String(),
+  }),
+});
+
+type AssertManifest = Static<typeof schema>;
+
+interface MatchesInput {
+  actual: unknown;
+  pattern: string;
+  flags?: string;
+}
+
+export async function create(manifest: AssertManifest, ctx: ResourceContext) {
+  const { bold, red, green, dim } = createColors(ctx);
+  const name = manifest.metadata.name;
+
+  return {
+    invoke: (input: MatchesInput) => {
+      const { actual, pattern, flags } = input ?? ({} as MatchesInput);
+
+      if (typeof pattern !== "string") {
+        throw new InvokeError(
+          "ERR_INVALID_CONFIG",
+          `Assert.Matches "${name}": 'pattern' must be a string`,
+        );
+      }
+      let regex: RegExp;
+      try {
+        regex = new RegExp(pattern, flags ?? "");
+      } catch (err) {
+        throw new InvokeError(
+          "ERR_INVALID_CONFIG",
+          `Assert.Matches "${name}": invalid pattern — ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+
+      if (typeof actual !== "string") {
+        const message = `actual must be a string; got ${typeof actual}`;
+        ctx.stderr.write(
+          bold(red(`Assert.Matches.${name}: assertion failed`)) +
+            "\n" +
+            `  ${red("✗")} ${message}\n`,
+        );
+        throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Matches "${name}": ${message}`);
+      }
+      if (regex.test(actual)) {
+        ctx.stdout.write(
+          bold(green(`Assert.Matches.${name}: assertion passed`)) +
+            "\n" +
+            `  ${green("✓")} ${dim(JSON.stringify(actual))} ${dim("~")} ${dim(regex.toString())}\n`,
+        );
+        return true;
+      }
+      const message = `${JSON.stringify(actual)} does not match ${regex.toString()}`;
+      ctx.stderr.write(
+        bold(red(`Assert.Matches.${name}: assertion failed`)) +
+          "\n" +
+          `  ${red("✗")} ${message}\n`,
+      );
+      throw new InvokeError("ERR_ASSERTION_FAILED", `Assert.Matches "${name}": ${message}`);
+    },
+  };
+}

package/src/module-context.ts

@@ -0,0 +1,96 @@
+import { Static, Type } from "@sinclair/typebox";
+import { ResourceContext, Runnable } from "@telorun/sdk";
+
+const ImportEntry = Type.Object({
+  variables: Type.Optional(Type.Record(Type.String(), Type.Any())),
+  secrets: Type.Optional(Type.Record(Type.String(), Type.Any())),
+});
+
+export const schema = Type.Object({
+  metadata: Type.Object({
+    name: Type.String(),
+    module: Type.Optional(Type.String()),
+  }),
+  resources: Type.Optional(Type.Record(Type.String(), ImportEntry)),
+  variables: Type.Optional(Type.Record(Type.String(), Type.Any())),
+  secrets: Type.Optional(Type.Record(Type.String(), Type.Any())),
+});
+
+type ModuleContextManifest = Static<typeof schema>;
+
+function createColors(stream: NodeJS.WritableStream) {
+  const useColor = (stream as any).isTTY ?? false;
+  const c = (code: string, text: string) => (useColor ? `\x1b[${code}m${text}\x1b[0m` : text);
+  return {
+    bold: (t: string) => c("1", t),
+    red: (t: string) => c("31", t),
+    green: (t: string) => c("32", t),
+    yellow: (t: string) => c("33", t),
+    dim: (t: string) => c("2", t),
+  };
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== "object" || typeof b !== "object") return false;
+  const aKeys = Object.keys(a as object);
+  const bKeys = Object.keys(b as object);
+  if (aKeys.length !== bKeys.length) return false;
+  for (const key of aKeys) {
+    if (!deepEqual((a as any)[key], (b as any)[key])) return false;
+  }
+  return true;
+}
+
+export async function create(
+  manifest: ModuleContextManifest,
+  ctx: ResourceContext,
+): Promise<Runnable> {
+  return {
+    run: async () => {
+      const { bold, red, green, yellow, dim } = createColors(ctx.stderr);
+      const resourcesToCheck = manifest.resources ?? {};
+      const failures: string[] = [];
+      const passed: string[] = [];
+      const { resources } = ctx.moduleContext;
+      for (const [alias, expected] of Object.entries(resourcesToCheck)) {
+        if (!ctx.moduleContext.hasImport(alias)) {
+          failures.push(`Import alias '${alias}' not found in declaring module`);
+          continue;
+        }
+
+        const snap = (resources[alias] as any) ?? {};
+        const path = `resources.${alias}`;
+
+        for (const [key, expectedValue] of Object.entries(expected.variables ?? {})) {
+          const actual = snap?.variables?.[key];
+          if (deepEqual(actual, expectedValue)) {
+            passed.push(`${path}.variables.${key}`);
+          } else {
+            failures.push(`${path}.variables.${key}: expected ${yellow(JSON.stringify(expectedValue))}, got ${red(JSON.stringify(actual))}`);
+          }
+        }
+
+        for (const [key, expectedValue] of Object.entries(expected.secrets ?? {})) {
+          const actual = snap?.secrets?.[key];
+          if (deepEqual(actual, expectedValue)) {
+            passed.push(`${path}.secrets.${key}`);
+          } else {
+            failures.push(`${path}.secrets.${key}: ${dim("value mismatch")}`);
+          }
+        }
+      }
+
+      const name = manifest.metadata.name;
+      const passedLines = passed.map((p) => `  ${green("✓")} ${dim(p)}\n`).join("");
+      if (failures.length > 0) {
+        const failedLines = failures.map((f) => `  ${red("✗")} ${f}\n`).join("");
+        ctx.stderr.write(bold(red(`Assert.ModuleContext.${name}: assertion failed`)) + "\n" + passedLines + failedLines);
+        ctx.requestExit(1);
+      } else {
+        ctx.stdout.write(bold(green(`Assert.ModuleContext.${name}: assertion passed`)) + "\n" + passedLines);
+      }
+    },
+  };
+}

package/src/schema.ts

@@ -0,0 +1,37 @@
+import { ResourceContext } from "@telorun/sdk";
+import { Static, Type } from "@sinclair/typebox";
+
+export const schema = Type.Object({
+  metadata: Type.Object({
+    name: Type.String(),
+  }),
+  schema: Type.Object({
+    type: Type.String(),
+  }),
+});
+
+type AssertManifest = Static<typeof schema>;
+
+export async function create(manifest: AssertManifest, ctx: ResourceContext) {
+  const useColor = (ctx.stderr as any).isTTY ?? false;
+  const c = (code: string, text: string) => (useColor ? `\x1b[${code}m${text}\x1b[0m` : text);
+  const bold = (t: string) => c("1", t);
+  const red = (t: string) => c("31", t);
+  const green = (t: string) => c("32", t);
+  const dim = (t: string) => c("2", t);
+
+  const validator = ctx.createSchemaValidator(manifest.schema);
+  const name = manifest.metadata.name;
+  return {
+    invoke: (data: any) => {
+      try {
+        validator.validate(data);
+        ctx.stdout.write(bold(green(`Assert.Schema.${name}: assertion passed`)) + "\n" + `  ${green("✓")} ${dim(JSON.stringify(data))}\n`);
+        return true;
+      } catch (err: any) {
+        ctx.stderr.write(bold(red(`Assert.Schema.${name}: assertion failed`)) + "\n" + `  ${red("✗")} ${err?.message ?? String(err)}\n`);
+        throw err;
+      }
+    },
+  };
+}