@intentius/chant 0.7.0 → 0.8.0

package/src/cli/commands/audit.test.ts

@@ -1,7 +1,13 @@
 import { describe, test, expect } from "vitest";
 import { fileURLToPath } from "url";
-import { auditCommand, discoverCiFiles, discoverManifests, discoverDocker, discoverCloudFormation, discoverArm, discoverGcp, discoverHelm, tokenForHost, coverageNotes } from "./audit";
-import { MissingLexiconError, type AuditInput } from "../../audit/core";
+import { auditCommand, tokenForHost, coverageNotes } from "./audit";
+import { discoverByDetection, loadAuditPlugins } from "../../audit/discover";
+import { MissingLexiconError, type AuditInput, type AuditLexicon } from "../../audit/core";
+
+/** Discover with all audit lexicons loaded, then keep one lexicon's inputs. */
+async function discoverLexicon(repo: string, lexicon: AuditLexicon): Promise<AuditInput[]> {
+  return discoverByDetection(repo, await loadAuditPlugins()).filter((i) => i.lexicon === lexicon);
+}
 import { readFileSync, existsSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
@@ -32,7 +38,7 @@ describe("auditCommand", () => {
 
   test("discovers and audits Kubernetes manifests", async () => {
     const repo = fileURLToPath(new URL("./__fixtures__/audit-k8s", import.meta.url));
-    const files = discoverManifests(repo);
+    const files = await discoverLexicon(repo, "k8s");
     expect(files.map((f) => f.path)).toContain("manifests/deploy.yaml");
     expect(files.every((f) => f.lexicon === "k8s")).toBe(true);
 
@@ -45,7 +51,7 @@ describe("auditCommand", () => {
 
   test("discovers and audits Docker artifacts (nested Dockerfile + compose)", async () => {
     const repo = fileURLToPath(new URL("./__fixtures__/audit-docker", import.meta.url));
-    const files = discoverDocker(repo);
+    const files = await discoverLexicon(repo, "docker");
     const paths = files.map((f) => f.path).sort();
     expect(paths).toContain("app/Dockerfile");
     expect(paths).toContain("docker-compose.yml");
@@ -60,7 +66,7 @@ describe("auditCommand", () => {
 
   test("discovers and audits CloudFormation (JSON and YAML)", async () => {
     const repo = fileURLToPath(new URL("./__fixtures__/audit-aws", import.meta.url));
-    const files = discoverCloudFormation(repo);
+    const files = await discoverLexicon(repo, "aws");
     const paths = files.map((f) => f.path).sort();
     expect(paths).toContain("template.json");
     expect(paths).toContain("stack.yaml");
@@ -77,7 +83,7 @@ describe("auditCommand", () => {
 
   test("discovers and audits Azure ARM templates", async () => {
     const repo = fileURLToPath(new URL("./__fixtures__/audit-azure", import.meta.url));
-    expect(discoverArm(repo).map((f) => f.path)).toContain("azuredeploy.json");
+    expect((await discoverLexicon(repo, "azure")).map((f) => f.path)).toContain("azuredeploy.json");
     const result = await auditCommand({ path: repo, format: "stylish" });
     expect(result.success).toBe(true);
     const ids = new Set(result.findings.map((f) => f.checkId));
@@ -86,10 +92,10 @@ describe("auditCommand", () => {
 
   test("discovers and audits GCP Config Connector (not misclassified as k8s)", async () => {
     const repo = fileURLToPath(new URL("./__fixtures__/audit-gcp", import.meta.url));
-    const gcp = discoverGcp(repo);
+    const gcp = await discoverLexicon(repo, "gcp");
     expect(gcp.map((f) => f.path).sort()).toEqual(["bucket.yaml", "firewall.yaml"]);
     // cnrm manifests must NOT also be picked up as k8s.
-    expect(discoverManifests(repo)).toEqual([]);
+    expect(await discoverLexicon(repo, "k8s")).toEqual([]);
 
     const result = await auditCommand({ path: repo, format: "stylish" });
     expect(result.success).toBe(true);
@@ -101,7 +107,7 @@ describe("auditCommand", () => {
 
   test("discovers and audits a Helm chart (as a bundle, not loose manifests)", async () => {
     const repo = fileURLToPath(new URL("./__fixtures__/audit-helm", import.meta.url));
-    const charts = discoverHelm(repo);
+    const charts = await discoverLexicon(repo, "helm");
     expect(charts).toHaveLength(1);
     expect(charts[0].lexicon).toBe("helm");
     expect(charts[0].files!["Chart.yaml"]).toContain("name: mychart");
@@ -116,8 +122,8 @@ describe("auditCommand", () => {
     expect([...ids].some((id) => id.startsWith("WK8"))).toBe(false);
   });
 
-  test("discovers CI files under a repo root", () => {
-    const files = discoverCiFiles(REPO);
+  test("discovers CI files under a repo root", async () => {
+    const files = await discoverLexicon(REPO, "github");
     expect(files.map((f) => f.path)).toContain(".github/workflows/ci.yml");
     expect(files.every((f) => f.lexicon === "github")).toBe(true);
   });
@@ -168,7 +174,7 @@ describe("auditCommand", () => {
     expect(result.success).toBe(true);
     expect(result.wroteTo).toBe(out);
     expect(existsSync(out)).toBe(true);
-    expect(readFileSync(out, "utf-8")).toContain("# CI security audit");
+    expect(readFileSync(out, "utf-8")).toContain("# chant audit");
     rmSync(out);
   });
 
@@ -191,7 +197,7 @@ describe("auditCommand", () => {
     const result = await auditCommand({ path: tmp });
     expect(result.success).toBe(true);
     expect(result.exitCode).toBe(0);
-    expect(result.output).toContain("No CI files found");
+    expect(result.output).toContain("No auditable files found");
     rmSync(tmp, { recursive: true, force: true });
   });
 
@@ -200,12 +206,13 @@ describe("auditCommand", () => {
     const yaml = "name: CI\non:\n  push:\npermissions: write-all\njobs:\n  build:\n    runs-on: ubuntu-latest\n";
     const impl = (async (url: string | URL | Request) => {
       const u = String(url);
+      if (u.includes("/git/trees/")) {
+        return new Response(JSON.stringify({ tree: [{ path: ".github/workflows/ci.yml", type: "blob", size: 100 }] }), { status: 200 });
+      }
       if (u.includes("/contents/.github/workflows/ci.yml")) {
         return new Response(JSON.stringify({ name: "ci.yml", path: ".github/workflows/ci.yml", type: "file", content: b64(yaml), encoding: "base64" }), { status: 200 });
       }
-      if (u.includes("/contents/.github/workflows")) {
-        return new Response(JSON.stringify([{ name: "ci.yml", path: ".github/workflows/ci.yml", type: "file", size: 100 }]), { status: 200 });
-      }
+      if (/\/repos\/acme\/widgets(\?|$)/.test(u)) return new Response(JSON.stringify({ default_branch: "main" }), { status: 200 });
       return new Response("not found", { status: 404 });
     }) as unknown as typeof fetch;
 
@@ -222,12 +229,13 @@ describe("auditCommand", () => {
     const impl = (async (url: string | URL | Request) => {
       const u = String(url);
       if (u.includes("/commits/v4")) return new Response(JSON.stringify({ sha }), { status: 200 });
+      if (u.includes("/git/trees/")) {
+        return new Response(JSON.stringify({ tree: [{ path: ".github/workflows/ci.yml", type: "blob", size: 100 }] }), { status: 200 });
+      }
       if (u.includes("/contents/.github/workflows/ci.yml")) {
         return new Response(JSON.stringify({ name: "ci.yml", path: ".github/workflows/ci.yml", type: "file", content: b64(yaml), encoding: "base64" }), { status: 200 });
       }
-      if (u.includes("/contents/.github/workflows")) {
-        return new Response(JSON.stringify([{ name: "ci.yml", path: ".github/workflows/ci.yml", type: "file", size: 100 }]), { status: 200 });
-      }
+      if (/\/repos\/acme\/widgets(\?|$)/.test(u)) return new Response(JSON.stringify({ default_branch: "main" }), { status: 200 });
       return new Response("not found", { status: 404 });
     }) as unknown as typeof fetch;
 

package/src/cli/commands/audit.ts

@@ -1,19 +1,18 @@
 /**
- * `chant audit` — run chant's CI security checks against an existing repo's
+ * `chant audit` — run chant's security, correctness, and best-practice checks against an existing repo's
  * pipeline YAML and emit a tiered report. Does not require a chant project;
  * it reads `.github/workflows`, `.gitlab-ci.yml`, and `.forgejo/workflows`
  * directly and runs the real post-synth checks via the audit core.
  */
 
-import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
-import { join, relative, basename } from "path";
-import { parseYAML } from "../../yaml";
-import { auditFiles, type AuditInput, type AuditFinding, type AuditLexicon, type ChecksProvider } from "../../audit/core";
+import { existsSync, statSync, writeFileSync } from "fs";
+import { auditFiles, type AuditInput, type AuditFinding, type ChecksProvider } from "../../audit/core";
+import { discoverByDetection, classifyFiles, loadAuditPlugins, AUDIT_LEXICONS } from "../../audit/discover";
 import { RULE_CATALOG } from "../../audit/catalog";
 import { renderMarkdown } from "../../audit/report";
 import { renderHtml, type ReportTheme } from "../../audit/report-html";
 import { buildReportJson, type AuditSnapshot } from "../../audit/report-model";
-import { fetchCiFiles, resolveActionSha, resolveImageDigest, resolveRepoCommit, parseRepoUrl, FetchError } from "../../audit/fetch";
+import { fetchRepoFiles, resolveActionSha, resolveImageDigest, resolveRepoCommit, parseRepoUrl, FetchError } from "../../audit/fetch";
 import { extractUnpinnedActions, extractUnpinnedImages } from "../../audit/proof";
 import type { ProveOptions } from "../../audit/proof";
 import type { Severity } from "../../lint/rule";
@@ -89,255 +88,6 @@ function githubToken(env: NodeJS.ProcessEnv = process.env): string | undefined {
   return env.GITHUB_TOKEN ?? env.CHANT_AUDIT_GITHUB_TOKEN;
 }
 
-function isYaml(name: string): boolean {
-  return name.endsWith(".yml") || name.endsWith(".yaml");
-}
-
-function collectDir(root: string, dir: string, lexicon: AuditLexicon, out: AuditInput[]): void {
-  const abs = join(root, dir);
-  if (!existsSync(abs) || !statSync(abs).isDirectory()) return;
-  for (const name of readdirSync(abs).sort()) {
-    if (!isYaml(name)) continue;
-    const full = join(abs, name);
-    if (!statSync(full).isFile()) continue;
-    out.push({ path: relative(root, full), content: readFileSync(full, "utf-8"), lexicon });
-  }
-}
-
-/** Discover CI files under a repo root. */
-export function discoverCiFiles(root: string): AuditInput[] {
-  const inputs: AuditInput[] = [];
-  collectDir(root, ".github/workflows", "github", inputs);
-  collectDir(root, ".forgejo/workflows", "forgejo", inputs);
-  const gitlab = join(root, ".gitlab-ci.yml");
-  if (existsSync(gitlab) && statSync(gitlab).isFile()) {
-    inputs.push({ path: ".gitlab-ci.yml", content: readFileSync(gitlab, "utf-8"), lexicon: "gitlab" });
-  }
-  return inputs;
-}
-
-const WALK_SKIP = new Set(["node_modules", ".git", "dist", ".github", ".forgejo"]);
-const MAX_WALK_FILES = 1000;
-
-/** Recursively collect file paths under a root, skipping noise/dot dirs. */
-function walkFiles(dir: string, out: string[]): void {
-  if (out.length >= MAX_WALK_FILES) return;
-  let entries;
-  try {
-    entries = readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const e of entries.sort((a, b) => (a.name < b.name ? -1 : 1))) {
-    if (out.length >= MAX_WALK_FILES) return;
-    if (e.name.startsWith(".") && e.isDirectory()) continue;
-    if (WALK_SKIP.has(e.name)) continue;
-    const full = join(dir, e.name);
-    if (e.isDirectory()) walkFiles(full, out);
-    else out.push(full);
-  }
-}
-
-function readSafe(full: string): string | undefined {
-  try {
-    return readFileSync(full, "utf-8");
-  } catch {
-    return undefined;
-  }
-}
-
-const CNRM = "cnrm.cloud.google.com";
-
-/** True if any YAML doc is a Kubernetes manifest (excluding GCP Config Connector). */
-function looksLikeK8s(content: string): boolean {
-  for (const doc of content.split(/\n---\n/)) {
-    const t = doc.trim();
-    if (!t) continue;
-    try {
-      const obj = parseYAML(t) as Record<string, unknown>;
-      const apiVersion = obj?.apiVersion;
-      if (typeof apiVersion === "string" && typeof obj.kind === "string" && !apiVersion.includes(CNRM)) return true;
-    } catch {
-      // not parseable as a single doc — skip
-    }
-  }
-  return false;
-}
-
-/** True if any YAML doc is a GCP Config Connector resource (cnrm.cloud.google.com). */
-function looksLikeGcp(content: string): boolean {
-  for (const doc of content.split(/\n---\n/)) {
-    const t = doc.trim();
-    if (!t) continue;
-    try {
-      const obj = parseYAML(t) as Record<string, unknown>;
-      if (typeof obj?.apiVersion === "string" && obj.apiVersion.includes(CNRM)) return true;
-    } catch {
-      // skip
-    }
-  }
-  return false;
-}
-
-/** Discover GCP Config Connector manifests under a repo root. */
-export function discoverGcp(root: string): AuditInput[] {
-  const files: string[] = [];
-  walkFiles(root, files);
-  const inputs: AuditInput[] = [];
-  for (const full of files) {
-    if (!isYaml(basename(full))) continue;
-    const content = readSafe(full);
-    if (content !== undefined && looksLikeGcp(content)) {
-      inputs.push({ path: relative(root, full), content, lexicon: "gcp" });
-    }
-  }
-  return inputs;
-}
-
-/** Discover Kubernetes manifest files under a repo root (content-detected). */
-export function discoverManifests(root: string): AuditInput[] {
-  const files: string[] = [];
-  walkFiles(root, files);
-  const inputs: AuditInput[] = [];
-  for (const full of files) {
-    if (!isYaml(basename(full))) continue;
-    const content = readSafe(full);
-    if (content !== undefined && looksLikeK8s(content)) {
-      inputs.push({ path: relative(root, full), content, lexicon: "k8s" });
-    }
-  }
-  return inputs;
-}
-
-function isDockerfileName(name: string): boolean {
-  return name === "Dockerfile" || name.startsWith("Dockerfile.") || name.endsWith(".Dockerfile") || name.endsWith(".dockerfile");
-}
-
-function looksLikeCompose(content: string): boolean {
-  try {
-    const obj = parseYAML(content) as Record<string, unknown>;
-    return Boolean(obj) && typeof obj === "object" && "services" in obj;
-  } catch {
-    return false;
-  }
-}
-
-/** Parse JSON or YAML content into an object, or undefined. */
-function parseStructured(content: string): Record<string, unknown> | undefined {
-  try {
-    const j = JSON.parse(content);
-    if (j && typeof j === "object") return j as Record<string, unknown>;
-  } catch {
-    // not JSON — try YAML
-  }
-  try {
-    const y = parseYAML(content) as Record<string, unknown>;
-    if (y && typeof y === "object") return y;
-  } catch {
-    // not YAML either
-  }
-  return undefined;
-}
-
-/** True if a parsed object is a CloudFormation template. */
-function looksLikeCloudFormation(obj: Record<string, unknown>): boolean {
-  if (obj.AWSTemplateFormatVersion !== undefined) return true;
-  const resources = obj.Resources;
-  if (resources && typeof resources === "object") {
-    for (const r of Object.values(resources as Record<string, unknown>)) {
-      const type = r && typeof r === "object" ? (r as Record<string, unknown>).Type : undefined;
-      if (typeof type === "string" && type.startsWith("AWS::")) return true;
-    }
-  }
-  return false;
-}
-
-/**
- * Discover CloudFormation templates (JSON or YAML, `.json`/`.yaml`/`.yml`/`.template`).
- * The aws checks `JSON.parse` the template, so YAML templates are normalized to a
- * JSON string here (intrinsics like `!Ref` survive as strings — fine for the
- * structural security checks).
- */
-export function discoverCloudFormation(root: string): AuditInput[] {
-  const files: string[] = [];
-  walkFiles(root, files);
-  const inputs: AuditInput[] = [];
-  for (const full of files) {
-    const name = basename(full);
-    if (!/\.(json|ya?ml|template)$/i.test(name)) continue;
-    const content = readSafe(full);
-    if (content === undefined) continue;
-    const parsed = parseStructured(content);
-    if (parsed && looksLikeCloudFormation(parsed)) {
-      inputs.push({ path: relative(root, full), content: JSON.stringify(parsed), lexicon: "aws" });
-    }
-  }
-  return inputs;
-}
-
-/** True if a parsed object is an Azure ARM deployment template. */
-function looksLikeArm(obj: Record<string, unknown>): boolean {
-  return typeof obj.$schema === "string" && obj.$schema.includes("deploymentTemplate") && Array.isArray(obj.resources);
-}
-
-/** Discover Azure ARM templates (`.json`) under a repo root. */
-export function discoverArm(root: string): AuditInput[] {
-  const files: string[] = [];
-  walkFiles(root, files);
-  const inputs: AuditInput[] = [];
-  for (const full of files) {
-    if (!/\.json$/i.test(basename(full))) continue;
-    const content = readSafe(full);
-    if (content === undefined) continue;
-    const parsed = parseStructured(content);
-    if (parsed && looksLikeArm(parsed)) {
-      inputs.push({ path: relative(root, full), content: JSON.stringify(parsed), lexicon: "azure" });
-    }
-  }
-  return inputs;
-}
-
-/**
- * Discover Helm charts. A chart (directory with Chart.yaml) is one bundle: the
- * helm checks read `output.files` keyed by chart-relative path, so all of the
- * chart's files are collected into a single AuditInput.files map.
- */
-export function discoverHelm(root: string): AuditInput[] {
-  const all: string[] = [];
-  walkFiles(root, all);
-  const chartDirs = all.filter((f) => basename(f) === "Chart.yaml").map((f) => f.slice(0, -("/Chart.yaml".length)));
-  const inputs: AuditInput[] = [];
-  for (const dir of chartDirs) {
-    const prefix = dir + "/";
-    const files: Record<string, string> = {};
-    for (const f of all) {
-      if (!f.startsWith(prefix)) continue;
-      const content = readSafe(f);
-      if (content !== undefined) files[f.slice(prefix.length)] = content;
-    }
-    if (files["Chart.yaml"] === undefined) continue;
-    const chartPath = relative(root, dir) || ".";
-    inputs.push({ path: chartPath, content: files["Chart.yaml"], lexicon: "helm", files });
-  }
-  return inputs;
-}
-
-/** Discover Docker artifacts: Dockerfiles (by name) and Compose files (by `services:`). */
-export function discoverDocker(root: string): AuditInput[] {
-  const files: string[] = [];
-  walkFiles(root, files);
-  const inputs: AuditInput[] = [];
-  for (const full of files) {
-    const name = basename(full);
-    const content = readSafe(full);
-    if (content === undefined) continue;
-    if (isDockerfileName(name) || (isYaml(name) && looksLikeCompose(content))) {
-      inputs.push({ path: relative(root, full), content, lexicon: "docker" });
-    }
-  }
-  return inputs;
-}
-
 function isMergeWorthy(f: AuditFinding): boolean {
   return RULE_CATALOG[f.checkId]?.tier === "merge-worthy";
 }
@@ -373,7 +123,7 @@ function renderStylish(findings: AuditFinding[], scanned: string[], notes: strin
   const mw = findings.filter(isMergeWorthy);
   const ro = findings.filter((f) => !isMergeWorthy(f));
   lines.push(
-    `Audited ${scanned.length} CI file${scanned.length === 1 ? "" : "s"} — ` +
+    `Audited ${scanned.length} file${scanned.length === 1 ? "" : "s"} — ` +
       `${findings.length} finding${findings.length === 1 ? "" : "s"} ` +
       `(${mw.length} merge-worthy, ${ro.length} report-only).`,
   );
@@ -456,12 +206,19 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
   const isUrl = /^https?:\/\//.test(options.path);
 
   let inputs: AuditInput[];
+  // Content-detected lexicons whose package isn't installed can't be detected
+  // (detection needs the plugin's `detectTemplate`), so a local audit would
+  // silently find nothing. Track the missing packages to turn that into a hint.
+  let missingHint = "";
   if (isUrl) {
     try {
-      inputs = await fetchCiFiles(options.path, {
+      // Fetch the whole repo's candidate files (all lexicons, not just CI) and
+      // run them through the same classifier the local path uses (#420).
+      const files = await fetchRepoFiles(options.path, {
         token: options.token ?? tokenForHost(options.path),
         fetchImpl: options.fetchImpl,
       });
+      inputs = classifyFiles(files, await loadAuditPlugins());
     } catch (err) {
       const msg = err instanceof FetchError ? err.message : err instanceof Error ? err.message : String(err);
       return { success: false, output: "", findings: [], scanned: [], exitCode: 1, error: msg };
@@ -470,26 +227,25 @@ export async function auditCommand(options: AuditCommandOptions): Promise<AuditC
     if (!existsSync(options.path)) {
       return { success: false, output: "", findings: [], scanned: [], exitCode: 1, error: `Path not found: ${options.path}` };
     }
-    // Helm claims whole chart directories; exclude chart-internal files from the
-    // other discoverers so raw templates aren't double-audited as loose manifests.
-    const helm = discoverHelm(options.path);
-    const chartPrefixes = helm.map((h) => (h.path === "." ? "" : `${h.path}/`));
-    const underChart = (p: string): boolean => chartPrefixes.some((pre) => (pre === "" ? true : p.startsWith(pre)));
-    const others = [
-      ...discoverCiFiles(options.path),
-      ...discoverManifests(options.path),
-      ...discoverDocker(options.path),
-      ...discoverCloudFormation(options.path),
-      ...discoverArm(options.path),
-      ...discoverGcp(options.path),
-    ].filter((i) => !underChart(i.path));
-    inputs = [...others, ...helm];
+    // One walk, plugin-delegated detection. Each lexicon plugin's own
+    // `detectTemplate` classifies the files it recognizes; CI (path), Dockerfiles
+    // (name), and Helm charts (bundle) are handled by discoverByDetection's
+    // special-cases since content shape alone can't disambiguate them.
+    const plugins = await loadAuditPlugins();
+    const loaded = new Set(plugins.map((p) => p.name));
+    const missing = AUDIT_LEXICONS.filter((n) => !loaded.has(n));
+    if (missing.length > 0) {
+      missingHint =
+        ` Some lexicon packages are not installed, so files of those types were not detected: ${missing.join(", ")}.` +
+        ` Install what you need, e.g. npm i ${missing.map((n) => `@intentius/chant-lexicon-${n}`).join(" ")}`;
+    }
+    inputs = discoverByDetection(options.path, plugins);
   }
 
   const scanned = inputs.map((i) => i.path);
 
   if (inputs.length === 0) {
-    return { success: true, output: `No CI files found under ${options.path}.`, findings: [], scanned: [], exitCode: 0 };
+    return { success: true, output: `No auditable files found under ${options.path}.${missingHint}`, findings: [], scanned: [], exitCode: 0 };
   }
 
   let findings: AuditFinding[];

package/src/codegen/bound-property-types.test.ts

@@ -0,0 +1,57 @@
+import { describe, test, expect } from "vitest";
+import { boundPropertyTypes, type BoundablePropertyType } from "./bound-property-types";
+
+interface Prop {
+  name: string;
+  tsType: string;
+}
+interface PT extends BoundablePropertyType {
+  name: string;
+  specType: string;
+  properties: Prop[];
+}
+
+function pt(name: string, props: Array<[string, string]>): PT {
+  return { name, specType: name.split("_")[1] ?? name, properties: props.map(([n, t]) => ({ name: n, tsType: t })) };
+}
+
+describe("boundPropertyTypes", () => {
+  test("drops property types unreachable from resource props", () => {
+    const props: Prop[] = [{ name: "sku", tsType: "R_Sku" }];
+    const types = [pt("R_Sku", [["name", "string"]]), pt("R_Unused", [["x", "string"]])];
+    const kept = boundPropertyTypes("R", props, types, new Set(), { maxDepth: 2 });
+    expect(kept.map((t) => t.name)).toEqual(["R_Sku"]);
+  });
+
+  test("caps nesting depth and loosens references beyond the cap", () => {
+    const props: Prop[] = [{ name: "a", tsType: "R_A" }];
+    const types = [
+      pt("R_A", [["b", "R_B"]]),
+      pt("R_B", [["c", "R_C"]]),
+      pt("R_C", [["d", "string"]]),
+    ];
+    const kept = boundPropertyTypes("R", props, types, new Set(), { maxDepth: 1 });
+    // depth 1: R_A kept, its child R_B not expanded -> loosened, R_C dropped
+    expect(kept.map((t) => t.name)).toEqual(["R_A"]);
+    expect(kept[0].properties[0].tsType).toBe("Record<string, unknown>");
+    expect(props[0].tsType).toBe("R_A"); // resource prop ref to a kept type is preserved
+  });
+
+  test("force-keeps curated property types by substring regardless of reachability", () => {
+    const props: Prop[] = [];
+    const types = [pt("R_SecurityRulePropertiesFormat", [["x", "string"]]), pt("R_Other", [["y", "string"]])];
+    const kept = boundPropertyTypes("R", props, types, new Set(), {
+      maxDepth: 1,
+      curatedDefs: ["SecurityRule"],
+    });
+    expect(kept.map((t) => t.name)).toEqual(["R_SecurityRulePropertiesFormat"]);
+  });
+
+  test("preserves enum references when loosening", () => {
+    const props: Prop[] = [{ name: "a", tsType: "R_A" }];
+    const types = [pt("R_A", [["mode", "R_ModeEnum"], ["nested", "R_Deep"]]), pt("R_Deep", [["x", "string"]])];
+    const kept = boundPropertyTypes("R", props, types, new Set(["R_ModeEnum"]), { maxDepth: 1 });
+    expect(kept[0].properties[0].tsType).toBe("R_ModeEnum"); // enum kept
+    expect(kept[0].properties[1].tsType).toBe("Record<string, unknown>"); // deep type loosened
+  });
+});

package/src/codegen/bound-property-types.ts

@@ -0,0 +1,110 @@
+/**
+ * Bound the set of generated property-type interfaces a lexicon emits.
+ *
+ * Cloud provider schemas (ARM, CloudFormation, …) embed a named definition for
+ * every nested object. Fully expanding all of them per-resource produces huge
+ * `.d.ts` declarations (azure was ~273MB — see #438). This helper keeps only
+ * the property types reachable from a resource's top-level properties within a
+ * depth bound, plus a curated force-keep set; references that fall outside the
+ * kept set are rewritten to `Record<string, unknown>`. Enum references are
+ * preserved. The input property refs are mutated in place. (#438, #440)
+ */
+
+/** A reference carrying a TypeScript type string, mutated in place when loosened. */
+export interface BoundablePropertyRef {
+  tsType: string;
+}
+
+/** A generated property type (named interface) and its properties. */
+export interface BoundablePropertyType {
+  name: string;
+  specType: string;
+  properties: BoundablePropertyRef[];
+}
+
+export interface BoundPropertyTypeOptions {
+  /** Maximum nesting depth of emitted property-type interfaces. */
+  maxDepth: number;
+  /**
+   * Definition-name substrings to always keep regardless of reachability/depth
+   * (e.g. common nested shapes worth typing for authoring ergonomics). Matched
+   * by substring against each property type's `specType`.
+   */
+  curatedDefs?: Iterable<string>;
+}
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/** Extract `${shortName}_Ident` type-reference tokens from a tsType string. */
+function referencedTypeNames(tsType: string, shortName: string): string[] {
+  const re = new RegExp("\\b" + escapeRegExp(shortName) + "_[A-Za-z0-9_]+", "g");
+  return tsType.match(re) ?? [];
+}
+
+/**
+ * Filter `propertyTypes` to the bounded set and loosen out-of-set references.
+ * Mutates the `tsType` of `resourceProps` and retained property types; returns
+ * the retained property types.
+ */
+export function boundPropertyTypes<PT extends BoundablePropertyType>(
+  shortName: string,
+  resourceProps: BoundablePropertyRef[],
+  propertyTypes: PT[],
+  enumNames: Set<string>,
+  options: BoundPropertyTypeOptions,
+): PT[] {
+  const { maxDepth } = options;
+  const curated = options.curatedDefs ? [...options.curatedDefs] : [];
+  const byName = new Map(propertyTypes.map((pt) => [pt.name, pt] as const));
+  const reached = new Set<string>();
+  const queue: Array<{ name: string; depth: number }> = [];
+
+  const seed = (tsType: string, depth: number) => {
+    for (const n of referencedTypeNames(tsType, shortName)) {
+      if (byName.has(n) && !reached.has(n)) {
+        reached.add(n);
+        queue.push({ name: n, depth });
+      }
+    }
+  };
+
+  for (const p of resourceProps) seed(p.tsType, 1);
+  // Force-keep curated property types (depth-1 seeds), matched by substring so
+  // schema variant names (e.g. "SecurityRulePropertiesFormat") are retained.
+  if (curated.length > 0) {
+    for (const pt of propertyTypes) {
+      if (!reached.has(pt.name) && curated.some((c) => pt.specType.includes(c))) {
+        reached.add(pt.name);
+        queue.push({ name: pt.name, depth: 1 });
+      }
+    }
+  }
+  while (queue.length) {
+    const { name, depth } = queue.shift()!;
+    if (depth >= maxDepth) continue; // do not expand children beyond the cap
+    const pt = byName.get(name);
+    if (!pt) continue;
+    for (const p of pt.properties) seed(p.tsType, depth + 1);
+  }
+
+  // Rewrite references to property types we are not emitting (keep enums).
+  const loosen = (tsType: string): string => {
+    let out = tsType;
+    for (const n of referencedTypeNames(tsType, shortName)) {
+      if (reached.has(n) || enumNames.has(n) || !byName.has(n)) continue;
+      out = out.replace(new RegExp("\\b" + escapeRegExp(n) + "\\b", "g"), "Record<string, unknown>");
+    }
+    return out;
+  };
+
+  for (const p of resourceProps) p.tsType = loosen(p.tsType);
+  const retained: PT[] = [];
+  for (const pt of propertyTypes) {
+    if (!reached.has(pt.name)) continue;
+    for (const p of pt.properties) p.tsType = loosen(p.tsType);
+    retained.push(pt);
+  }
+  return retained;
+}