@intentius/chant-lexicon-cedar 0.44.8

package/src/config-namespace.test.ts

@@ -0,0 +1,44 @@
+/**
+ * The `cedar` namespace is read, not just declared (#1344, #1650).
+ *
+ * A `configSchema` that nothing consumes is worse than none: it validates a key
+ * that has no effect, which reads as a working knob. These tests pin the path
+ * from `chant.config.ts` to the schema `generate()` actually opens.
+ */
+
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadCedarConfig } from "./config";
+import { resolveSchemaPath } from "./spec/fetch";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+describe("loadCedarConfig", () => {
+  it("reads the namespace out of a project config", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "cedar-config-"));
+    writeFileSync(
+      join(dir, "chant.config.json"),
+      JSON.stringify({ lexicons: ["cedar"], cedar: { schema: "authz/app.cedarschema" } }),
+    );
+    expect(await loadCedarConfig(dir)).toEqual({ schema: "authz/app.cedarschema" });
+  });
+
+  it("returns an empty namespace when the project declares none", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "cedar-config-"));
+    writeFileSync(join(dir, "chant.config.json"), JSON.stringify({ lexicons: ["cedar"] }));
+    expect(await loadCedarConfig(dir)).toEqual({});
+  });
+
+  it("reaches the schema the example's config points at", async () => {
+    const example = join(pkgDir, "examples", "basic-policies");
+    const config = await loadCedarConfig(example);
+    expect(config.schema).toBe("schema.cedarschema");
+    expect(resolveSchemaPath({ projectRoot: example, config })).toEqual({
+      path: join(example, "schema.cedarschema"),
+      isDefault: false,
+    });
+  });
+});

package/src/config.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+import { cedarConfigSchema, CEDAR_DEFAULT_SCHEMA_PATH } from "./config";
+import { cedarPlugin } from "./plugin";
+import { resolveSchemaPath, defaultSchemaPath } from "./spec/fetch";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+describe("cedar config namespace", () => {
+  it("is declared on the plugin, so core validates it at load", () => {
+    expect(cedarPlugin.configSchema).toBe(cedarConfigSchema);
+  });
+
+  it("accepts the documented shape", () => {
+    const parsed = cedarConfigSchema.parse({
+      schema: "authz/app.cedarschema",
+      validation: { mode: "strict", warnings: "warn", requireProjectSchema: true },
+    });
+    expect(parsed.schema).toBe("authz/app.cedarschema");
+  });
+
+  it("rejects an unknown key inside the namespace", () => {
+    expect(() => cedarConfigSchema.parse({ shema: "app.cedarschema" })).toThrow();
+  });
+
+  it("rejects an unknown key one level down, where a typo actually lands", () => {
+    expect(() => cedarConfigSchema.parse({ validation: { requireSchema: true } })).toThrow();
+  });
+
+  it("rejects a validation mode cedar-wasm does not implement", () => {
+    // `ValidationMode` in 4.12.0 is `"strict"` and nothing else; anything more
+    // throws from inside the wasm rather than returning a failure (#1648 §5.7).
+    expect(() => cedarConfigSchema.parse({ validation: { mode: "permissive" } })).toThrow();
+  });
+
+  it("leaves everything optional, so an empty namespace is legal", () => {
+    expect(cedarConfigSchema.parse({})).toEqual({});
+  });
+});
+
+describe("schema resolution", () => {
+  it("falls back to the bundled default when the project has no schema", () => {
+    const resolved = resolveSchemaPath({ projectRoot: join(pkgDir, "nowhere") });
+    expect(resolved.isDefault).toBe(true);
+    expect(resolved.path).toBe(defaultSchemaPath());
+  });
+
+  it("reads the configured path when it exists", () => {
+    const example = join(pkgDir, "examples", "basic-policies");
+    const resolved = resolveSchemaPath({ projectRoot: example, config: { schema: "schema.cedarschema" } });
+    expect(resolved.isDefault).toBe(false);
+    expect(resolved.path).toBe(join(example, "schema.cedarschema"));
+  });
+
+  it("looks for the default filename when nothing is configured", () => {
+    const example = join(pkgDir, "examples", "basic-policies");
+    expect(CEDAR_DEFAULT_SCHEMA_PATH).toBe("schema.cedarschema");
+    expect(resolveSchemaPath({ projectRoot: example }).path).toBe(join(example, CEDAR_DEFAULT_SCHEMA_PATH));
+  });
+
+  it("refuses the fallback when requireProjectSchema is on", () => {
+    expect(() =>
+      resolveSchemaPath({
+        projectRoot: join(pkgDir, "nowhere"),
+        config: { validation: { requireProjectSchema: true } },
+      }),
+    ).toThrow(/no schema found/);
+  });
+});
+
+describe("upstream pin declaration", () => {
+  it("points at a constant its own pattern finds", async () => {
+    const pin = cedarPlugin.upstreamPin;
+    expect(pin).toBeDefined();
+    const { readFileSync } = await import("node:fs");
+    const source = readFileSync(join(pkgDir, pin!.file), "utf-8");
+    const match = pin!.pattern.exec(source);
+    expect(match?.[1]).toBe("4.12.0");
+    expect(pin!.replace("4.13.0", match![0])).toContain('"4.13.0"');
+  });
+});

package/src/config.ts

@@ -0,0 +1,119 @@
+/**
+ * The `cedar` namespace in `chant.config.ts` (#1344, #1650).
+ *
+ * ```ts
+ * import type { ChantConfig } from "@intentius/chant/config";
+ * import "@intentius/chant-lexicon-cedar";   // brings the `cedar` key into ChantConfig
+ *
+ * export default {
+ *   lexicons: ["cedar"],
+ *   cedar: {
+ *     schema: "authz/app.cedarschema",
+ *     validation: { mode: "strict", warnings: "warn" },
+ *   },
+ * } satisfies ChantConfig;
+ * ```
+ *
+ * Cedar is the one lexicon whose codegen input is the *project's* file rather
+ * than a global upstream (epic #1645), so this namespace is not a convenience —
+ * it is where `generate()` is told what to read. A typo in the path is the
+ * difference between "your entity types" and "the bundled default schema",
+ * which is exactly the kind of silent fallback `z.strictObject` exists to stop
+ * one level down.
+ */
+
+import { z } from "zod";
+import type { ChantConfig } from "@intentius/chant/config";
+
+/**
+ * Where `generate()` looks when `cedar.schema` is unset.
+ *
+ * Relative to the project root (the directory holding `chant.config.ts`).
+ */
+export const CEDAR_DEFAULT_SCHEMA_PATH = "schema.cedarschema";
+
+/**
+ * `strictObject`, not `object`. Core applies `.strict()` to the top level of a
+ * declared namespace itself; `validation` is nested, and is the lexicon's own
+ * to close.
+ */
+export const cedarConfigSchema = z.strictObject({
+  /**
+   * Path to the project's human-readable Cedar schema, relative to the project
+   * root. Defaults to {@link CEDAR_DEFAULT_SCHEMA_PATH}; when neither the
+   * configured path nor the default exists, generation falls back to the
+   * schema bundled at `src/spec/default-schema.cedarschema` so a fresh
+   * checkout still produces artifacts.
+   */
+  schema: z.string().optional(),
+
+  /**
+   * Knobs for the `cedar-wasm` validator. `mode` is a single-variant enum on
+   * purpose: `ValidationMode` in cedar-wasm 4.12.0 accepts `"strict"` and
+   * nothing else, and passing anything further throws (#1648 §5.7).
+   */
+  validation: z
+    .strictObject({
+      /** Validator mode. Only `"strict"` exists in this build of cedar-wasm. */
+      mode: z.literal("strict").optional(),
+      /**
+       * What to do with `validationWarnings` — the validator reports things
+       * like "policy is impossible" here, separately from errors.
+       */
+      warnings: z.enum(["ignore", "warn", "error"]).optional(),
+      /**
+       * Refuse to build when no project schema is found rather than falling
+       * back to the bundled default. Off by default so `chant init` works;
+       * worth turning on once a project has its own schema, because
+       * `checkParseSchema("")` succeeds and an empty schema validates
+       * everything clean (#1648 §1).
+       */
+      requireProjectSchema: z.boolean().optional(),
+    })
+    .optional(),
+});
+
+export type CedarConfig = z.infer<typeof cedarConfigSchema>;
+
+declare module "@intentius/chant/config" {
+  interface ChantConfig {
+    cedar?: CedarConfig;
+  }
+}
+
+/**
+ * Compile-time proof that the augmentation above reaches `ChantConfig` (#1344).
+ *
+ * Without it this line is `Property 'cedar' does not exist on type
+ * 'ChantConfig'`. It lives here rather than in a test because the root tsconfig
+ * excludes test files, so a compile-time claim asserted in one is checked by
+ * nothing.
+ */
+export type CedarConfigNamespace = NonNullable<ChantConfig["cedar"]>;
+
+/**
+ * Read the `cedar` namespace out of the project's config.
+ *
+ * Searches upward from `startDir`, so `chant generate` finds the config from a
+ * subdirectory the same way `chant build` does. A project with no config, or
+ * one with no `cedar` key, gets `{}` — the schema resolution order in
+ * `spec/fetch.ts` handles that case without needing to know why.
+ *
+ * Core has already validated the namespace against {@link cedarConfigSchema}
+ * by the time this reads it, so the parse here is a type narrowing rather than
+ * a second gate; it stays because a caller can point this at a directory core
+ * never loaded.
+ */
+export async function loadCedarConfig(startDir: string): Promise<CedarConfig> {
+  const { loadChantConfigUpward } = await import("@intentius/chant/config");
+  try {
+    const { config } = await loadChantConfigUpward(startDir);
+    const parsed = cedarConfigSchema.safeParse(config.cedar ?? {});
+    return parsed.success ? parsed.data : {};
+  } catch {
+    // A project whose config does not load is not this function's problem to
+    // report — every other command reports it first, and generation falling
+    // back to the bundled schema is the same behaviour as having no config.
+    return {};
+  }
+}

package/src/coverage.test.ts

@@ -0,0 +1,61 @@
+import { describe, expect, it } from "vitest";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { computeCedarCoverage, formatCedarCoverage } from "./coverage";
+
+const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+
+function generatedDirWith(registry: Record<string, unknown>): string {
+  const dir = mkdtempSync(join(tmpdir(), "cedar-coverage-"));
+  writeFileSync(join(dir, "lexicon-cedar.json"), JSON.stringify(registry));
+  return dir;
+}
+
+describe("cedar coverage", () => {
+  it("reports full coverage for artifacts generated from the same schema", () => {
+    const report = computeCedarCoverage({ projectRoot: join(pkgDir, "nowhere") });
+    expect(report.isDefaultSchema).toBe(true);
+    expect(report.entityTypes).toBe(7);
+    expect(report.actions).toBe(9);
+    expect(report.overallPct).toBe(100);
+  });
+
+  it("names the declarations the artifacts do not reach", () => {
+    // The failure this exists to catch: a schema action with no generated
+    // constant is an action a policy can only name as a hand-typed string.
+    const generatedDir = generatedDirWith({
+      User: { resourceType: "App::User", kind: "resource" },
+      UserAttributes: { resourceType: "App::User.Attributes", kind: "property" },
+    });
+
+    const report = computeCedarCoverage({ projectRoot: join(pkgDir, "nowhere"), generatedDir });
+    expect(report.entityTypesCovered).toBe(1);
+    expect(report.actionsCovered).toBe(0);
+    expect(report.actionPct).toBe(0);
+    expect(report.overallPct).toBeLessThan(100);
+
+    const gap = report.items.find((i) => i.name === 'App::Action::"read"');
+    expect(gap?.covered).toBe(false);
+    expect(formatCedarCoverage(report, true)).toContain("no generated declaration");
+  });
+
+  it("reports against a project schema when one is configured", () => {
+    const example = join(pkgDir, "examples", "basic-policies");
+    const report = computeCedarCoverage({ projectRoot: example, config: { schema: "schema.cedarschema" } });
+    expect(report.isDefaultSchema).toBe(false);
+    // The example's schema is a subset of the default one, so artifacts
+    // generated from either cover it.
+    expect(report.overallPct).toBe(100);
+  });
+
+  it("treats a schema with nothing in it as covered rather than dividing by zero", () => {
+    const generatedDir = generatedDirWith({});
+    const empty = mkdtempSync(join(tmpdir(), "cedar-empty-"));
+    writeFileSync(join(empty, "schema.cedarschema"), "");
+    const report = computeCedarCoverage({ projectRoot: empty, generatedDir });
+    expect(report.overallPct).toBe(100);
+    expect(report.entityTypes).toBe(0);
+  });
+});

package/src/coverage.ts

@@ -0,0 +1,166 @@
+/**
+ * Schema coverage for the cedar lexicon.
+ *
+ * Core's `computeCoverage` measures CloudFormation-shaped dimensions —
+ * property constraints, create-only/write-only lifecycle, return attributes —
+ * none of which a Cedar schema has. Reporting 0% across four axes that cannot
+ * apply would be worse than reporting nothing, so this asks the question that
+ * does mean something here: **is every entity type and every action in the
+ * schema reachable from the generated artifacts?**
+ *
+ * A gap is a real defect, not a nice-to-have. An action with no generated
+ * constant is an action a policy can only name as a hand-typed string, which
+ * is the exact failure mode the lexicon exists to remove.
+ */
+
+import { existsSync, readFileSync } from "fs";
+import { dirname, join } from "path";
+import { fileURLToPath } from "url";
+import { LEXICON_JSON_FILENAME } from "./codegen/generate";
+import { attributesTypeName, contextTypeName } from "./codegen/emit";
+import { readSchemaSource, type ResolveSchemaOptions } from "./spec/fetch";
+import { parseCedarSchema } from "./spec/parse";
+
+export interface CedarCoverageItem {
+  /** Fully-qualified declaration name from the schema. */
+  name: string;
+  kind: "entity" | "action";
+  /** True when a registry entry names this declaration. */
+  covered: boolean;
+  /** True when the record type beside it (attributes / context) is present too. */
+  recordCovered: boolean;
+  /** Attributes the schema declares for it. */
+  attributes: number;
+}
+
+export interface CedarCoverageReport {
+  /** Where the schema came from. */
+  schemaPath: string;
+  /** True when the bundled default schema was used. */
+  isDefaultSchema: boolean;
+  entityTypes: number;
+  entityTypesCovered: number;
+  actions: number;
+  actionsCovered: number;
+  recordTypes: number;
+  recordTypesCovered: number;
+  entityPct: number;
+  actionPct: number;
+  recordPct: number;
+  overallPct: number;
+  items: CedarCoverageItem[];
+}
+
+export interface CedarCoverageOptions extends ResolveSchemaOptions {
+  /** Directory holding the generated artifacts. Defaults to `<package>/src/generated`. */
+  generatedDir?: string;
+  verbose?: boolean;
+  /** Fail when `overallPct` falls below this. */
+  minOverall?: number;
+}
+
+function defaultGeneratedDir(): string {
+  return join(dirname(fileURLToPath(import.meta.url)), "generated");
+}
+
+function pct(covered: number, total: number): number {
+  return total === 0 ? 100 : Math.round((covered / total) * 100);
+}
+
+/** Compute schema coverage against the artifacts already on disk. */
+export function computeCedarCoverage(options: CedarCoverageOptions = {}): CedarCoverageReport {
+  const generatedDir = options.generatedDir ?? defaultGeneratedDir();
+  const registryPath = join(generatedDir, LEXICON_JSON_FILENAME);
+
+  const covered = new Set<string>();
+  if (existsSync(registryPath)) {
+    const registry = JSON.parse(readFileSync(registryPath, "utf-8")) as Record<string, { resourceType?: string }>;
+    for (const entry of Object.values(registry)) {
+      if (entry.resourceType) covered.add(entry.resourceType);
+    }
+  }
+
+  const source = readSchemaSource(options);
+  const { decls } = parseCedarSchema(source.text);
+
+  const items: CedarCoverageItem[] = decls
+    .map((decl) => {
+      const recordName =
+        decl.kind === "entity" ? attributesTypeName(decl.typeName) : contextTypeName(decl.typeName);
+      return {
+        name: decl.typeName,
+        kind: decl.kind,
+        covered: covered.has(decl.typeName),
+        recordCovered: covered.has(recordName),
+        attributes: decl.kind === "entity" ? decl.attributes.length : decl.context.length,
+      };
+    })
+    .sort((a, b) => a.name.localeCompare(b.name));
+
+  const entities = items.filter((i) => i.kind === "entity");
+  const actions = items.filter((i) => i.kind === "action");
+  const entityTypesCovered = entities.filter((i) => i.covered).length;
+  const actionsCovered = actions.filter((i) => i.covered).length;
+  const recordTypesCovered = items.filter((i) => i.recordCovered).length;
+
+  const entityPct = pct(entityTypesCovered, entities.length);
+  const actionPct = pct(actionsCovered, actions.length);
+  const recordPct = pct(recordTypesCovered, items.length);
+
+  return {
+    schemaPath: source.path,
+    isDefaultSchema: source.isDefault,
+    entityTypes: entities.length,
+    entityTypesCovered,
+    actions: actions.length,
+    actionsCovered,
+    recordTypes: items.length,
+    recordTypesCovered,
+    entityPct,
+    actionPct,
+    recordPct,
+    overallPct: Math.round((entityPct + actionPct + recordPct) / 3),
+    items,
+  };
+}
+
+/** Human-readable summary. */
+export function formatCedarCoverage(report: CedarCoverageReport, verbose = false): string {
+  const lines = [
+    `Cedar schema coverage — ${report.isDefaultSchema ? "bundled default schema" : report.schemaPath}`,
+    `  Entity types: ${report.entityTypesCovered}/${report.entityTypes} (${report.entityPct}%)`,
+    `  Actions:      ${report.actionsCovered}/${report.actions} (${report.actionPct}%)`,
+    `  Record types: ${report.recordTypesCovered}/${report.recordTypes} (${report.recordPct}%)`,
+    `  Overall:      ${report.overallPct}%`,
+  ];
+
+  if (verbose) {
+    lines.push("");
+    for (const item of report.items) {
+      const gaps: string[] = [];
+      if (!item.covered) gaps.push("no generated declaration");
+      if (!item.recordCovered) gaps.push(item.kind === "entity" ? "no attributes type" : "no context type");
+      lines.push(
+        gaps.length === 0
+          ? `  ${item.name}: covered (${item.attributes} attribute(s))`
+          : `  ${item.name}: ${gaps.join(", ")}`,
+      );
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Print the report, and throw when it falls below `minOverall`.
+ */
+export function analyzeCedarCoverage(options: CedarCoverageOptions = {}): CedarCoverageReport {
+  const report = computeCedarCoverage(options);
+  console.error(formatCedarCoverage(report, options.verbose));
+
+  if (options.minOverall !== undefined && report.overallPct < options.minOverall) {
+    throw new Error(`Cedar schema coverage ${report.overallPct}% is below the ${options.minOverall}% minimum`);
+  }
+
+  return report;
+}

package/src/detect.test.ts

@@ -0,0 +1,64 @@
+import { describe, test, expect } from "vitest";
+import { readFileSync } from "fs";
+import { join } from "path";
+import { detectTemplate } from "./detect";
+
+const testdata = (file: string) => readFileSync(join(import.meta.dirname, "import", "testdata", file), "utf8");
+
+describe("what cedar claims", () => {
+  test("the JSON policy-set envelope, parsed", () => {
+    expect(detectTemplate(JSON.parse(testdata("full.cedar.json")))).toBe(true);
+  });
+
+  test("the JSON policy-set envelope, as a raw string", () => {
+    expect(detectTemplate(testdata("full.cedar.json"))).toBe(true);
+  });
+
+  test("`.cedar` policy text", () => {
+    expect(detectTemplate(testdata("simple.cedar"))).toBe(true);
+    expect(detectTemplate(testdata("realistic.cedar"))).toBe(true);
+  });
+
+  test("a document that is only templates", () => {
+    expect(detectTemplate('@id("t") permit (principal == ?principal, action, resource);')).toBe(true);
+  });
+});
+
+describe("what cedar leaves alone", () => {
+  test("another lexicon's JSON", () => {
+    expect(detectTemplate({ apiVersion: "apps/v1", kind: "Deployment", metadata: { name: "web" } })).toBe(false);
+    expect(detectTemplate({ AWSTemplateFormatVersion: "2010-09-09", Resources: {} })).toBe(false);
+    expect(detectTemplate({ services: { web: { image: "nginx" } } })).toBe(false);
+    expect(detectTemplate({ $schema: "https://schema.management.azure.com/", resources: [] })).toBe(false);
+  });
+
+  test("an empty policy set — `{}` parses as one, and claiming it would swallow everything", () => {
+    expect(detectTemplate({})).toBe(false);
+    expect(detectTemplate({ staticPolicies: {} })).toBe(false);
+    expect(detectTemplate({ staticPolicies: {}, templates: {}, templateLinks: [] })).toBe(false);
+    expect(detectTemplate("")).toBe(false);
+    expect(detectTemplate("   ")).toBe(false);
+  });
+
+  test("an envelope with one foreign key beside the known ones", () => {
+    expect(detectTemplate({ staticPolicies: { p: {} }, Resources: {} })).toBe(false);
+  });
+
+  test("a well-formed envelope whose policies are not Cedar", () => {
+    expect(detectTemplate({ staticPolicies: { p: { effect: "maybe" } } })).toBe(false);
+  });
+
+  test("text that is not Cedar", () => {
+    expect(detectTemplate("FROM node:20\nRUN npm ci\n")).toBe(false);
+    expect(detectTemplate("apiVersion: v1\nkind: Pod\n")).toBe(false);
+    expect(detectTemplate("# a readme\n\nSome prose.\n")).toBe(false);
+  });
+
+  test("scalars, arrays and nothing", () => {
+    expect(detectTemplate(null)).toBe(false);
+    expect(detectTemplate(undefined)).toBe(false);
+    expect(detectTemplate(42)).toBe(false);
+    expect(detectTemplate([])).toBe(false);
+    expect(detectTemplate([{ staticPolicies: {} }])).toBe(false);
+  });
+});

package/src/detect.ts

@@ -0,0 +1,59 @@
+/**
+ * Edge-safe template detection for cedar (#426, #1653).
+ *
+ * Two documents belong to this lexicon: the JSON policy-set envelope the
+ * serializer writes, and `.cedar` policy text. The first is recognized by its
+ * shape and then confirmed by `checkParsePolicySet`; the second only by asking
+ * the module to split it.
+ *
+ * The shape test is strict on purpose. `chant import` walks every loaded
+ * plugin's `detectTemplate` in turn, so a lexicon that answers `true` for
+ * someone else's JSON steals the file. `staticPolicies`/`templates`/
+ * `templateLinks` and nothing else is a document no other lexicon writes, and
+ * a policy set with no policies in it is not claimed at all — `{}` parses
+ * perfectly well as an empty Cedar policy set, and matching it would swallow
+ * every empty JSON object in the repo.
+ */
+
+import { isPolicySetEnvelope } from "./import/parser";
+import { parsesAsPolicySet, splitPolicySet } from "./spec/wasm";
+
+/** Does the envelope actually carry a policy or a template? */
+function hasContent(envelope: Record<string, unknown>): boolean {
+  const count = (value: unknown): number => {
+    if (Array.isArray(value)) return value.length;
+    if (value && typeof value === "object") return Object.keys(value).length;
+    if (typeof value === "string") return value.trim().length > 0 ? 1 : 0;
+    return 0;
+  };
+  return count(envelope.staticPolicies) + count(envelope.templates) > 0;
+}
+
+/** Is this text a Cedar policy document with at least one policy in it? */
+function isPolicyText(content: string): boolean {
+  if (!content.trim()) return false;
+  const parts = splitPolicySet(content);
+  return parts.ok && parts.value.policies.length + parts.value.templates.length > 0;
+}
+
+export function detectTemplate(data: unknown): boolean {
+  if (typeof data === "string") {
+    const trimmed = data.trim();
+    if (!trimmed) return false;
+
+    // A string may still be the envelope — `chant import` hands the parsed
+    // object around, but the audit discovery path passes raw file contents.
+    if (trimmed.startsWith("{")) {
+      try {
+        return detectTemplate(JSON.parse(trimmed));
+      } catch {
+        return false;
+      }
+    }
+    return isPolicyText(trimmed);
+  }
+
+  if (!isPolicySetEnvelope(data)) return false;
+  if (!hasContent(data)) return false;
+  return parsesAsPolicySet(data);
+}