@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/write-scope.ts

@@ -25,59 +25,78 @@
  *   detection only (ws-002).
  *
  * A principal's class comes from the role grants in the trust policy at base,
- * through {@link principalClass} alone (the agent, runner and service roles),
+ * through {@link principalClass} alone (the agent, runner and service roles,
+ * then the role each domain class a pinned package supplies names, #3080),
  * or from naming an agent session. Claiming a session only ever narrows what
  * a writer may do, so an unverified `CHANT_AGENT` or trailer is safe to honour.
+ *
+ * A writeScope key no pinned package supplies fails closed: a writer judged
+ * `human` might be in that class, so it is refused with
+ * `write-scope-class-unknown` until the plugin is installed at the pinned
+ * version or the entry is removed.
  */
 
 import { execFileSync } from "node:child_process";
 import { posix, relative, sep } from "node:path";
+import { isDeepStrictEqual } from "node:util";
+// @ts-ignore — picomatch has no types declaration
+import picomatch from "picomatch";
 import {
-  PRINCIPAL_CLASSES,
   readDeclaration,
   WorkspaceReadError,
   type AgentDeclaration,
   type ClassScope,
   type Declaration,
   type PrincipalClass,
+  type ProtectedPath,
   type WriteVerb,
 } from "./declaration";
+import {
+  classesOf,
+  coreClassRegistry,
+  loadClassRegistry,
+  principalClass as classOf,
+  roleGrants,
+  unknownScopeClasses,
+  type ClassRegistry,
+} from "./principal-classes";
 import type { ReasonCode } from "./reason-codes";
+import { parseJsonText } from "./jsonc";
 import { memberHolding } from "./record-assets";
 import { gitRoot } from "./record-source";
 import { normalisePrincipal, parseFrontMatter } from "./records";
+import type { WorkspaceTree } from "./tree";
 import { emptyPolicy, type TrustPolicy } from "./trust/policy";
 import { commitProvenance, policyAtBase, resolveBase } from "./trust/provenance";
+import { AGENT_TRAILER } from "./trailers";
 import { locateWorkspace } from "./which-chant";
 
 /** The environment variable naming the agent session a write is made in. */
 export const AGENT_ENV = "CHANT_AGENT";
 
-/** The commit trailer naming the agent session a commit was made in. */
-export const AGENT_TRAILER = "Chant-Agent";
+/** The commit trailer naming the agent session a commit was made in, one of chant's trailers (`trailers.ts`). */
+export { AGENT_TRAILER };
 
 /** Why a write is outside its writer's scope. Closed. */
-export const WRITE_SCOPE_CODES = ["write-scope-member", "write-scope-kind", "agent-unknown"] as const satisfies readonly ReasonCode[];
+export const WRITE_SCOPE_CODES = ["write-scope-member", "write-scope-kind", "write-scope-class-unknown", "agent-unknown"] as const satisfies readonly ReasonCode[];
 export type WriteScopeCode = (typeof WRITE_SCOPE_CODES)[number];
 
-/** The classes a role grant puts a principal in, in the order they are tried. Human is the rest. */
-const ROLE_CLASSES = ["agent", "runner", "service"] as const satisfies readonly PrincipalClass[];
-
 /**
- * The role grants a class is read from. Every read of roles for write scope
- * goes through here, so where the grants live (`.chant/trust.json` today,
- * possibly the declaration, #2547) is decided in one place: the policy.
+ * What `check --changes` reports a path with: the record-write codes, and a
+ * write to a protected path (#3146), which a record write never is. Closed.
  */
-export function roleGrants(policy: TrustPolicy): Record<string, string[]> {
-  return policy.roles;
-}
+export const SCOPE_FINDING_CODES = [...WRITE_SCOPE_CODES, "write-scope-protected"] as const satisfies readonly ReasonCode[];
+export type ScopeFindingCode = (typeof SCOPE_FINDING_CODES)[number];
+
+export { classesOf, roleGrants };
 
-/** The class a principal is in: the first of agent, runner and service whose role it holds at base, or human. */
-export function principalClass(policy: TrustPolicy, principal: string | null): PrincipalClass {
-  if (principal === null) return "human";
-  const name = normalisePrincipal(principal);
-  const grants = roleGrants(policy);
-  return ROLE_CLASSES.find((cls) => (grants[cls] ?? []).some((p) => normalisePrincipal(p) === name)) ?? "human";
+/**
+ * The class a principal is in: the first of agent, runner and service whose
+ * role it holds at base, then the first domain class in `classes` whose role
+ * it holds (#3080), or human.
+ */
+export function principalClass(policy: TrustPolicy, principal: string | null, classes: ClassRegistry = coreClassRegistry()): PrincipalClass {
+  return classOf(policy, principal, classes);
 }
 
 /** Who is writing, as the scope judges it. */
@@ -104,7 +123,12 @@ export class WriteScopeError extends Error {
  * the declaration declares none by that name), in the session that lists
  * `principal`, or else in the class `principal`'s roles give it.
  */
-export function resolveWriter(declaration: Declaration | null, policy: TrustPolicy, given: { agent?: string | null; principal?: string | null }): Writer {
+export function resolveWriter(
+  declaration: Declaration | null,
+  policy: TrustPolicy,
+  given: { agent?: string | null; principal?: string | null },
+  classes: ClassRegistry = coreClassRegistry(),
+): Writer {
   const principal = given.principal ?? null;
   const agents = declaration?.agents ?? [];
   if (given.agent !== undefined && given.agent !== null) {
@@ -125,19 +149,40 @@ export function resolveWriter(declaration: Declaration | null, policy: TrustPoli
     const agent = agents.find((a) => a.principals.some((p) => normalisePrincipal(p) === name));
     if (agent) return { principal, class: "agent", agent };
   }
-  return { principal, class: principalClass(policy, principal), agent: null };
+  return { principal, class: principalClass(policy, principal, classes), agent: null };
+}
+
+/**
+ * Refuse `writer` when the declaration's writeScope names a class `classes`
+ * doesn't know and the writer is judged human (#3080): nothing says which
+ * role puts a principal in the unknown class, so this writer may be in it.
+ * A writer in another class is judged by that class, which comes first.
+ */
+export function unknownClassVerdict(declaration: Declaration | null, writer: Writer, classes: ClassRegistry): { ok: true } | { ok: false; code: "write-scope-class-unknown"; message: string } {
+  if (writer.class !== "human") return OK;
+  const unknown = unknownScopeClasses(declaration?.writeScope ?? null, classes);
+  if (unknown.length === 0) return OK;
+  const list = unknown.map((c) => `writeScope.${c}`).join(", ");
+  return {
+    ok: false,
+    code: "write-scope-class-unknown",
+    message: `${who(writer)} may be in ${unknown.length === 1 ? "a class" : "classes"} no pinned package supplies (${list}), so its scope can't be told; install the package that supplies ${unknown.length === 1 ? "it" : "them"} at the pinned version, or remove the entry (known classes: ${classes.names().join(", ")})`,
+  };
 }
 
 /** The scope that applies to `writer`, or null when its class is not restricted. An agent is always restricted to its member. */
 export function scopeOf(declaration: Declaration | null, writer: Writer): ClassScope | null {
   const entry = declaration?.writeScope?.[writer.class];
-  if (writer.class === "agent") return { members: null, records: entry?.records ?? null, pointer: entry?.pointer ?? "/agents" };
+  if (writer.class === "agent") return { members: null, records: entry?.records ?? null, protected: entry?.protected ?? [], pointer: entry?.pointer ?? "/agents" };
   return entry ?? null;
 }
 
-export type ScopeVerdict = { ok: true } | { ok: false; code: Exclude<WriteScopeCode, "agent-unknown">; message: string };
+export type ScopeVerdict = { ok: true } | { ok: false; code: Exclude<ScopeFindingCode, "agent-unknown">; message: string };
 
-const OK: ScopeVerdict = { ok: true };
+/** A record write's verdict: never write-scope-protected, since protected paths judge files that aren't records. */
+export type RecordVerdict = { ok: true } | { ok: false; code: Exclude<WriteScopeCode, "agent-unknown">; message: string };
+
+const OK = { ok: true } as const;
 
 function who(writer: Writer): string {
   if (writer.agent) return `agent session ${writer.agent.name}, bound to member ${writer.agent.member},`;
@@ -164,7 +209,7 @@ export interface ScopedKind {
 }
 
 /** Whether `writer` may write a record of `kind` with `verb`. A delete is never in a restricted scope. */
-export function judgeRecord(declaration: Declaration | null, writer: Writer, kind: ScopedKind, verb: WriteVerb | "delete"): ScopeVerdict {
+export function judgeRecord(declaration: Declaration | null, writer: Writer, kind: ScopedKind, verb: WriteVerb | "delete"): RecordVerdict {
   const scope = scopeOf(declaration, writer);
   if (scope === null) return OK;
   // The workspace's own kinds are in every member's reach; a member's kinds only in its own.
@@ -194,17 +239,97 @@ export function judgeRecord(declaration: Declaration | null, writer: Writer, kin
   };
 }
 
-/** Whether `writer` may write the file at `path`, from the workspace root. */
-export function judgePath(declaration: Declaration | null, writer: Writer, path: string): ScopeVerdict {
+/**
+ * The protected entry of `entries` that covers `path` (#3146, ws-077): one
+ * whose glob matches the path or a directory above it. Null when none does.
+ */
+export function protectedEntry(entries: readonly ProtectedPath[], path: string): ProtectedPath | null {
+  if (entries.length === 0) return null;
+  const parts = path.split("/");
+  const prefixes = parts.map((_, i) => parts.slice(0, i + 1).join("/"));
+  for (const entry of entries) {
+    const match = picomatch(entry.path, { dot: true }) as (p: string) => boolean;
+    if (prefixes.some((p) => match(p))) return entry;
+  }
+  return null;
+}
+
+/** What an array item an `except` pointer covers is compared as, so the items after it keep their places. */
+const REMOVED = Symbol("except");
+
+/** Remove every value `pointer` matches from `value`, in place; a `*` token matches every key or index at its level. */
+function removeAtPointer(value: unknown, tokens: readonly string[]): void {
+  if (tokens.length === 0 || value === null || typeof value !== "object") return;
+  const [head, ...rest] = tokens;
+  const container = value as Record<string, unknown>;
+  const names = head === "*" ? Object.keys(container) : Object.prototype.hasOwnProperty.call(container, head) ? [head] : [];
+  for (const name of names) {
+    if (rest.length > 0) removeAtPointer(container[name], rest);
+    else if (Array.isArray(value)) (value as unknown[])[Number(name)] = REMOVED;
+    else delete container[name];
+  }
+}
+
+/**
+ * Whether JSON text `before` and `after` differ only in what `except`
+ * allows: a top-level key, or, for an entry starting with `/`, the values a
+ * JSON Pointer matches, where a `*` token matches every key or array index
+ * at its level (`/members/*\/box/listing`, #3308). Comments and trailing
+ * commas are read, so a `.jsonc` declaration is judged too. False when either
+ * is missing or isn't a JSON object.
+ */
+export function onlyKeysChanged(before: string | null, after: string | null, except: readonly string[]): boolean {
+  if (before === null || after === null || except.length === 0) return false;
+  const strip = (text: string): Record<string, unknown> | null => {
+    const parsed = parseJsonText(text, { jsonc: true });
+    if (!parsed.ok) return null;
+    const value = parsed.value;
+    if (value === null || typeof value !== "object" || Array.isArray(value)) return null;
+    const copy = structuredClone(value) as Record<string, unknown>;
+    for (const entry of except) {
+      if (entry.startsWith("/")) removeAtPointer(copy, entry.slice(1).split("/").map((t) => t.replace(/~1/g, "/").replace(/~0/g, "~")));
+      else delete copy[entry];
+    }
+    return copy;
+  };
+  const a = strip(before);
+  const b = strip(after);
+  return a !== null && b !== null && isDeepStrictEqual(a, b);
+}
+
+/** A file's text before and after a write, read only when a protected entry with `except` needs it. */
+export interface PathChange {
+  before(): string | null;
+  after(): string | null;
+}
+
+/**
+ * Whether `writer` may write the file at `path`, from the workspace root:
+ * the path is in a member the writer may write, and no protected entry of
+ * its scope covers it, unless the entry's `except` allows the change (#3146).
+ * Without `change`, a write to a path an `except` entry covers is judged as a
+ * change outside the allowed keys.
+ */
+export function judgePath(declaration: Declaration | null, writer: Writer, path: string, change?: PathChange): ScopeVerdict {
   const scope = scopeOf(declaration, writer);
   if (scope === null) return OK;
   const member = memberHolding(path, declaration?.members ?? []);
-  if (memberAllowed(writer, scope, member)) return OK;
-  const where = member === null ? "is in no member" : `is in member ${member}`;
+  if (!memberAllowed(writer, scope, member)) {
+    const where = member === null ? "is in no member" : `is in member ${member}`;
+    return {
+      ok: false,
+      code: "write-scope-member",
+      message: `${who(writer)} may not write ${path}, which ${where}: ${writer.class === "agent" ? "an agent session writes only its own member" : `writeScope.${writer.class}.members leaves it out`}`,
+    };
+  }
+  const guarded = protectedEntry(scope.protected, path);
+  if (guarded === null) return OK;
+  if (guarded.except.length > 0 && change && onlyKeysChanged(change.before(), change.after(), guarded.except)) return OK;
+  const allowance = guarded.except.length > 0 ? `, outside what its except allows (${guarded.except.join(", ")})` : "";
   return {
     ok: false,
-    code: "write-scope-member",
-    message: `${who(writer)} may not write ${path}, which ${where}: ${writer.class === "agent" ? "an agent session writes only its own member" : `writeScope.${writer.class}.members leaves it out`}`,
+    code: "write-scope-protected",
+    message: `${who(writer)} may not write ${path}${allowance}: writeScope.${writer.class}.protected lists ${guarded.path}`,
   };
 }
 
@@ -220,12 +345,14 @@ export interface ScopeSource {
   /** The workspace root from the git root, "." for the git root, or null without a declaration. */
   root: string | null;
   policy: TrustPolicy;
+  /** The principal classes: the core four and those the declaration's pins supply, path pins read where the declaration was (#3080). */
+  classes: ClassRegistry;
 }
 
-function readAt(cwd: string, at?: string): { declaration: Declaration; rootOnDisk: string; root: string } | null {
+function readAt(cwd: string, at?: string): { declaration: Declaration; rootOnDisk: string; root: string; tree: WorkspaceTree } | null {
   try {
     const located = locateWorkspace(cwd, at);
-    return { declaration: readDeclaration(located.tree), rootOnDisk: located.rootOnDisk, root: located.root };
+    return { declaration: readDeclaration(located.tree), rootOnDisk: located.rootOnDisk, root: located.root, tree: located.tree };
   } catch (err) {
     if (err instanceof WorkspaceReadError) return null;
     throw err;
@@ -242,12 +369,16 @@ export function scopeSource(cwd: string): ScopeSource {
   const top = gitRoot(cwd);
   const base = top ? resolveBase(top) : null;
   const policy = top && base ? policyAtBase(top, base) : emptyPolicy(null);
+  const withClasses = (read: NonNullable<ReturnType<typeof readAt>>) => {
+    const { tree, ...rest } = read;
+    return { ...rest, classes: loadClassRegistry(read.declaration.pins, read.rootOnDisk, { tree }).registry };
+  };
   if (base?.commit) {
     const atBase = readAt(cwd, base.commit);
-    if (atBase) return { ...atBase, from: "base", policy };
+    if (atBase) return { ...withClasses(atBase), from: "base", policy };
   }
   const here = readAt(cwd);
-  return here ? { ...here, from: "working-tree", policy } : { declaration: null, from: null, rootOnDisk: null, root: null, policy };
+  return here ? { ...withClasses(here), from: "working-tree", policy } : { declaration: null, from: null, rootOnDisk: null, root: null, policy, classes: coreClassRegistry() };
 }
 
 const toPosix = (p: string) => (sep === "/" ? p : p.split(sep).join("/"));
@@ -271,16 +402,20 @@ export function scopedKind(source: ScopeSource, kindName: string, kindFile: stri
  * Refuse a record write outside the writer's scope (#2548): throws a
  * {@link WriteScopeError}. `agent` is the session the write names
  * (`CHANT_AGENT`), and `principal` who the write names as its author.
+ * Returns what it read at base, for the identity rule (#3163).
  */
 export function refuseRecordWrite(
   cwd: string,
   write: { kindName: string; kindFile: string; recordsDir: string; verb: WriteVerb; agent?: string | null; principal?: string | null },
-): void {
+): ScopeSource {
   const source = scopeSource(cwd);
-  if (source.declaration === null && (write.agent === undefined || write.agent === null)) return;
-  const writer = resolveWriter(source.declaration, source.policy, { agent: write.agent, principal: write.principal });
+  if (source.declaration === null && (write.agent === undefined || write.agent === null)) return source;
+  const writer = resolveWriter(source.declaration, source.policy, { agent: write.agent, principal: write.principal }, source.classes);
+  const unknown = unknownClassVerdict(source.declaration, writer, source.classes);
+  if (!unknown.ok) throw new WriteScopeError(unknown.code, unknown.message);
   const verdict = judgeRecord(source.declaration, writer, scopedKind(source, write.kindName, write.kindFile, write.recordsDir), write.verb);
   if (!verdict.ok) throw new WriteScopeError(verdict.code, verdict.message);
+  return source;
 }
 
 // ── The check over a range ───────────────────────────────────────────────────
@@ -301,9 +436,9 @@ export interface ScopeCommit {
 }
 
 export interface ScopeFinding {
-  /** `finding:<code>:<commit>:<path>`, or `finding:agent-unknown:<commit>`. */
+  /** `finding:<code>:<commit>:<path>`, or `finding:<code>:<commit>` for agent-unknown and write-scope-class-unknown, which judge the whole commit. */
   id: string;
-  code: WriteScopeCode;
+  code: ScopeFindingCode;
   commit: string;
   /** From the workspace root, or null for a finding on the whole commit. */
   path: string | null;
@@ -318,7 +453,7 @@ export interface ScopeFinding {
 export interface ScopeReport {
   /** The commit the declaration and the trust policy were read at. */
   base: string;
-  /** The classes with a writeScope entry, and agent when any session is declared. */
+  /** The classes with a writeScope entry, and agent when any session is declared: core first, then domain classes in pin order, then any no pinned package supplies. */
   restricted: PrincipalClass[];
   agents: string[];
   commits: ScopeCommit[];
@@ -384,13 +519,17 @@ export async function checkWriteScope(q: {
   prefix: string;
   declaration: Declaration;
   kinds: CheckKind[];
+  /** The principal classes the declaration's pins supply at base (#3080). Without it, the core four. */
+  classes?: ClassRegistry;
 }): Promise<ScopeReport | null> {
   const { top, base, head, prefix, declaration } = q;
+  const classes = q.classes ?? coreClassRegistry();
   if (declaration.writeScope === null && declaration.agents.length === 0) return null;
   const policy = policyAtBase(top, { commit: base, from: "flag" });
   const { activeAttestors } = await import("./trust/attestor");
   const attestors = await activeAttestors();
-  const restricted = PRINCIPAL_CLASSES.filter((c) => declaration.writeScope?.[c] !== undefined || (c === "agent" && declaration.agents.length > 0));
+  const scoped = (c: string) => declaration.writeScope?.[c] !== undefined || (c === "agent" && declaration.agents.length > 0);
+  const restricted = [...classes.names().filter(scoped), ...unknownScopeClasses(declaration.writeScope, classes)];
   const report: ScopeReport = { base, restricted, agents: declaration.agents.map((a) => a.name), commits: [], findings: [] };
   const list = git(top, ["rev-list", "--reverse", "--no-merges", `${base}..${head}`]).split("\n").filter(Boolean);
   for (const commit of list) {
@@ -410,7 +549,7 @@ export async function checkWriteScope(q: {
     }
     let writer: Writer;
     try {
-      writer = resolveWriter(declaration, policy, { agent: named, principal });
+      writer = resolveWriter(declaration, policy, { agent: named, principal }, classes);
     } catch (err) {
       if (!(err instanceof WriteScopeError)) throw err;
       report.commits.push({ commit, subject, principal, attested, class: "agent", agent: named, paths: paths.length });
@@ -418,6 +557,11 @@ export async function checkWriteScope(q: {
       continue;
     }
     report.commits.push({ commit, subject, principal, attested, class: writer.class, agent: writer.agent?.name ?? null, paths: paths.length });
+    const unknown = unknownClassVerdict(declaration, writer, classes);
+    if (!unknown.ok) {
+      report.findings.push({ id: `finding:${unknown.code}:${commit}`, code: unknown.code, commit, path: null, principal, class: writer.class, agent: null, verb: null, message: `${commit.slice(0, 8)}: ${unknown.message}` });
+      continue;
+    }
     if (scopeOf(declaration, writer) === null) continue;
     for (const p of paths) {
       const inWorkspace = prefix === "" ? p.path : p.path.slice(prefix.length + 1);
@@ -428,7 +572,10 @@ export async function checkWriteScope(q: {
         verb = p.status === "A" ? "new" : p.status === "D" ? "delete" : modifiedVerb(top, commit, p.path, kind);
         verdict = judgeRecord(declaration, writer, kind.scoped, verb);
       } else {
-        verdict = judgePath(declaration, writer, inWorkspace);
+        verdict = judgePath(declaration, writer, inWorkspace, {
+          before: () => (p.status === "A" ? null : show(top, `${commit}^`, p.path)),
+          after: () => (p.status === "D" ? null : show(top, commit, p.path)),
+        });
       }
       if (verdict.ok) continue;
       report.findings.push({

package/src/yaml.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "vitest";
 import { load as jsYamlLoad } from "js-yaml";
-import { emitYAML, parseYAML, parseYAMLDocument, parseScalar, splitYAMLDocuments, YAMLParseError } from "./yaml";
+import { emitYAML, emitYAMLEntry, parseYAML, parseYAMLDocument, parseScalar, splitYAMLDocuments, YAMLParseError } from "./yaml";
 
 // ---------------------------------------------------------------------------
 // emitYAML
@@ -781,3 +781,113 @@ describe("parseYAML — anchors, aliases and merge keys (#2991)", () => {
     expect(() => parseYAML("a: &v 1\nb:\n  <<: *v\n")).toThrow(YAMLParseError);
   });
 });
+
+// #3006: parseYAML is js-yaml with chant's schema. Before it, an inline
+// comment stayed in the value and a flow collection that was not JSON came
+// back as a string, without a warning.
+describe("parseYAML — comments and flow collections (#3006)", () => {
+  const same = (src: string): void => {
+    expect(parseYAMLDocument(src)).toEqual(jsYamlLoad(src));
+  };
+
+  test("an inline comment is not part of the value", () => {
+    expect(parseYAML("replicas: 1 # comment\n")).toEqual({ replicas: 1 });
+    expect(parseYAML("image: nginx:1.27 # pinned\nport: 80\t# tab\n")).toEqual({ image: "nginx:1.27", port: 80 });
+    same("items:\n  - a # one\n  - name: b # two\n    url: http://x/#frag\n");
+  });
+
+  test("a # inside a quoted or plain scalar is kept", () => {
+    expect(parseYAML("a: 'x # y'\nb: \"x # y\"\nc: x#y\n")).toEqual({ a: "x # y", b: "x # y", c: "x#y" });
+  });
+
+  test("flow sequences and mappings that are not JSON", () => {
+    expect(parseYAML("args: [--foo, --bar]\n")).toEqual({ args: ["--foo", "--bar"] });
+    same("weekdays: [saturday, sunday]\ndays: ['1:7']\nmeta: { name: gw, labels: { app: x } }\n");
+    same("times:\n  - { start_time: \"00:00\", end_time: \"24:00\" }\n");
+  });
+
+  test("a flow collection spanning lines", () => {
+    same("args: [\n  --foo,\n  --bar\n]\nmeta: {\n  a: 1,\n  b: [x, y]\n}\n");
+  });
+
+  test("a nested sequence on one line, as Grafana writes object matchers", () => {
+    expect(parseYAML("matchers:\n  - - severity\n    - =\n    - page\n")).toEqual({ matchers: [["severity", "=", "page"]] });
+  });
+
+  test("a folded scalar keeps the line breaks of its more-indented lines (#2925)", () => {
+    same("msg: >\n  a\n    indented\n  b\n");
+  });
+});
+
+describe("parseYAML — what chant keeps from its old parser (#3006)", () => {
+  test("yes and no are booleans; on and off stay strings", () => {
+    expect(parseYAML("a: yes\nb: no\nc: on\nd: off\n")).toEqual({ a: true, b: false, c: "on", d: "off" });
+  });
+
+  test("a date stays a string", () => {
+    expect(parseYAML("date: 2024-01-01\nat: 2024-01-01T00:00:00Z\n")).toEqual({ date: "2024-01-01", at: "2024-01-01T00:00:00Z" });
+  });
+
+  test("a local tag on a scalar or sequence reads as its text", () => {
+    expect(parseYAML("s: !reference [.base, script]\nr: !Ref MyApi\n")).toEqual({
+      s: "!reference [.base, script]",
+      r: "!Ref MyApi",
+    });
+    expect(parseYAML(emitYAMLEntry("s", { tag: "!reference", value: [".base", "script"] }))).toEqual({
+      s: "!reference [.base, script]",
+    });
+  });
+
+  test("a duplicate key takes the last value", () => {
+    expect(parseYAML("a: 1\na: 2\n")).toEqual({ a: 2 });
+  });
+
+  test("a `---`-separated stream reads as one mapping, as before", () => {
+    expect(parseYAML("a: 1\n---\nb: 2\n")).toEqual({ a: 1, b: 2 });
+  });
+
+  test("a scalar document is an error naming its line", () => {
+    expect(() => parseYAML("# header\njust text\n")).toThrow(/YAML line 2:/);
+    expect(parseYAML("")).toEqual({});
+    expect(parseYAML("# only a comment\n")).toEqual({});
+  });
+
+  test("a merged block is a copy, not shared with its anchor", () => {
+    const doc = parseYAML("a: &a\n  x: { n: 1 }\nb:\n  <<: *a\n") as { a: { x: { n: number } }; b: { x: { n: number } } };
+    doc.b.x.n = 2;
+    expect(doc.a.x.n).toBe(1);
+  });
+});
+
+describe("emitYAMLEntry (#3006)", () => {
+  test("an inline value gets a space after the colon", () => {
+    expect(emitYAMLEntry("jobs", {})).toBe("jobs: {}");
+    expect(emitYAMLEntry("stages", [])).toBe("stages: []");
+    expect(emitYAMLEntry("name", "x")).toBe("name: x");
+  });
+
+  test("a block value follows on the next line", () => {
+    expect(emitYAMLEntry("stages", ["a", "b"])).toBe("stages:\n  - a\n  - b");
+    expect(emitYAMLEntry("b", { c: 1 }, 1)).toBe("  b:\n    c: 1");
+  });
+
+  test("what it writes parses back", () => {
+    const doc = { on: {}, env: { A: "1" }, stages: [], jobs: { build: { script: ["make"] } } };
+    const text = Object.entries(doc).map(([k, v]) => emitYAMLEntry(k, v)).join("\n");
+    expect(parseYAML(text)).toEqual(doc);
+  });
+});
+
+describe("emitYAML quotes strings a parser would read as something else (#3006)", () => {
+  const values = ["foo:", "- x", "? x", "|x", ">x", "@x", "`x", "%x", ",x", "]x", "}x", "True", "NULL", "~", ".inf", "-.inf", ".NaN", " lead", "trail ", "-1", "+1", ".5", "Yes"];
+
+  for (const v of values) {
+    test(`round-trips ${JSON.stringify(v)}`, () => {
+      expect(parseYAML(`k: ${emitYAML(v, 0)}\n`).k).toBe(v);
+    });
+  }
+
+  test("strings that were safe stay plain", () => {
+    for (const v of ["--flag", "-x", "a:b", "http://a/b", "on"]) expect(emitYAML(v, 0)).toBe(v);
+  });
+});