@intentius/chant 0.97.0 → 0.99.0

package/src/import/embedded.ts

@@ -0,0 +1,376 @@
+/**
+ * Content embedded in another lexicon's resources, imported by the lexicon
+ * that owns it (#2962).
+ *
+ * A Kubernetes ConfigMap holding a collector's `config.yaml`, a
+ * `PrometheusRule` whose `spec.groups` are Prometheus rule groups, and a
+ * ConfigMap holding Grafana dashboard JSON all carry another lexicon's
+ * source inside a k8s resource. The host lexicon's parser (k8s) finds such
+ * content and offers it here; the lexicon that can import it (otel,
+ * prometheus, grafana) declares so with `LexiconPlugin.embeddedImporters()`.
+ * Core matches the two at run time, so the host needs no dependency on the
+ * owner: when the owner is not installed the content stays as written, with
+ * a warning.
+ *
+ * The flow, driven by `chant import`:
+ *
+ * 1. The host's `TemplateParser.parse(content, context)` calls
+ *    `context.embedded.resolve(site)` for each place content can be
+ *    embedded, and puts the `EmbeddedReference` it gets back into its IR in
+ *    place of the raw value. `undefined` means keep the raw value.
+ * 2. The owner's `EmbeddedContentImporter.import(site)` returns the modules
+ *    declaring the content and how the host's value is built from them
+ *    (`collectorYaml([...])`, a list of rule groups, `dashboardJson(...)`).
+ * 3. Core writes those modules in a directory of their own beside the
+ *    host's files, and the host's generator renders the reference with
+ *    `renderEmbeddedReference`, which also writes the imports it needs.
+ */
+
+import { posix } from "path";
+import { parseYAMLDocument, splitYAMLDocuments } from "../yaml";
+import type { GeneratedFile } from "./generator";
+
+// ── what the host offers ─────────────────────────────────────────────
+
+/** One place in a host resource that may hold another lexicon's content. */
+export interface EmbeddedContent {
+  /** The host lexicon, e.g. `"k8s"`. */
+  readonly host: string;
+  /** The host resource's type, e.g. `"K8s::Core::ConfigMap"`. */
+  readonly hostType: string;
+  /** Where it is, for messages: `ConfigMap otel-agent data["config.yaml"]`. */
+  readonly location: string;
+  /** A name for the directory its modules are written to; core makes it unique. */
+  readonly directory: string;
+  /** The content as text, when the host holds it as text (a ConfigMap value). */
+  readonly text?: string;
+  /**
+   * The content as the document it would be in a file of its own. Core
+   * parses `text` into it (JSON, then YAML) when the host leaves it out.
+   * `PrometheusRule` `spec.groups` is offered as `{ groups: [...] }`, the rule
+   * file those groups would make.
+   */
+  readonly document?: unknown;
+  /**
+   * When the host's value is one member of `document` rather than the whole
+   * of it: `"groups"` for `spec.groups`. The reference must then evaluate to
+   * `document[select]`. Absent, it evaluates to `text`.
+   */
+  readonly select?: string;
+  /** The host resource's labels, where the host has them. */
+  readonly labels?: Readonly<Record<string, string>>;
+  /**
+   * The lexicon the host expects to own this content, from conventions it
+   * knows (a PrometheusRule's groups are Prometheus rules). Only used for the
+   * warning when no installed lexicon imports the content.
+   */
+  readonly expectedOwner?: { readonly lexicon: string; readonly what: string };
+}
+
+/** A declaration the host's value is built from. */
+export interface EmbeddedBinding {
+  /** A package (`@intentius/chant-lexicon-otel`) or the path of one of the import's `files`. */
+  readonly from: string;
+  /** The exported name. */
+  readonly name: string;
+  /** A member of it the value uses instead, e.g. an `Slo`'s `rules`. */
+  readonly member?: string;
+}
+
+/** How the host's value is built from the imported declarations. */
+export interface EmbeddedValue {
+  /** The declarations, in order. */
+  readonly bindings: readonly EmbeddedBinding[];
+  /** `"list"`: an array of them. `"single"`: the one binding. */
+  readonly shape: "list" | "single";
+  /** A function the value is passed through, e.g. otel's `collectorYaml`. */
+  readonly through?: { readonly from: string; readonly name: string };
+}
+
+/** What an owner's importer returns for one piece of content. */
+export interface EmbeddedImport {
+  /** The modules declaring the content, at paths relative to their own directory. */
+  readonly files: readonly GeneratedFile[];
+  readonly value: EmbeddedValue;
+  /** What the import read but could not carry. */
+  readonly warnings?: readonly string[];
+}
+
+/** An owner lexicon's declaration that it can import content embedded in another's resources. */
+export interface EmbeddedContentImporter {
+  /** What it imports, for messages: `"an OpenTelemetry Collector config"`. */
+  readonly what: string;
+  /** Whether this content is one it imports. Must not throw on content that is not. */
+  matches(content: EmbeddedContent): boolean;
+  /** Import it. A throw keeps the content as written, with a warning. */
+  import(content: EmbeddedContent): EmbeddedImport;
+}
+
+/** An importer with the lexicon that registered it. */
+export interface RegisteredEmbeddedImporter {
+  readonly lexicon: string;
+  readonly importer: EmbeddedContentImporter;
+}
+
+// ── what the host gets back ──────────────────────────────────────────
+
+/**
+ * What the host puts in its IR in place of the raw value. Plain data: the
+ * bindings' local paths are relative to the import's output directory.
+ */
+export interface EmbeddedReference {
+  readonly $embedded: {
+    readonly lexicon: string;
+    readonly what: string;
+    readonly location: string;
+    readonly value: EmbeddedValue;
+  };
+}
+
+export function isEmbeddedReference(value: unknown): value is EmbeddedReference {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const e = (value as { $embedded?: unknown }).$embedded;
+  return (
+    typeof e === "object" &&
+    e !== null &&
+    Array.isArray((e as { value?: { bindings?: unknown } }).value?.bindings)
+  );
+}
+
+/** What a host's parser is handed to resolve embedded content. */
+export interface EmbeddedContentResolver {
+  /** The reference to put in place of the content, or undefined to keep it as written. */
+  resolve(content: EmbeddedContent): EmbeddedReference | undefined;
+}
+
+// ── the registry ─────────────────────────────────────────────────────
+
+function isObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** The document a text holds: JSON, or a single YAML document. Undefined for anything else. */
+export function embeddedDocument(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    // Not JSON: try YAML.
+  }
+  const docs = splitYAMLDocuments(text);
+  if (docs.length !== 1) return undefined;
+  let doc: unknown;
+  try {
+    doc = parseYAMLDocument(docs[0]);
+  } catch {
+    return undefined;
+  }
+  // Text that is not YAML (`just text`, `KEY=value` lines) makes core's YAML
+  // reader throw, caught above (#2991); an empty or comment-only text reads
+  // as an empty mapping. Neither is a document.
+  if (typeof doc === "object" && doc !== null && Object.keys(doc).length === 0) return undefined;
+  return doc;
+}
+
+/** A directory name: lower-case letters, digits and `-`. */
+function slug(text: string): string {
+  const s = text
+    .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return s === "" ? "embedded" : s;
+}
+
+/**
+ * Resolves embedded content against the importers registered for one
+ * import, and collects what the imports produce: the files to write beside
+ * the host's and the warnings to print. `offered` lists every piece of
+ * content the host offered, claimed or not.
+ */
+export class EmbeddedImports implements EmbeddedContentResolver {
+  readonly offered: EmbeddedContent[] = [];
+  readonly files: GeneratedFile[] = [];
+  readonly warnings: string[] = [];
+  private readonly directories = new Set<string>();
+
+  /**
+   * @param importers what the installed lexicons registered, in the order they are asked
+   * @param options.quiet collect `offered` only, with no warnings (a probe before the importers are known)
+   */
+  constructor(
+    private readonly importers: readonly RegisteredEmbeddedImporter[] = [],
+    private readonly options: { quiet?: boolean } = {},
+  ) {}
+
+  resolve(offered: EmbeddedContent): EmbeddedReference | undefined {
+    const content: EmbeddedContent =
+      offered.document === undefined && typeof offered.text === "string"
+        ? { ...offered, document: embeddedDocument(offered.text) }
+        : offered;
+    this.offered.push(content);
+
+    const matching = this.importers.filter(({ importer }) => {
+      try {
+        return importer.matches(content);
+      } catch {
+        return false;
+      }
+    });
+    const [chosen, ...others] = matching;
+    if (!chosen) {
+      const owner = content.expectedOwner;
+      if (owner && !this.options.quiet) {
+        this.warnings.push(
+          `${content.location} looks like ${owner.what}, and no installed lexicon imports it, so it is kept as written. ` +
+            `Install @intentius/chant-lexicon-${owner.lexicon} (or a version that imports embedded content) to import it as typed declarations.`,
+        );
+      }
+      return undefined;
+    }
+    if (others.length > 0) {
+      this.warnings.push(
+        `${content.location} is also importable by ${others.map((o) => o.lexicon).join(", ")}; imported with ${chosen.lexicon}.`,
+      );
+    }
+
+    let result: EmbeddedImport;
+    try {
+      result = chosen.importer.import(content);
+    } catch (err) {
+      this.warnings.push(
+        `${content.location} looks like ${chosen.importer.what}, but the ${chosen.lexicon} import failed, so it is kept as written: ` +
+          (err instanceof Error ? err.message : String(err)),
+      );
+      return undefined;
+    }
+
+    const dir = this.claimDirectory(content.directory);
+    const local = new Set(result.files.map((f) => f.path));
+    const rebase = (from: string) => (local.has(from) ? `${dir}/${from}` : from);
+    for (const f of result.files) this.files.push({ path: `${dir}/${f.path}`, content: f.content });
+    for (const w of result.warnings ?? []) this.warnings.push(`${content.location}: ${w}`);
+
+    const v = result.value;
+    const value: EmbeddedValue = {
+      bindings: v.bindings.map((b) => ({ ...b, from: rebase(b.from) })),
+      shape: v.shape,
+      ...(v.through ? { through: { ...v.through, from: rebase(v.through.from) } } : {}),
+    };
+    return {
+      $embedded: { lexicon: chosen.lexicon, what: chosen.importer.what, location: content.location, value },
+    };
+  }
+
+  private claimDirectory(name: string): string {
+    const base = slug(name);
+    let dir = base;
+    for (let n = 2; this.directories.has(dir); n++) dir = `${base}-${n}`;
+    this.directories.add(dir);
+    return dir;
+  }
+}
+
+// ── rendering ────────────────────────────────────────────────────────
+
+const RESERVED = new Set(
+  (
+    "break case catch class const continue debugger default delete do else enum export extends false finally for " +
+    "function if import in instanceof new null return super switch this throw true try typeof var void while with " +
+    "yield let static implements interface package private protected public await arguments eval undefined"
+  ).split(" "),
+);
+
+/**
+ * The imports one generated module needs for the references it renders.
+ * Names are made unique against the module's own declarations: a second
+ * `otlp` from another collector's directory is imported as `otlp2`.
+ */
+export class EmbeddedImportScope {
+  private readonly taken: Set<string>;
+  /** specifier -> exported name -> local name */
+  private readonly bySpecifier = new Map<string, Map<string, string>>();
+
+  /**
+   * @param fromDir the directory of the module being generated, relative to the output directory (`""` for its top)
+   * @param taken names the module already declares or imports
+   */
+  constructor(
+    private readonly fromDir: string,
+    taken: Iterable<string> = [],
+  ) {
+    this.taken = new Set(taken);
+  }
+
+  /** The local name `name`, exported by `from` (a package or an output-relative path), is used under. */
+  bind(from: string, name: string): string {
+    const spec = this.specifier(from);
+    let names = this.bySpecifier.get(spec);
+    if (!names) {
+      names = new Map();
+      this.bySpecifier.set(spec, names);
+    }
+    const existing = names.get(name);
+    if (existing) return existing;
+    let local = name;
+    for (let n = 2; this.taken.has(local) || RESERVED.has(local); n++) local = `${name}${n}`;
+    this.taken.add(local);
+    names.set(name, local);
+    return local;
+  }
+
+  /** The import statements, packages first, then local modules, each sorted. */
+  lines(): string[] {
+    const specs = [...this.bySpecifier.keys()].sort((a, b) => {
+      const la = a.startsWith("."), lb = b.startsWith(".");
+      return la === lb ? a.localeCompare(b) : la ? 1 : -1;
+    });
+    return specs.map((spec) => {
+      const entries = [...this.bySpecifier.get(spec)!].sort(([a], [b]) => a.localeCompare(b));
+      const list = entries.map(([name, local]) => (name === local ? name : `${name} as ${local}`));
+      const one = `import { ${list.join(", ")} } from "${spec}";`;
+      return one.length <= 100 ? one : `import {\n${list.map((n) => `  ${n},`).join("\n")}\n} from "${spec}";`;
+    });
+  }
+
+  private specifier(from: string): string {
+    if (!from.endsWith(".ts")) return from;
+    let rel = posix.relative(this.fromDir || ".", from.replace(/\.ts$/, ""));
+    if (!rel.startsWith(".")) rel = `./${rel}`;
+    return rel;
+  }
+}
+
+/**
+ * The TypeScript expression for a reference, binding its names in `scope`.
+ * A list longer than one line is broken one binding per line, indented from
+ * `indent` spaces.
+ */
+export function renderEmbeddedReference(ref: EmbeddedReference, scope: EmbeddedImportScope, indent = 0): string {
+  const { value } = ref.$embedded;
+  const items = value.bindings.map((b) => `${scope.bind(b.from, b.name)}${b.member ? `.${b.member}` : ""}`);
+  let inner: string;
+  if (value.shape === "single") {
+    if (items.length !== 1) throw new Error(`${ref.$embedded.location}: a single embedded value needs exactly one binding`);
+    inner = items[0];
+  } else {
+    const one = `[${items.join(", ")}]`;
+    const pad = " ".repeat(indent);
+    inner = one.length <= 80 ? one : `[\n${items.map((i) => `${pad}  ${i},`).join("\n")}\n${pad}]`;
+  }
+  return value.through ? `${scope.bind(value.through.from, value.through.name)}(${inner})` : inner;
+}
+
+/**
+ * The names a generated module exports in its `export { … }` list, for an
+ * importer whose generator writes one per module (COR004).
+ */
+export function exportedNames(content: string): string[] {
+  const names: string[] = [];
+  for (const m of content.matchAll(/^export\s*\{([^}]*)\};?\s*$/gm)) {
+    for (const part of m[1].split(",")) {
+      const name = part.trim().split(/\s+as\s+/).pop()!.trim();
+      if (name !== "" && !name.startsWith("type ")) names.push(name);
+    }
+  }
+  return names;
+}

package/src/import/generator.ts

@@ -18,4 +18,18 @@ export interface TypeScriptGenerator {
    * @returns Array of generated TypeScript files
    */
   generate(ir: TemplateIR): GeneratedFile[];
+
+  /**
+   * True when the generator places its own files (#2964). Core then calls
+   * `generate()` once with the whole IR and writes exactly the files it
+   * returns, at the paths it gives, however many resources the IR holds.
+   *
+   * Leave it unset for core's default layout: up to three resources are
+   * generated in one call, and above three core splits the IR into
+   * per-category files (`storage.ts`, `compute.ts`, `network.ts`,
+   * `other.ts`) plus an `index.ts` barrel, keeping only the first file of
+   * each call. Set it when your resources refer to each other across that
+   * split, or when one `generate()` call returns several modules.
+   */
+  readonly ownsLayout?: boolean;
 }

package/src/import/parser.ts

@@ -1,3 +1,5 @@
+import type { EmbeddedContentResolver } from "./embedded";
+
 /**
  * Intermediate representation of a template parameter
  */
@@ -63,6 +65,19 @@ export interface TemplateIR {
   readonly warnings?: string[];
 }
 
+/**
+ * What `chant import` hands a parser besides the content (#2962).
+ */
+export interface ParseContext {
+  /**
+   * Resolves content embedded in the template's resources (a collector
+   * config in a ConfigMap) to a reference to declarations the owning
+   * lexicon imports. Absent outside `chant import`; a parser then keeps
+   * embedded content as written.
+   */
+  readonly embedded?: EmbeddedContentResolver;
+}
+
 /**
  * Interface for template parsers that convert external formats to IR
  */
@@ -70,7 +85,8 @@ export interface TemplateParser {
   /**
    * Parse template content into intermediate representation
    * @param content - Raw template content (JSON, YAML, etc.)
+   * @param context - What `chant import` provides beyond the content; parsers may ignore it
    * @returns Intermediate representation of the template
    */
-  parse(content: string): TemplateIR;
+  parse(content: string, context?: ParseContext): TemplateIR;
 }

package/src/lexicon.ts

@@ -5,6 +5,7 @@ import type { RuleSpec } from "./lint/declarative";
 import type { PostSynthCheck } from "./lint/post-synth";
 import type { TemplateParser, TemplateIR } from "./import/parser";
 import type { TypeScriptGenerator } from "./import/generator";
+import type { EmbeddedContentImporter } from "./import/embedded";
 import type { AgentConfigImporter } from "./agents/importer";
 import type { ArtifactIntegrity } from "./lexicon-integrity";
 import type { OkfFile } from "./okf";
@@ -1047,6 +1048,15 @@ export interface LexiconPlugin {
   /** Return declarative rule specs for compilation via rule() */
   declarativeRules?(): RuleSpec[];
 
+  /**
+   * Class names this lexicon exports whose instances are property-kind
+   * declarables (`createProperty`), such as Grafana's panels and queries.
+   * The core COR001, COR004 and COR009 heuristics leave them out, since a
+   * property-kind declarable lives inside the resource that holds it
+   * (chant #2957). A lexicon that leaves this out gets the rules unchanged.
+   */
+  propertyClassNames?(): string[];
+
   /** Return post-synthesis checks for build validation */
   postSynthChecks?(): PostSynthCheck[];
 
@@ -1156,6 +1166,17 @@ export interface LexiconPlugin {
   /** Return a generator for converting IR to TypeScript */
   templateGenerator?(): TypeScriptGenerator;
 
+  /**
+   * Importers for this lexicon's content when it is embedded in another
+   * lexicon's resources (#2962): a collector config in a k8s ConfigMap, rule
+   * groups in a `PrometheusRule`, dashboard JSON in a ConfigMap. The host's
+   * parser offers the content through `ParseContext.embedded`, and core finds
+   * the owner at run time among the project's lexicons and the installed
+   * ones whose `detectTemplate` recognizes the content, so the host does not
+   * depend on the owner. See `packages/core/src/import/embedded.ts`.
+   */
+  embeddedImporters?(): EmbeddedContentImporter[];
+
   /**
    * Re-express local agent configuration (skills, MCP servers, instruction
    * files) discovered by `chant audit --agents` as this lexicon's resources.

package/src/lint/engine.ts

@@ -207,6 +207,11 @@ function isDiagnosticDisabled(
  *   config-aware rules (COR021 reads `environments` + `ownership`), put on
  *   every file's `LintContext.projectConfig`. Optional; without it those
  *   rules stay silent.
+ * @param propertyClasses - chant #2957 — the class names the active
+ *   lexicons declare property-kind (`LexiconPlugin.propertyClassNames()`),
+ *   put on every file's `LintContext.propertyClasses` so COR001, COR004 and
+ *   COR009 leave those declarables out. Optional; without it every
+ *   declarable counts.
  * @returns LintRunResult with diagnostics and suppressed items
  */
 export async function runLint(
@@ -215,6 +220,7 @@ export async function runLint(
   ruleOptions?: Map<string, Record<string, unknown>>,
   intrinsics?: readonly IntrinsicDef[],
   projectConfig?: LintProjectConfig,
+  propertyClasses?: ReadonlySet<string>,
 ): Promise<LintRunResult> {
   const allDiagnostics: LintDiagnostic[] = [];
   const allSuppressed: Array<LintDiagnostic & { reason?: string }> = [];
@@ -237,6 +243,7 @@ export async function runLint(
         lexicon: undefined,
         intrinsics,
         projectConfig,
+        propertyClasses,
       };
 
       // Execute each rule

package/src/lint/rule.ts

@@ -97,6 +97,16 @@ export interface LintContext {
    * case config-aware rules stay silent.
    */
   projectConfig?: LintProjectConfig;
+  /**
+   * chant #2957 — class names the active lexicons declare property-kind
+   * (`LexiconPlugin.propertyClassNames()`), such as Grafana's panels,
+   * queries and variables. COR001, COR004 and COR009 leave these out: a
+   * property-kind declarable lives inside the resource that holds it, so it
+   * is neither a resource to count nor dead code on its own. Undefined when
+   * no active lexicon names any, and those rules then treat every
+   * declarable alike.
+   */
+  propertyClasses?: ReadonlySet<string>;
 }
 
 /**

package/src/lint/rules/file-declarable-limit.ts

@@ -1,5 +1,6 @@
 import * as ts from "typescript";
 import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+import { isPropertyKindNew } from "./property-kind";
 
 const DECLARABLE_LIMIT = 8;
 
@@ -57,15 +58,21 @@ function isDeclarableConstructor(node: ts.NewExpression): boolean {
   return false;
 }
 
+/**
+ * Collect the declarable `new` expressions this rule counts. Property-kind
+ * declarables (chant #2957) are left out: a dashboard with twenty panels,
+ * queries and variables is one resource, not twenty-one.
+ */
 function collectDeclarableNewExpressions(
   node: ts.Node,
+  context: LintContext,
   results: ts.NewExpression[],
 ): void {
-  if (ts.isNewExpression(node) && isDeclarableConstructor(node)) {
+  if (ts.isNewExpression(node) && isDeclarableConstructor(node) && !isPropertyKindNew(node, context)) {
     results.push(node);
   }
   ts.forEachChild(node, (child) =>
-    collectDeclarableNewExpressions(child, results),
+    collectDeclarableNewExpressions(child, context, results),
   );
 }
 
@@ -73,11 +80,11 @@ export const fileDeclarableLimitRule: LintRule = {
   id: "COR009",
   severity: "warning",
   category: "style",
-  description: "Limits the number of Declarable instances per file to encourage splitting by concern",
+  description: "Limits the number of resource Declarable instances per file to encourage splitting by concern; property-kind declarables are not counted",
   check(context: LintContext, options?: Record<string, unknown>): LintDiagnostic[] {
     const limit = (typeof options?.max === "number" ? options.max : null) ?? DECLARABLE_LIMIT;
     const instances: ts.NewExpression[] = [];
-    collectDeclarableNewExpressions(context.sourceFile, instances);
+    collectDeclarableNewExpressions(context.sourceFile, context, instances);
 
     if (instances.length > limit) {
       return [

package/src/lint/rules/flat-declarations.ts

@@ -1,5 +1,6 @@
 import * as ts from "typescript";
 import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+import { isPropertyKindNew } from "./property-kind";
 
 /**
  * COR001: No inline objects in Declarable constructors
@@ -12,11 +13,15 @@ import type { LintRule, LintContext, LintDiagnostic } from "../rule";
  * Triggers on: new Bucket({ tags: [{ key: "env", value: "prod" }] })
  * OK: new Bucket({ bucketName: "my-bucket", accessControl: "Private" })
  * OK: new Bucket({ encryption: dataEncryption })
+ * OK: new TimeSeriesPanel({ fieldConfig: { defaults: { unit: "ms" } } }) when
+ *     the lexicon declares TimeSeriesPanel property-kind (chant #2957). A
+ *     property-kind declarable is itself a nested value inside a resource, so
+ *     the object literals it holds are already at the depth this rule asks for.
  */
 
 function checkNode(node: ts.Node, context: LintContext, diagnostics: LintDiagnostic[]): void {
   // Check for NewExpression nodes (constructor calls)
-  if (ts.isNewExpression(node)) {
+  if (ts.isNewExpression(node) && !isPropertyKindNew(node, context)) {
     // Check if the first argument is an object literal
     if (node.arguments && node.arguments.length > 0) {
       const firstArg = node.arguments[0];

package/src/lint/rules/no-unused-declarable.ts

@@ -1,5 +1,6 @@
 import * as ts from "typescript";
 import type { LintRule, LintContext, LintDiagnostic } from "../rule";
+import { isPropertyKindNew } from "./property-kind";
 
 /**
  * COR004: no-unused-declarable
@@ -10,6 +11,13 @@ import type { LintRule, LintContext, LintDiagnostic } from "../rule";
  *
  * Triggers on: export const bucket = new Bucket({...}) when bucket is never referenced
  * OK: export const bucket = new Bucket({...}); export const fn = new Function({ bucket: bucket.arn })
+ *
+ * Property-kind declarables (chant #2957), such as Grafana panels, are left
+ * out on both sides. One is never flagged itself: it only means something
+ * inside a resource, and a file of them is usually assembled into that
+ * resource from another file. A resource that holds one, inline or through
+ * a const declared in this file, is the root that emits it, so it is not
+ * flagged either: nothing ever references a dashboard, and that is fine.
  */
 
 interface DeclarableInfo {
@@ -31,8 +39,52 @@ function getNewExpressionClassName(expr: ts.NewExpression): string | undefined {
   return undefined;
 }
 
-function collectExportedDeclarables(sourceFile: ts.SourceFile): DeclarableInfo[] {
+/** Names of this file's top-level consts initialised with a property-kind `new`. */
+function collectPropertyKindConsts(context: LintContext): Set<string> {
+  const names = new Set<string>();
+  for (const stmt of context.sourceFile.statements) {
+    if (!ts.isVariableStatement(stmt)) continue;
+    for (const decl of stmt.declarationList.declarations) {
+      if (
+        ts.isIdentifier(decl.name) &&
+        decl.initializer &&
+        ts.isNewExpression(decl.initializer) &&
+        isPropertyKindNew(decl.initializer, context)
+      ) {
+        names.add(decl.name.text);
+      }
+    }
+  }
+  return names;
+}
+
+/**
+ * True when the constructor arguments hold a property-kind declarable,
+ * either inline (`panels: [new Row(…)]`) or through a const from
+ * `propertyConsts` (`panels: [red]`).
+ */
+function holdsPropertyKind(expr: ts.NewExpression, context: LintContext, propertyConsts: Set<string>): boolean {
+  let found = false;
+  function visit(node: ts.Node): void {
+    if (found) return;
+    if (ts.isNewExpression(node) && isPropertyKindNew(node, context)) {
+      found = true;
+      return;
+    }
+    if (ts.isIdentifier(node) && propertyConsts.has(node.text)) {
+      found = true;
+      return;
+    }
+    ts.forEachChild(node, visit);
+  }
+  for (const arg of expr.arguments ?? []) visit(arg);
+  return found;
+}
+
+function collectExportedDeclarables(context: LintContext): DeclarableInfo[] {
   const declarables: DeclarableInfo[] = [];
+  const sourceFile = context.sourceFile;
+  const propertyConsts = collectPropertyKindConsts(context);
 
   ts.forEachChild(sourceFile, (node) => {
     if (!ts.isVariableStatement(node)) return;
@@ -54,6 +106,11 @@ function collectExportedDeclarables(sourceFile: ts.SourceFile): DeclarableInfo[]
       // Parameters are inherently cross-file (declared in params.ts, consumed via Ref() elsewhere)
       if (className === "Parameter") continue;
 
+      // chant #2957: a property-kind declarable is part of a resource, and a
+      // resource holding one is the root that emits it.
+      if (isPropertyKindNew(decl.initializer, context)) continue;
+      if (holdsPropertyKind(decl.initializer, context, propertyConsts)) continue;
+
       declarables.push({
         name: decl.name.text,
         node,
@@ -98,7 +155,7 @@ export const noUnusedDeclarableRule: LintRule = {
   description: "Detects exported declarables that are never referenced in the same file",
   check(context: LintContext): LintDiagnostic[] {
     const diagnostics: LintDiagnostic[] = [];
-    const declarables = collectExportedDeclarables(context.sourceFile);
+    const declarables = collectExportedDeclarables(context);
 
     for (const decl of declarables) {
       if (!collectReferences(decl.name, context.sourceFile, decl.node)) {