@intentius/chant 0.97.0 → 0.99.0

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

package/src/yaml.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "vitest";
-import { emitYAML, parseYAML, parseScalar } from "./yaml";
+import { load as jsYamlLoad } from "js-yaml";
+import { emitYAML, parseYAML, parseYAMLDocument, parseScalar, splitYAMLDocuments, YAMLParseError } from "./yaml";
 
 // ---------------------------------------------------------------------------
 // emitYAML
@@ -538,3 +539,245 @@ describe("parseYAML — a colon without following space is not a mapping (#2013)
     });
   });
 });
+
+// ---------------------------------------------------------------------------
+// parseYAMLDocument / splitYAMLDocuments (#2965)
+// ---------------------------------------------------------------------------
+
+describe("parseYAMLDocument", () => {
+  test("a top-level list parses as a list", () => {
+    expect(parseYAMLDocument("- a\n- b\n")).toEqual(["a", "b"]);
+    expect(parseYAMLDocument("# rules\n\n- name: one\n  expr: up\n- name: two\n")).toEqual([
+      { name: "one", expr: "up" },
+      { name: "two" },
+    ]);
+  });
+
+  test("parseYAML still returns a mapping for the same input", () => {
+    expect(parseYAML("- a\n- b\n")).toEqual({});
+  });
+
+  test("a mapping and JSON parse as parseYAML parses them", () => {
+    expect(parseYAMLDocument("a: 1\nb:\n  - x\n")).toEqual({ a: 1, b: ["x"] });
+    expect(parseYAMLDocument("[1, 2]")).toEqual([1, 2]);
+    expect(parseYAMLDocument("")).toEqual({});
+  });
+});
+
+describe("splitYAMLDocuments", () => {
+  test("splits on bare --- separators", () => {
+    expect(splitYAMLDocuments("a: 1\n---\nb: 2\n")).toEqual(["a: 1", "b: 2\n"]);
+  });
+
+  test("a separator may carry a trailing comment", () => {
+    expect(splitYAMLDocuments("--- # first\na: 1\n---   # second\nb: 2")).toEqual(["a: 1", "b: 2"]);
+  });
+
+  test("... ends a document", () => {
+    expect(splitYAMLDocuments("a: 1\n...\nb: 2\n... # done\n")).toEqual(["a: 1", "b: 2"]);
+    expect(splitYAMLDocuments("---\na: 1\n...\n---\nb: 2\n...\n")).toEqual(["a: 1", "b: 2"]);
+  });
+
+  test("drops empty and comment-only documents", () => {
+    expect(splitYAMLDocuments("# header\n---\n\n---\na: 1\n---\n# trailing\n")).toEqual(["a: 1"]);
+    expect(splitYAMLDocuments("")).toEqual([]);
+  });
+
+  test("only a whole-line marker splits", () => {
+    expect(splitYAMLDocuments("a: ---\nb: |\n  ---\n---x: 1\n")).toEqual(["a: ---\nb: |\n  ---\n---x: 1\n"]);
+  });
+
+  test("normalizes CRLF line endings", () => {
+    expect(splitYAMLDocuments("a: 1\r\n--- # c\r\nb: 2\r\n")).toEqual(["a: 1", "b: 2\n"]);
+  });
+});
+
+// Blank, whitespace-only and comment lines inside a block, and other input the
+// parser used to skip or hoist without a word (#2991). Each valid case is
+// checked against js-yaml, so the expected value is what a full parser reads.
+describe("parseYAML — blank lines inside blocks (#2991)", () => {
+  const same = (src: string): void => {
+    expect(parseYAMLDocument(src)).toEqual(jsYamlLoad(src));
+  };
+
+  test("a blank line between a key and its nested mapping (the reported bug)", () => {
+    expect(parseYAML("a:\n\n  b: 1\nc: 2\n")).toEqual({ a: { b: 1 }, c: 2 });
+  });
+
+  test("a whitespace-only line between a key and its nested mapping", () => {
+    expect(parseYAML("a:\n  \n  b: 1\nc: 2\n")).toEqual({ a: { b: 1 }, c: 2 });
+    expect(parseYAML("a:\n\t\n  b: 1\nc: 2\n")).toEqual({ a: { b: 1 }, c: 2 });
+  });
+
+  test("a comment at a lower column between a key and its nested mapping", () => {
+    same("a:\n# about b\n  b: 1\nc: 2\n");
+  });
+
+  test("a blank line before the first item of a block sequence", () => {
+    // This one lost every key after the sequence, not just the sequence.
+    same("a:\n\n  - 1\n  - 2\nc: 2\n");
+    same("a:\n\n- 1\n- 2\nc: 2\n");
+  });
+
+  test("blank lines between block sequence items", () => {
+    same("a:\n  - 1\n\n  -   \n\n  - 3\nb: 2\n");
+  });
+
+  test("blank lines between the keys of a nested mapping", () => {
+    same("a:\n  b: 1\n\n  c:\n\n    d: 2\n\n  e: 3\nf: 4\n");
+  });
+
+  test("blank lines before nested blocks inside a sequence item", () => {
+    same("a:\n- name: x\n  env:\n\n  - n: 1\n  meta:\n\n    k: v\n\n  last: 1\nc: 2\n");
+    same("a:\n- first:\n\n    k: v\n  second: 2\n");
+  });
+
+  test("a dash alone on its line takes the block below it", () => {
+    same("a:\n-\n  x: 1\n  y: 2\n-\n\n  - 1\n-\n- z\n");
+  });
+
+  test("CRLF line endings, blank lines included", () => {
+    expect(parseYAML("a:\r\n\r\n  b: 1\r\n  c:\r\n  \r\n  - x\r\nd: 2\r\n")).toEqual({
+      a: { b: 1, c: ["x"] },
+      d: 2,
+    });
+  });
+
+  test("trailing whitespace on keys, items and blank lines", () => {
+    same("a:   \n    \n  b: 1   \n  c:  \n\t\n    d: 2\ne:\n  - x   \n  -   y: 1  \n      z: 2\n");
+  });
+
+  test("a sequence item indented past `- ` keeps its keys together", () => {
+    same("-   a: 1\n    b: 2\n-   c: 3\n");
+  });
+
+  test("the emitter's output still round-trips", () => {
+    const value = { a: { b: [{ c: 1, d: { e: "x" } }, "y"], f: null }, g: [[]] };
+    expect(parseYAML(emitYAML(value, 0).trimStart())).toEqual(value);
+  });
+});
+
+describe("parseYAML — scalars spanning lines (#2991)", () => {
+  const same = (src: string): void => {
+    expect(parseYAMLDocument(src)).toEqual(jsYamlLoad(src));
+  };
+
+  test("a plain scalar wrapped onto more lines, as go-yaml (Helm toYaml) wraps them", () => {
+    same("description: a long line that go-yaml\n  wraps at eighty columns\n\n  and a paragraph\nnext: 1\n");
+  });
+
+  test("a wrapped plain scalar as a sequence item and as an item's key", () => {
+    same("- long text\n  continued\n- name: x\n  help: more\n    text\n  after: 1\n");
+  });
+
+  test("a scalar on the line after its key", () => {
+    same("a:\n  hello\n  there\nb: 1\n");
+  });
+
+  test("a double-quoted scalar across lines, with a blank line and an escaped break", () => {
+    same('a: "one\n  two\n\n  three"\nb: "x\\\n    y"\nc: 1\n');
+  });
+
+  test("a single-quoted scalar across lines", () => {
+    same("a: 'it''s\n  here'\nb: 1\n");
+  });
+
+  test("an unterminated quoted scalar is an error", () => {
+    expect(() => parseYAML('a: "abc\nb: 1\n')).toThrow(YAMLParseError);
+  });
+});
+
+describe("parseYAML — quoted keys (#2991)", () => {
+  test("a quoted key holding a colon is read, not skipped", () => {
+    expect(parseYAML('"a:b": 1\nc: 2\n')).toEqual({ "a:b": 1, c: 2 });
+  });
+
+  test("quotes are not part of the key", () => {
+    expect(parseYAMLDocument("- \"a\": \"b\"\n  'c:d': 2\n")).toEqual([{ a: "b", "c:d": 2 }]);
+  });
+});
+
+describe("parseYAML — lines it cannot place are errors, not drops (#2991)", () => {
+  const throwsAt = (src: string, line: number): void => {
+    let error: unknown;
+    try {
+      parseYAML(src);
+    } catch (err) {
+      error = err;
+    }
+    expect(error).toBeInstanceOf(YAMLParseError);
+    expect((error as YAMLParseError).line).toBe(line);
+  };
+
+  test("a key indented under a scalar value", () => {
+    // Used to read as { a: 1, b: 2, c: 3 }.
+    throwsAt("a: 1\n   b: 2\nc: 3\n", 2);
+  });
+
+  test("a key indented past its siblings inside a sequence item", () => {
+    throwsAt("items:\n- name: x\n  image: y\n     stray: z\n", 4);
+  });
+
+  test("a line that is neither a key nor an item", () => {
+    throwsAt("a: 1\njust text\nb: 2\n", 2);
+  });
+
+  test("a dedent to a column no mapping is at", () => {
+    throwsAt("  a: 1\nb: 2\n", 2);
+  });
+
+  test("a tag before a nested block names the construct", () => {
+    expect(() => parseYAML("a: !Thing\n  b: 1\n")).toThrow(/the tag "!Thing"/);
+  });
+
+  test("an alias with no anchor before it", () => {
+    throwsAt("a: *nowhere\n", 1);
+  });
+
+  test("document markers are still skipped, as before", () => {
+    expect(parseYAML("---\na: 1\n...\n")).toEqual({ a: 1 });
+  });
+
+  test("a top-level list still reads as an empty mapping through parseYAML", () => {
+    expect(parseYAML("- a\n- b\n")).toEqual({});
+  });
+});
+
+// GitLab CI templates and Alertmanager configs anchor a block and merge it
+// elsewhere. Before #2991 the anchored block was hoisted into its parent and
+// the alias read as the string "*name".
+describe("parseYAML — anchors, aliases and merge keys (#2991)", () => {
+  const same = (src: string): void => {
+    expect(parseYAMLDocument(src)).toEqual(jsYamlLoad(src));
+  };
+
+  test("an anchored mapping merged into jobs, a GitLab CI template", () => {
+    same(
+      ".test-template: &test-defaults\n  stage: test\n  before_script:\n    - npm ci\n\n" +
+        "unit-test:\n  <<: *test-defaults\n  script:\n    - npm test\n" +
+        "lint:\n  stage: lint\n  <<: *test-defaults\n",
+    );
+  });
+
+  test("an anchored sequence item merged into the next, an Alertmanager receiver", () => {
+    same("slack_configs:\n  - &slack\n    channel: '#db-alerts'\n    send_resolved: true\n  - <<: *slack\n    channel: '#db-oncall'\n");
+  });
+
+  test("anchored scalars and sequences, and aliases to them", () => {
+    same("a: &v 1\nb: *v\nc: &list\n  - x\n  - y\nd: *list\ne:\n  - *v\n  - *list\n");
+  });
+
+  test("several anchors merged at once; the first listed wins", () => {
+    same("a: &a\n  x: 1\n  y: 1\nb: &b\n  y: 2\n  z: 2\nc:\n  <<: [*a, *b]\n  z: 3\n");
+  });
+
+  test("an alias is a copy, not shared with its anchor", () => {
+    const doc = parseYAML("a: &a\n  x: 1\nb: *a\n") as { a: { x: number }; b: { x: number } };
+    doc.b.x = 2;
+    expect(doc.a.x).toBe(1);
+  });
+
+  test("a merge key needs a mapping", () => {
+    expect(() => parseYAML("a: &v 1\nb:\n  <<: *v\n")).toThrow(YAMLParseError);
+  });
+});