@intentius/chant 0.98.0 → 0.99.0

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)) {

package/src/lint/rules/property-kind.test.ts

@@ -0,0 +1,99 @@
+import { describe, test, expect } from "vitest";
+import * as ts from "typescript";
+import { flatDeclarationsRule } from "./flat-declarations";
+import { noUnusedDeclarableRule } from "./no-unused-declarable";
+import { fileDeclarableLimitRule } from "./file-declarable-limit";
+import type { LintContext } from "../rule";
+
+// chant #2957: a dashboard-shaped file whose panels, rows, queries and
+// variables are property-kind declarables, as the grafana lexicon declares them.
+const PROPERTY = new Set(["Row", "StatPanel", "TimeSeriesPanel", "PromQuery", "QueryVariable"]);
+
+const DASHBOARD = `
+import { Dashboard, Row, TimeSeriesPanel as Series, StatPanel, PromQuery, QueryVariable } from "@intentius/chant-lexicon-grafana";
+
+export const service = new QueryVariable({ name: "service", query: "label_values(up, job)" });
+
+export const overview = new Dashboard({
+  title: "Overview",
+  variables: [service],
+  panels: [
+    new Row({ title: "RED", panels: [
+      new StatPanel({ title: "Errors", targets: [new PromQuery({ expr: "a" })], fieldConfig: { defaults: { unit: "percentunit" } }, options: { graphMode: "area" } }),
+      new Series({ title: "Rate", targets: [new PromQuery({ expr: "b" }), new PromQuery({ expr: "c" })], fieldConfig: { defaults: { unit: "reqps" } } }),
+      new Series({ title: "Latency", targets: [new PromQuery({ expr: "d" })], fieldConfig: { defaults: { unit: "ms" } } }),
+      new Series({ title: "Saturation", targets: [new PromQuery({ expr: "e" })] }),
+    ] }),
+  ],
+});
+`;
+
+function context(code: string, propertyClasses?: ReadonlySet<string>): LintContext {
+  return {
+    sourceFile: ts.createSourceFile("dashboard.ts", code, ts.ScriptTarget.Latest, true),
+    entities: [],
+    filePath: "dashboard.ts",
+    propertyClasses,
+  };
+}
+
+describe("property-kind declarables in COR001, COR004 and COR009 (chant #2957)", () => {
+  test("without property classes the rules count every declarable, as before", () => {
+    const ctx = context(DASHBOARD);
+    expect(fileDeclarableLimitRule.check(ctx)).toHaveLength(1);
+    expect(fileDeclarableLimitRule.check(ctx)[0].message).toContain("12 Declarable instances");
+    expect(flatDeclarationsRule.check(ctx)).toHaveLength(4);
+    expect(noUnusedDeclarableRule.check(ctx).map((d) => d.message)).toEqual([
+      expect.stringContaining("'overview'"),
+    ]);
+  });
+
+  test("with them, the dashboard file is clean", () => {
+    const ctx = context(DASHBOARD, PROPERTY);
+    expect(fileDeclarableLimitRule.check(ctx)).toEqual([]);
+    expect(flatDeclarationsRule.check(ctx)).toEqual([]);
+    expect(noUnusedDeclarableRule.check(ctx)).toEqual([]);
+  });
+
+  test("COR009 still counts resources, and only resources", () => {
+    const resources = Array.from({ length: 9 }, (_, i) => `export const d${i} = new Dashboard({ panels: [new Row({})] });`).join("\n");
+    const [diag] = fileDeclarableLimitRule.check(context(resources, PROPERTY));
+    expect(diag.message).toContain("9 Declarable instances");
+  });
+
+  test("COR001 still flags inline objects on a resource", () => {
+    const code = `export const d = new Dashboard({ time: { from: "now-1h", to: "now" }, panels: [new StatPanel({ options: { a: 1 } })] });`;
+    const diags = flatDeclarationsRule.check(context(code, PROPERTY));
+    expect(diags).toHaveLength(1);
+    expect(diags[0].column).toBe(code.indexOf("{ from") + 1);
+  });
+
+  test("COR004 skips an exported property-kind declarable used from another file", () => {
+    const code = `export const latency = new TimeSeriesPanel({ title: "Latency" });`;
+    expect(noUnusedDeclarableRule.check(context(code, PROPERTY))).toEqual([]);
+    expect(noUnusedDeclarableRule.check(context(code))).toHaveLength(1);
+  });
+
+  test("COR004 treats a resource holding a property-kind const as the root", () => {
+    const code = [
+      `const red = new Row({ title: "RED" });`,
+      `export const overview = new Dashboard({ panels: [red] });`,
+    ].join("\n");
+    expect(noUnusedDeclarableRule.check(context(code, PROPERTY))).toEqual([]);
+  });
+
+  test("COR004 still flags an unreferenced resource holding no property-kind declarable", () => {
+    const code = [
+      `export const logs = new Bucket({ bucketName: "logs" });`,
+      `export const overview = new Dashboard({ panels: [new Row({})] });`,
+    ].join("\n");
+    expect(noUnusedDeclarableRule.check(context(code, PROPERTY)).map((d) => d.message)).toEqual([
+      expect.stringContaining("'logs'"),
+    ]);
+  });
+
+  test("a namespace-qualified constructor resolves by its member name", () => {
+    const code = `export const d = new g.Dashboard({ panels: [new g.StatPanel({ options: { a: 1 } })] });`;
+    expect(flatDeclarationsRule.check(context(code, PROPERTY))).toEqual([]);
+  });
+});

package/src/lint/rules/property-kind.ts

@@ -0,0 +1,56 @@
+import * as ts from "typescript";
+import type { LintContext } from "../rule";
+
+/**
+ * Property-kind declarables for the COR001, COR004 and COR009 heuristics
+ * (chant #2957).
+ *
+ * Those three rules were written for cloud resources, where every `new X(…)`
+ * is something the build emits. A property-kind declarable (`createProperty`)
+ * is not: it only exists inside the resource that holds it, like a Grafana
+ * panel inside its dashboard. The active lexicons name their property-kind
+ * classes through `LexiconPlugin.propertyClassNames()`, and `runLint` puts
+ * them on `LintContext.propertyClasses`. Without that set (a unit test, or a
+ * lexicon that declares none) nothing is property-kind and the rules behave
+ * as they always have.
+ */
+
+/**
+ * Map each locally bound import name to the name it was exported under, so
+ * `import { TimeSeriesPanel as Series }` still resolves `new Series(…)`.
+ */
+function importAliases(sourceFile: ts.SourceFile): Map<string, string> {
+  const aliases = new Map<string, string>();
+  for (const stmt of sourceFile.statements) {
+    if (!ts.isImportDeclaration(stmt)) continue;
+    const bindings = stmt.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const el of bindings.elements) {
+      if (el.propertyName) aliases.set(el.name.text, el.propertyName.text);
+    }
+  }
+  return aliases;
+}
+
+const aliasCache = new WeakMap<ts.SourceFile, Map<string, string>>();
+
+/** The exported class name a `new` expression constructs, if it has one. */
+export function constructedClassName(node: ts.NewExpression, sourceFile: ts.SourceFile): string | undefined {
+  const expr = node.expression;
+  if (ts.isPropertyAccessExpression(expr)) return expr.name.text;
+  if (!ts.isIdentifier(expr)) return undefined;
+  let aliases = aliasCache.get(sourceFile);
+  if (!aliases) {
+    aliases = importAliases(sourceFile);
+    aliasCache.set(sourceFile, aliases);
+  }
+  return aliases.get(expr.text) ?? expr.text;
+}
+
+/** True when `node` constructs a class an active lexicon declares property-kind. */
+export function isPropertyKindNew(node: ts.NewExpression, context: LintContext): boolean {
+  const classes = context.propertyClasses;
+  if (!classes || classes.size === 0) return false;
+  const name = constructedClassName(node, context.sourceFile);
+  return name !== undefined && classes.has(name);
+}

package/src/workspace/conformance/index.mjs

@@ -25,6 +25,7 @@ export const {
   selectCommands,
   MCP_READ_TOOLS,
   mcpToolCall,
+  sameReadDocument,
   startMcpSession,
   createConformanceWorkspace,
   conformanceTarget,

package/src/workspace/conformance/index.ts

@@ -527,6 +527,28 @@ function runChant(command: string[], argv: string[], cwd: string, timeoutMs: num
   });
 }
 
+/**
+ * Whether an MCP tool's document and the one its command printed are the same
+ * read (#2707). Each graph member's `cached` flag (#2876) is left out: it says
+ * whether chant's per-member cache answered that one read, not what the graph
+ * is. The tool is called first, so its read can store the cache entry the
+ * command's read is then answered from, and the flag differs while the graph
+ * does not (#3019). Everything else must be equal.
+ */
+export function sameReadDocument(tool: unknown, printed: unknown): boolean {
+  return isDeepStrictEqual(withoutCacheFlags(tool), withoutCacheFlags(printed));
+}
+
+function withoutCacheFlags(doc: unknown): unknown {
+  if (typeof doc !== "object" || doc === null || !Array.isArray((doc as { members?: unknown }).members)) return doc;
+  const members = (doc as { members: unknown[] }).members.map((m) => {
+    if (typeof m !== "object" || m === null || !("cached" in m)) return m;
+    const { cached: _cached, ...rest } = m as Record<string, unknown>;
+    return rest;
+  });
+  return { ...doc, members };
+}
+
 /**
  * A transport that runs chant in the workspace `target()` names and records
  * every call and what it printed. `reset()` clears the record before a read.
@@ -556,7 +578,7 @@ export function recordingTransport(target: () => { workspaceDir: string; chantCo
     } catch {
       printedDoc = undefined;
     }
-    if (!isDeepStrictEqual(doc, printedDoc)) problems.push(`${argv.slice(1).join(" ")}: the MCP tool ${call.name} returned a document other than chant ${argv.join(" ")} printed`);
+    if (!sameReadDocument(doc, printedDoc)) problems.push(`${argv.slice(1).join(" ")}: the MCP tool ${call.name} returned a document other than chant ${argv.join(" ")} printed`);
     return { argv: [...argv], status: 0, stdout: JSON.stringify(doc), stderr: "" };
   };
   const transport: ChantTransport = {