@intentius/chant-lexicon-sql 0.0.0-stage → 0.112.0

package/src/core/find-templates.ts

@@ -0,0 +1,158 @@
+/**
+ * Finding a dialect's tags in a source file, for source-level lint rules and
+ * the editor (chant #3278). A rule reads a template's raw parts straight from
+ * the TypeScript AST and parses them the way the tag does, with every
+ * interpolation left a reference: lint cannot know the values.
+ *
+ * Every dialect exports tags with the same names (`table`, `view`), so a tag
+ * is a dialect's by the module it is imported from, never by its name.
+ */
+
+import * as ts from "typescript";
+import type { Token } from "./tokens";
+import { unescapeTemplateDelimiters } from "./template";
+
+/** Which imports make a tag one dialect's. */
+export interface TemplateSource<Tag extends string = string> {
+  /** The dialect, as `sql.dialect` names it. */
+  dialect: string;
+  /** The module specifiers its tags are imported from. */
+  modules: readonly string[];
+  /** The tag names it exports. */
+  tags: readonly Tag[];
+}
+
+export interface FoundTemplate<Tag extends string = string> {
+  node: ts.TaggedTemplateExpression;
+  /** The dialect whose module the tag was imported from. */
+  dialect: string;
+  tag: Tag;
+  /** The template's raw parts, backslashes as written. */
+  parts: string[];
+  /** Source offset of each part's first character. */
+  starts: number[];
+  /** The source text of each interpolation's expression. */
+  expressions: ts.Expression[];
+}
+
+/** Local names bound to the dialects' tags by this file's imports: `{ table as t }` maps `t` to `table`. */
+function tagBindings<Tag extends string>(source: ts.SourceFile, sources: readonly TemplateSource<Tag>[]): Map<string, { dialect: string; tag: Tag }> {
+  const out = new Map<string, { dialect: string; tag: Tag }>();
+  for (const stmt of source.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    // A module may export several dialects' tags (the package root does): a tag is the first source's that names it.
+    const from = sources.filter((s) => s.modules.includes((stmt.moduleSpecifier as ts.StringLiteral).text));
+    if (from.length === 0) continue;
+    const named = stmt.importClause?.namedBindings;
+    if (!named || !ts.isNamedImports(named)) continue;
+    for (const el of named.elements) {
+      const imported = (el.propertyName ?? el.name).text;
+      const source = from.find((s) => (s.tags as readonly string[]).includes(imported));
+      if (source) out.set(el.name.text, { dialect: source.dialect, tag: imported as Tag });
+    }
+  }
+  return out;
+}
+
+/** Every template in `source` whose tag is imported from one of `sources`' modules, in source order. */
+export function findSqlTemplates<Tag extends string>(source: ts.SourceFile, sources: readonly TemplateSource<Tag>[]): FoundTemplate<Tag>[] {
+  const bindings = tagBindings(source, sources);
+  if (bindings.size === 0) return [];
+  const found: FoundTemplate<Tag>[] = [];
+  const visit = (node: ts.Node) => {
+    if (ts.isTaggedTemplateExpression(node) && ts.isIdentifier(node.tag) && bindings.has(node.tag.text)) {
+      const t = node.template;
+      // As the tag reads them: raw, with `\`` and `\${` undone. An offset after one of those is off by one.
+      const parts = (
+        ts.isNoSubstitutionTemplateLiteral(t)
+          ? [t.rawText ?? t.text]
+          : [t.head.rawText ?? t.head.text, ...t.templateSpans.map((s) => s.literal.rawText ?? s.literal.text)]
+      ).map(unescapeTemplateDelimiters);
+      // A part's text begins one character after its opening delimiter (` or }).
+      const starts = ts.isNoSubstitutionTemplateLiteral(t)
+        ? [t.getStart(source) + 1]
+        : [t.head.getStart(source) + 1, ...t.templateSpans.map((s) => s.literal.getStart(source) + 1)];
+      const expressions = ts.isNoSubstitutionTemplateLiteral(t) ? [] : t.templateSpans.map((s) => s.expression);
+      const { dialect, tag } = bindings.get(node.tag.text)!;
+      found.push({ node, dialect, tag, parts, starts, expressions });
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return found;
+}
+
+/** 1-based line and column of a template offset. */
+export function templatePosition(source: ts.SourceFile, found: FoundTemplate, part: number, offset: number): { line: number; column: number } {
+  const pos = (found.starts[part] ?? found.node.getStart(source)) + offset;
+  const { line, character } = source.getLineAndCharacterOfPosition(pos);
+  return { line: line + 1, column: character + 1 };
+}
+
+/** A token's position; an interpolation's is its expression's. */
+export function tokenPosition(source: ts.SourceFile, found: FoundTemplate, token: Token): { line: number; column: number } {
+  if (token.kind === "ref") {
+    const expr = found.expressions[token.part];
+    if (expr) {
+      const { line, character } = source.getLineAndCharacterOfPosition(expr.getStart(source));
+      return { line: line + 1, column: character + 1 };
+    }
+  }
+  return templatePosition(source, found, token.part, token.start);
+}
+
+// ── The editor ─────────────────────────────────────────────────────────
+
+/** The offset of an LSP position (0-based line and character) in `content`. */
+export function offsetAt(content: string, pos: { line: number; character: number }): number {
+  let offset = 0;
+  for (let line = 0; line < pos.line; line++) {
+    const next = content.indexOf("\n", offset);
+    if (next < 0) return content.length;
+    offset = next + 1;
+  }
+  return Math.min(offset + pos.character, content.length);
+}
+
+export interface Located<Tag extends string = string> {
+  source: ts.SourceFile;
+  found: FoundTemplate<Tag>;
+  /** The template part the cursor is in, or -1 when it is inside an interpolation's expression. */
+  part: number;
+  /** Offset in that part. */
+  offset: number;
+  /** The interpolation the cursor is in, when part is -1. */
+  expression: number;
+  /** Absolute source offset. */
+  at: number;
+}
+
+/** The template the source offset `at` is inside, and where in it. */
+export function locateIn<Tag extends string>(content: string, at: number, sources: readonly TemplateSource<Tag>[], fileName = "file.ts"): Located<Tag> | undefined {
+  const source = ts.createSourceFile(fileName, content, ts.ScriptTarget.Latest, true);
+  for (const found of findSqlTemplates(source, sources)) {
+    const start = found.node.template.getStart(source);
+    const end = found.node.template.getEnd();
+    if (at <= start || at >= end) continue;
+    for (let i = 0; i < found.parts.length; i++) {
+      const from = found.starts[i]!;
+      if (at >= from && at <= from + found.parts[i]!.length) {
+        return { source, found, part: i, offset: at - from, expression: -1, at };
+      }
+    }
+    const expression = found.expressions.findIndex((e) => at >= e.getStart(source) && at <= e.getEnd());
+    return { source, found, part: -1, offset: 0, expression, at };
+  }
+  return undefined;
+}
+
+const WORD = /[A-Za-z0-9_]/;
+
+/** The identifier characters around an offset in a part. */
+export function wordAround(text: string, offset: number): { start: number; end: number } {
+  let start = offset;
+  while (start > 0 && WORD.test(text[start - 1]!)) start--;
+  let end = offset;
+  while (end < text.length && WORD.test(text[end]!)) end++;
+  return { start, end };
+}

package/src/core/handoff.ts

@@ -0,0 +1,44 @@
+/**
+ * How a plan hands a change it refuses to make in place to a migration Op,
+ * the same in every dialect.
+ *
+ * `chant sql plan`, `chant sql diff` and the applier refuse a change the
+ * dialect cannot make in place (a ClickHouse sorting-key change, which needs
+ * a rebuild). What they hand on is the Op to run instead, one per object: a
+ * declaration ready to put in an `*.op.ts` file, reviewed in the pull request
+ * like the schema change it carries out. Nothing is written for the user. The
+ * Op's own Plan phase classifies the change again against the server.
+ *
+ * Which Op, and the options a dialect suggests for it (ClickHouse's dual-write
+ * mode), are the dialect's.
+ */
+
+/** One Op to run instead of a refused change. A dialect adds its own suggested options. */
+export interface MigrationOpSuggestion {
+  /** The object the Op migrates, qualified as the dialect writes it. */
+  table: string;
+  /** The Op's suggested name. */
+  name: string;
+  env: string;
+  /** The declaration, ready to paste into an `*.op.ts` file. */
+  declaration: string;
+}
+
+/** An Op name for a migration of `table`: `<kind>-<table>`, lower case, runs of other characters as `-`. */
+export function migrationOpName(kind: string, table: string): string {
+  return `${kind}-${table.replace(/[^A-Za-z0-9]+/g, "-").toLowerCase()}`;
+}
+
+/**
+ * The suggestions as report lines: what the Op is, the import it comes from,
+ * then one declaration per line.
+ */
+export function renderMigrationOps(ops: readonly MigrationOpSuggestion[], op: { what: string; exportName: string; importPath: string }): string[] {
+  if (ops.length === 0) return [];
+  return [
+    "",
+    `Run ${ops.length === 1 ? "it" : "each"} as ${op.what}, declared in an *.op.ts file ` +
+      `(import { ${op.exportName} } from "${op.importPath}"), then \`chant run <name>\` until it is done:`,
+    ...ops.map((o) => `  ${o.declaration}`),
+  ];
+}

package/src/core/index.ts

@@ -0,0 +1,61 @@
+/**
+ * The sql lexicon's shared core: what every dialect (`../clickhouse/`, and
+ * Postgres next, #3289) builds on, with no database's grammar in it (#3275
+ * question 7, #3047 question 1).
+ *
+ * Belongs here:
+ *
+ * - the entity base and Declarable plumbing, and column references
+ *   (`entity.ts`);
+ * - the lossless tokenizer, with each dialect's character-level rules as a
+ *   table (`tokens.ts`), and the parser base: a cursor over significant
+ *   tokens with expressions kept as token spans (`cursor.ts`);
+ * - the tagged-template plumbing: raw parts, what a plain interpolation
+ *   splices in, `SqlLiteral`, the tag's error (`template.ts`), and splicing,
+ *   span text, what each spliced value fed, and a view's column lineage
+ *   (`interpolation.ts`);
+ * - finding a dialect's templates in a source file by the module its tags
+ *   are imported from, for lint and the editor (`find-templates.ts`);
+ * - references between objects, column lineage, and the creation order
+ *   (`references.ts`);
+ * - identity and renames between two schemas, and the change-set model
+ *   (`diff.ts`);
+ * - the classifier framework: the rule shape, classes as data per dialect,
+ *   `classifyDisruption()` over a dialect's rules, the text report
+ *   (`classifier.ts`);
+ * - normalization helpers that are not a database's grammar, such as the
+ *   `-- previously:` hint (`normalize.ts`);
+ * - the ownership trailer on an object's comment (`ownership.ts`);
+ * - receipts kept on the server (`receipts.ts`);
+ * - the applier's tri-state outcome, its envelope projection and the build
+ *   output reader (`apply.ts`);
+ * - the hand-off from a refused change to a migration Op (`handoff.ts`);
+ * - a throwaway server in a container, and test helpers that are not one
+ *   database's (`container.ts`, `testing/`).
+ *
+ * Stays in a dialect: its lexical rules and statement grammar, its key words
+ * and identifier quoting, `literal()`'s escaping, its entity types and props,
+ * its generated types and overlays, its normalization rules, its rule ids
+ * and classes and the documentation they cite, the statements its applier
+ * sends and how it waits on the server, its client and binding, import and
+ * observation over its catalog, and its migration Op.
+ *
+ * Nothing here is exported from the package root or a dialect subpath on its
+ * own: each dialect re-exports what its public surface names.
+ */
+
+export * from "./entity";
+export * from "./tokens";
+export * from "./cursor";
+export * from "./template";
+export * from "./interpolation";
+export * from "./find-templates";
+export * from "./references";
+export * from "./diff";
+export * from "./classifier";
+export * from "./normalize";
+export * from "./ownership";
+export * from "./receipts";
+export * from "./apply";
+export * from "./handoff";
+export * from "./container";

package/src/core/interpolation.ts

@@ -0,0 +1,225 @@
+/**
+ * What a tag does with its interpolations, in every dialect (chant #3196,
+ * #3212): splice plain values into the token list as SQL text while
+ * references stay `ref` tokens, render a span with its references written as
+ * names, record which props each spliced value fed, locate a parse error on
+ * its template line, and read column lineage off a view's select list.
+ *
+ * The dialect supplies its tokenizer rules, which values are its objects and
+ * column references, how a reference renders, and how a select-list name
+ * reads ({@link TemplateDialect}).
+ */
+
+import type { AttrRef } from "@intentius/chant/attrref";
+import { isTrivia, SqlSyntaxError, tokenize, tokenizeText, untokenize, type LexicalRules, type Token } from "./tokens";
+import type { Span } from "./cursor";
+import type { LineageEdge } from "./references";
+import type { SqlObject } from "./entity";
+import { interpolationLine, spliceText, SqlTemplateError } from "./template";
+
+/** What a dialect supplies to the shared template machinery. */
+export interface TemplateDialect {
+  lexical: LexicalRules;
+  /** An entity of this dialect: an interpolation that references an object. */
+  isObject(value: unknown): value is SqlObject;
+  /** A column reference to one of this dialect's objects. */
+  isColumnRef(value: unknown): value is AttrRef;
+  /**
+   * How a referenced object or column renders in the SQL. `index` is the
+   * interpolation's index in the template, for a dialect whose rendering
+   * depends on where the reference sits (Postgres writes a sequence inside
+   * `nextval(...)` as a `regclass` literal).
+   */
+  renderReference(value: unknown, index?: number): string;
+  /** A name token's value in a select list (identifier quotes off, and folded where the dialect folds). */
+  identValue(text: string): string;
+  /** The output name of the `n`th (1-based) select-list item that has none. */
+  unnamedOutput(n: number): string;
+  /**
+   * What lineage reads off a select list beyond ClickHouse's rules, each off
+   * unless set (#3278). `aliasWithoutAs`: `expr name` names its output
+   * `name`; `keyword` says which bare words are key words, so `CASE ... END`
+   * or `a COLLATE "C"` is not read as an alias. `distinctOn`: a
+   * `DISTINCT ON (...)` after `SELECT` is not an item. `qualifiedRefs`:
+   * `alias.${t.columns.c}` names its output after the column. `outputOf`:
+   * the output name of an item with no alias, when the dialect derives one
+   * from the expression (Postgres names `count(x)` "count"); undefined falls
+   * back to {@link unnamedOutput}.
+   */
+  lineage?: {
+    aliasWithoutAs?: boolean;
+    keyword?(t: Token): "reserved" | "keyword" | undefined;
+    distinctOn?: boolean;
+    qualifiedRefs?: boolean;
+    outputOf?(items: readonly Token[], valueOf: (t: Token) => unknown): string | undefined;
+  };
+}
+
+/** A template being built: its tokens, the interpolated values, and what each spliced value fed. */
+export interface TemplateCtx {
+  d: TemplateDialect;
+  tokens: Token[];
+  values: readonly unknown[];
+  /**
+   * Per interpolation, the props paths its spliced text landed in (#3212).
+   * Only spliced text counts: an interpolated entity or column is a reference
+   * to a sibling, not a value the author typed into this field.
+   */
+  fed: Array<Set<string>>;
+}
+
+/** Record that the spliced text inside `span` fed `path`. */
+export function feed(ctx: TemplateCtx, span: Span | undefined, path: string): void {
+  if (!span) return;
+  for (let i = span.from; i < span.to; i++) {
+    const splice = ctx.tokens[i]!.splice;
+    if (splice !== undefined) ctx.fed[splice]!.add(path);
+  }
+}
+
+/**
+ * Splice every interpolation that is not a reference into the token list as
+ * SQL text. References stay `ref` tokens for the parser and the entity to see.
+ */
+export function splice(d: TemplateDialect, tag: string, parts: readonly string[], values: readonly unknown[]): Token[] {
+  const out: Token[] = [];
+  for (const t of tokenize(parts, d.lexical)) {
+    if (t.kind !== "ref") {
+      out.push(t);
+      continue;
+    }
+    const value = values[t.part];
+    if (d.isObject(value) || d.isColumnRef(value)) {
+      out.push(t);
+      continue;
+    }
+    const text = spliceText(value);
+    if (typeof text !== "string") {
+      throw new SqlTemplateError(
+        tag,
+        `the interpolation on template line ${interpolationLine(parts, t.part)} is ${text.error}`,
+        t.part,
+        parts[t.part]!.length,
+      );
+    }
+    try {
+      for (const s of tokenizeText(text, t.part, d.lexical)) out.push({ ...s, splice: t.part });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new SqlTemplateError(
+        tag,
+        `the text interpolated on template line ${interpolationLine(parts, t.part)} does not tokenize: ${message}`,
+        t.part,
+        parts[t.part]!.length,
+      );
+    }
+  }
+  return out;
+}
+
+/** A span's text, interpolations rendered, trimmed. With `path`, the span's spliced text is recorded as feeding it. */
+export function spanText(ctx: TemplateCtx, span: Span | undefined, path?: string): string | undefined {
+  if (!span || span.to <= span.from) return undefined;
+  if (path) feed(ctx, span, path);
+  return untokenize(ctx.tokens.slice(span.from, span.to), (i) => ctx.d.renderReference(ctx.values[i], i)).trim();
+}
+
+/** A parse error as the tag reports it: on the template line, or in the interpolated text it came from. */
+export function templateSyntaxError(tag: string, parts: readonly string[], err: SqlSyntaxError): SqlTemplateError {
+  const where =
+    err.token?.splice !== undefined
+      ? `in the text interpolated on template line ${interpolationLine(parts, err.token.splice)}`
+      : `on template line ${parts.slice(0, err.part).join("${}").split("\n").length + parts[err.part]!.slice(0, err.offset).split("\n").length - 1}`;
+  return new SqlTemplateError(tag, `${err.message} (${where})`, err.part, err.offset);
+}
+
+/**
+ * Column-level lineage of a view's SELECT: one edge per item of the top-level
+ * select list. FROM, WHERE and GROUP BY stay text; the objects they
+ * interpolate land in `reads`. A column written by name inside the SQL is not
+ * lineage: only references are (#3047, "no parsing of SQL for names").
+ */
+export function lineage<O extends SqlObject>(ctx: TemplateCtx, select: Span): { edges: LineageEdge[]; reads: O[] } {
+  const { d } = ctx;
+  const sig: number[] = [];
+  for (let i = select.from; i < select.to; i++) if (!isTrivia(ctx.tokens[i]!)) sig.push(i);
+  const tok = (i: number) => ctx.tokens[i]!;
+  const isKw = (i: number, w: string) => tok(i).kind === "ident" && tok(i).text.toUpperCase() === w;
+  let depth = 0;
+  let selectAt = -1;
+  let fromAt = sig.length;
+  const commas: number[] = [];
+  for (let k = 0; k < sig.length; k++) {
+    const t = tok(sig[k]!);
+    if (t.kind === "punct" && t.text === "(") depth++;
+    else if (t.kind === "punct" && t.text === ")") depth--;
+    else if (depth === 0 && selectAt < 0 && isKw(sig[k]!, "SELECT")) {
+      selectAt = k;
+      if (sig[k + 1] !== undefined && isKw(sig[k + 1]!, "DISTINCT")) {
+        selectAt = k + 1;
+        // `DISTINCT ON (a, b)`: the parenthesized list is not a select-list item.
+        if (d.lineage?.distinctOn && sig[k + 2] !== undefined && isKw(sig[k + 2]!, "ON") && tok(sig[k + 3] ?? -1)?.text === "(") {
+          let nest = 0;
+          let j = k + 3;
+          for (; j < sig.length; j++) {
+            const x = tok(sig[j]!);
+            if (x.kind === "punct" && x.text === "(") nest++;
+            else if (x.kind === "punct" && x.text === ")" && --nest === 0) break;
+          }
+          selectAt = j;
+          k = j;
+        }
+      } else if (sig[k + 1] !== undefined && d.lineage?.distinctOn && isKw(sig[k + 1]!, "ALL")) selectAt = k + 1;
+    } else if (depth === 0 && selectAt >= 0 && fromAt === sig.length && isKw(sig[k]!, "FROM")) fromAt = k;
+    else if (depth === 0 && selectAt >= 0 && fromAt === sig.length && t.kind === "punct" && t.text === ",") commas.push(k);
+  }
+  const edges: LineageEdge[] = [];
+  if (selectAt >= 0) {
+    const bounds = [selectAt, ...commas, fromAt];
+    for (let b = 0; b + 1 < bounds.length; b++) {
+      const items = sig.slice(bounds[b]! + 1, bounds[b + 1]);
+      if (items.length === 0) continue;
+      let output: string | undefined;
+      let exprItems = items;
+      const asAt = items.findIndex((i) => isKw(i, "AS"));
+      if (asAt >= 0 && asAt === items.length - 2) {
+        output = d.identValue(tok(items[asAt + 1]!).text);
+        exprItems = items.slice(0, asAt);
+      } else if (items.length === 1) {
+        const t = tok(items[0]!);
+        if (t.kind === "ref" && d.isColumnRef(ctx.values[t.part])) output = (ctx.values[t.part] as AttrRef).attribute;
+        else if (t.kind === "ident" || t.kind === "qident") output = d.identValue(t.text);
+      } else if (items.length === 3 && tok(items[1]!).text === "." && (tok(items[2]!).kind === "ident" || tok(items[2]!).kind === "qident")) {
+        output = d.identValue(tok(items[2]!).text);
+      } else if (d.lineage?.qualifiedRefs && items.length === 3 && tok(items[1]!).text === "." && tok(items[2]!).kind === "ref" && d.isColumnRef(ctx.values[tok(items[2]!).part])) {
+        // `alias.${t.columns.c}` names its output after the column.
+        output = (ctx.values[tok(items[2]!).part] as AttrRef).attribute;
+      } else if (d.lineage?.aliasWithoutAs && items.length >= 2) {
+        // `expr name`: an alias without AS. The name follows an operand, never an operator or `.`.
+        const last = tok(items[items.length - 1]!);
+        const before = tok(items[items.length - 2]!);
+        const keyword = (t: Token) => (t.kind === "ident" ? d.lineage?.keyword?.(t) : undefined);
+        const operandEnd =
+          before.kind === "ref" || before.kind === "string" || before.kind === "number" || before.kind === "qident" || before.kind === "param" ||
+          (before.kind === "ident" && keyword(before) === undefined) ||
+          (before.kind === "punct" && (before.text === ")" || before.text === "]"));
+        const label = last.kind === "qident" || (last.kind === "ident" && keyword(last) !== "reserved");
+        if (label && operandEnd) {
+          output = d.identValue(last.text);
+          exprItems = items.slice(0, -1);
+        }
+      }
+      if (output === undefined && d.lineage?.outputOf) output = d.lineage.outputOf(exprItems.map(tok), (t) => (t.kind === "ref" ? ctx.values[t.part] : undefined));
+      const refs = exprItems.filter((i) => tok(i).kind === "ref").map((i) => tok(i).part);
+      const exprSpan: Span = { from: exprItems[0]!, to: exprItems[exprItems.length - 1]! + 1, refs };
+      edges.push({
+        output: output ?? d.unnamedOutput(b + 1),
+        expr: spanText(ctx, exprSpan) ?? "",
+        from: [...new Set(refs.map((i) => ctx.values[i]).filter((v): v is AttrRef => d.isColumnRef(v)))],
+      });
+    }
+  }
+  const reads = [...new Set(select.refs.map((i) => ctx.values[i]).filter((v): v is O => d.isObject(v)))];
+  return { edges, reads };
+}
+

package/src/core/normalize.ts

@@ -0,0 +1,39 @@
+/**
+ * Normalization helpers that hold in every dialect. A dialect's normalization
+ * undoes what its own server rewrites (quoting, type aliases, default
+ * levels), by rule over its own parse; these are the pieces that are not any
+ * one database's grammar.
+ */
+
+/**
+ * The name in a `-- previously: <name>` comment, when the text holds one: the
+ * rename hint, before a `CREATE` for an object or on a column's line for a
+ * column. The name may be quoted with backquotes or double quotes.
+ */
+export function previouslyIn(comments: readonly string[]): string | undefined {
+  for (const c of comments) {
+    const m = /^--\s*previously\s*:\s*([`"]?)([^\s`"]+)\1\s*$/i.exec(c.trim());
+    if (m) return m[2];
+  }
+  return undefined;
+}
+
+/**
+ * Split canonical text (tokens joined by single spaces) on its top-level
+ * commas, outside parentheses and brackets.
+ */
+export function splitTopLevel(text: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let cur: string[] = [];
+  for (const tok of text.split(" ")) {
+    if (tok === "(" || tok === "[") depth++;
+    if (tok === ")" || tok === "]") depth--;
+    if (tok === "," && depth === 0) {
+      parts.push(cur.join(" "));
+      cur = [];
+    } else cur.push(tok);
+  }
+  if (cur.length) parts.push(cur.join(" "));
+  return parts.filter((p) => p.length > 0);
+}

package/src/core/ownership.test.ts

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "vitest";
+import { carriesMarker, hasChantTrailerKey, isChantManaged, markerTrailer, readMarker, readTrailerPairs, stampedComment, stripMarker } from "./ownership";
+
+describe("the comment trailer (#3208)", () => {
+  test("is appended to the declared comment, never in place of it", () => {
+    expect(stampedComment("Raw events", { stack: "shop", env: "prod" })).toBe("Raw events [chant managed-by=chant stack=shop env=prod]");
+    expect(stampedComment(undefined, undefined)).toBe("[chant managed-by=chant]");
+    expect(stampedComment("Raw events [chant managed-by=chant stack=old]", { stack: "shop" })).toBe("Raw events [chant managed-by=chant stack=shop]");
+  });
+
+  test("reads back, and strips to the declared comment", () => {
+    const c = stampedComment("a [b] c", { stack: "my shop", env: "prod]" });
+    expect(readMarker(c)).toEqual({ managedBy: "chant", stack: "my shop", env: "prod]" });
+    expect(stripMarker(c)).toBe("a [b] c");
+    expect(isChantManaged(c)).toBe(true);
+    expect(isChantManaged("a [b] c")).toBe(false);
+    expect(markerTrailer({ stack: "it's" })).not.toContain("'");
+  });
+
+  test("matches this project's stack and env exactly", () => {
+    const c = stampedComment("", { stack: "shop", env: "prod" });
+    expect(carriesMarker(c, { stack: "shop", env: "prod" })).toBe(true);
+    expect(carriesMarker(c, { stack: "shop" })).toBe(false);
+    expect(carriesMarker(c, { stack: "other", env: "prod" })).toBe(false);
+    expect(carriesMarker("Raw events", { stack: "shop", env: "prod" })).toBe(false);
+  });
+
+  test("carries extra pairs, encoded, after the marker's own", () => {
+    const c = stampedComment("x", { stack: "s" }, { migration: "public.users", role: "new" });
+    expect(c).toBe("x [chant managed-by=chant stack=s migration=public.users role=new]");
+    expect(readTrailerPairs(c)?.get("migration")).toBe("public.users");
+    expect(hasChantTrailerKey(c, ["migration"])).toBe(true);
+    expect(hasChantTrailerKey(c, ["receipts"])).toBe(false);
+    expect(() => markerTrailer(undefined, { "bad key": "v" })).toThrow(/not \[A-Za-z0-9._-\]\+/);
+  });
+});