quixos-protocol/src/capability-language/structural-edits.ts

import { CharStream, CommonTokenStream } from "antlr4ng";
import { QuixosLockLexer } from "../resource-lock/generated/QuixosLockLexer.js";
import { QuixosLockParser } from "../resource-lock/generated/QuixosLockParser.js";
import { parseQuixosLockDocument } from "../resource-lock/parser.js";
import { parseQx, walkSyntax, applySourceEdits, type SyntaxNode } from "./source.js";

export type StructuralSelector = { kind: string; id?: string; name?: string; names?: string[] };
export type StructuralEdit =
  | { operation: "append"; parent: StructuralSelector; source: string }
  | { operation: "replace"; target: StructuralSelector; source: string }
  | { operation: "remove"; target: StructuralSelector }
  | { operation: "import"; kind: "interface" | "package"; name: string }
  | { operation: "semantic-major"; target: StructuralSelector; major: number }
  | { operation: "conformance-id"; target: StructuralSelector; id: string }
  | { operation: "quixos-pin"; source: { repository: string; commit: string } }
  | {
      operation: "dependency";
      kind: "interface" | "package";
      name: string;
      source: { repository: string; commit: string } | null;
    };

// Deliberately exclude valueType/identifier/stringLiteral: callers operate on
// declaration structure, not arbitrary token offsets or lockfile text patches.
const selectable = new Set([
  "workspaceDecl",
  "fragmentDecl",
  "interfaceResourceDecl",
  "packageResourceDecl",
  "atomDecl",
  "valueMember",
  "relationshipMember",
  "operationMember",
  "packageOperationExport",
  "packageFunctionExport",
  "packageConstructorExport",
  "conformanceDecl",
  "stateDecl",
  "edgeDecl",
  "constructorBindingDecl",
  "resourceImportDecl",
  "sourceImportDecl",
  "operationBindingDecl",
]);

/** Bind only the template root identity; schema/atom identities are reusable.
 * The revision's real identity is derived from its containing commit at compile time. */
export const instantiateWorkspaceIdentity = (source: string, workspaceId: string): string => {
  if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(workspaceId))
    throw new Error("Workspace identity must be a UUID");
  const syntax = parseQx(source);
  if (syntax.diagnostics.length) throw new Error("Cannot instantiate a malformed template workspace");
  const declaration = syntax.root.children.find((node) => node.kind === "workspaceDecl");
  const literals = declaration?.children.filter((node) => node.kind === "stringLiteral");
  if (!literals || literals.length !== 3) throw new Error("Template must contain a workspace declaration");
  return applySourceEdits(source, [
    { ...literals[0], text: JSON.stringify(workspaceId) },
    { ...literals[1], text: JSON.stringify(`workspace-revision:${workspaceId}:source`) },
  ]);
};

const select = (
  source: string,
  selector: StructuralSelector,
): { node: SyntaxNode; syntax: ReturnType<typeof parseQx> } => {
  if (!selectable.has(selector.kind)) throw new Error(`Unsupported structural selector ${selector.kind}`);
  const syntax = parseQx(source);
  if (syntax.diagnostics.length) throw new Error("Cannot scaffold syntactically invalid QX");
  const matches = [...walkSyntax(syntax.root)].filter((node) => {
    if (node.kind !== selector.kind) return false;
    if (
      selector.name &&
      !node.children.some(
        (child) => child.kind === "identifier" && source.slice(child.start, child.end) === selector.name,
      )
    )
      return false;
    if (
      selector.names &&
      JSON.stringify(
        node.children
          .filter((child) => child.kind === "identifier")
          .map((child) => source.slice(child.start, child.end)),
      ) !== JSON.stringify(selector.names)
    )
      return false;
    if (selector.id) {
      // Only an explicit ID field counts, not a coincidentally equal revision,
      // default value, nested declaration, or comment.
      const tokens = syntax.tokens.filter(
        (token) => !token.trivia && token.start >= node.start && token.end <= node.end,
      );
      const literal = node.children.find(
        (child) =>
          child.kind === "stringLiteral" &&
          tokens.some((token, index) => token.start === child.start && tokens[index - 1]?.kind === "ID"),
      );
      if (!literal || JSON.parse(source.slice(literal.start, literal.end)) !== selector.id) return false;
    }
    return true;
  });
  if (matches.length !== 1) throw new Error(`Structural selector must resolve exactly once (found ${matches.length})`);
  return { node: matches[0], syntax };
};

/** Comment-preserving structural edits; every result is parsed before returning. */
export const editStructure = (source: string, edit: StructuralEdit): string => {
  if (edit.operation === "quixos-pin") {
    const parsed = parseQuixosLockDocument(source);
    if (!parsed.ok || parsed.document.kind !== "root") throw new Error("Quixos pins belong in a valid root lockfile");
    const parser = new QuixosLockParser(new CommonTokenStream(new QuixosLockLexer(CharStream.fromString(source))));
    const entries = parser.document().quixosEntry();
    if (entries.length !== 1) throw new Error("Expected one Quixos source declaration");
    const literals = entries[0].quixosSourceBlock().stringLiteral();
    const offsets = [0];
    for (const character of source) offsets.push(offsets[offsets.length - 1] + character.length);
    const result = applySourceEdits(source, [
      {
        start: offsets[literals[0].start!.start],
        end: offsets[literals[0].stop!.stop + 1],
        text: JSON.stringify(edit.source.repository),
      },
      {
        start: offsets[literals[literals.length - 1].start!.start],
        end: offsets[literals[literals.length - 1].stop!.stop + 1],
        text: JSON.stringify(edit.source.commit),
      },
    ]);
    const checked = parseQuixosLockDocument(result);
    if (!checked.ok)
      throw new Error(`Invalid Quixos pin: ${checked.diagnostics.map((entry) => entry.message).join("; ")}`);
    return result;
  }
  if (edit.operation === "import") {
    if (!["interface", "package"].includes(edit.kind) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(edit.name))
      throw new Error("Invalid resource import");
    const syntax = parseQx(source);
    if (syntax.diagnostics.length) throw new Error("Cannot scaffold invalid QX");
    const text = `import ${edit.kind} ${edit.name};`;
    if (
      [...walkSyntax(syntax.root)].some(
        (entry) =>
          entry.kind === "resourceImportDecl" && source.slice(entry.start, entry.end).replace(/\s+/g, " ") === text,
      )
    )
      return source;
    const root = syntax.root.children[0];
    const position = ["workspaceDecl", "fragmentDecl"].includes(root.kind)
      ? syntax.tokens.find((token) => token.kind === "LBRACE")!.end
      : root.start;
    const result = applySourceEdits(source, [{ start: position, end: position, text: `\n${text}\n` }]);
    if (parseQx(result).diagnostics.length) throw new Error("Invalid resource import position");
    return result;
  }
  if (edit.operation === "dependency") {
    const parsed = parseQuixosLockDocument(source);
    if (!parsed.ok) throw new Error("Cannot scaffold an invalid lockfile");
    if (!["interface", "package"].includes(edit.kind) || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(edit.name))
      throw new Error("Invalid dependency selector");
    const parser = new QuixosLockParser(new CommonTokenStream(new QuixosLockLexer(CharStream.fromString(source))));
    const tree = parser.document();
    const offsets = [0];
    for (const character of source) offsets.push(offsets[offsets.length - 1] + character.length);
    const entries = tree
      .resourceEntry()
      .filter((entry) => entry.resourceKind().getText() === edit.kind && entry.identifier().getText() === edit.name);
    if (entries.length > 1) throw new Error("Ambiguous dependency selector");
    const entry = entries[0];
    const replacement = edit.source
      ? `${edit.kind} ${edit.name} source {\n  repository ${JSON.stringify(edit.source.repository)};\n  commit ${JSON.stringify(edit.source.commit)};\n}`
      : "";
    if (!entry && !edit.source) throw new Error("Cannot remove an absent dependency");
    const start = entry ? offsets[entry.start!.start] : offsets[tree.RBRACE().symbol.start];
    const end = entry ? offsets[entry.stop!.stop + 1] : start;
    const result = applySourceEdits(source, [{ start, end, text: entry ? replacement : `${replacement}\n` }]);
    const checked = parseQuixosLockDocument(result);
    if (!checked.ok)
      throw new Error(`Invalid dependency change: ${checked.diagnostics.map((entry) => entry.message).join("; ")}`);
    return result;
  }
  const { node, syntax } = select(source, edit.operation === "append" ? edit.parent : edit.target);
  let result: string;
  if (edit.operation === "semantic-major") {
    if (
      !["conformanceDecl", "packageResourceDecl"].includes(node.kind) ||
      !Number.isSafeInteger(edit.major) ||
      edit.major < 1
    )
      throw new Error("Semantic major requires a package/conformance and positive integer");
    const tokens = syntax.tokens.filter((token) => !token.trivia && token.start >= node.start && token.end <= node.end);
    const marker = tokens.findIndex((token) => token.kind === "SEMANTIC_MAJOR");
    const value = marker < 0 ? undefined : tokens[marker + 1];
    const brace = tokens.find((token) => token.kind === "LBRACE")!;
    result = applySourceEdits(source, [
      {
        start: value?.start ?? brace.start,
        end: value?.end ?? brace.start,
        text: value ? String(edit.major) : `semantic-major ${edit.major} `,
      },
    ]);
  } else if (edit.operation === "conformance-id") {
    if (node.kind !== "conformanceDecl" || !edit.id)
      throw new Error("Identity enrollment requires a conformance and stable ID");
    const existing = node.children.find((entry) => entry.kind === "stringLiteral");
    if (existing) {
      if (JSON.parse(source.slice(existing.start, existing.end)) !== edit.id)
        throw new Error("Cannot change an enrolled conformance identity; create a new conformance explicitly");
      return source;
    }
    const identifiers = node.children.filter((entry) => entry.kind === "identifier");
    const position = identifiers[identifiers.length - 1].end;
    result = applySourceEdits(source, [{ start: position, end: position, text: ` id ${JSON.stringify(edit.id)}` }]);
  } else if (edit.operation === "append") {
    const closing = syntax.tokens.find((token) => token.kind === "RBRACE" && token.end === node.end);
    if (!closing) throw new Error("Append requires a declaration with a body");
    result = applySourceEdits(source, [{ start: closing.start, end: closing.start, text: `\n${edit.source}\n` }]);
  } else {
    // A resource parser node includes imports/external declarations preceding
    // its header. Replacing the declaration must not delete that preamble.
    const identifier = node.children.find((child) => child.kind === "identifier");
    const header =
      ["packageResourceDecl", "interfaceResourceDecl"].includes(node.kind) && identifier
        ? syntax.tokens
            .filter(
              (token) =>
                token.start >= node.start &&
                token.end <= identifier.start &&
                token.kind === (node.kind === "packageResourceDecl" ? "PACKAGE" : "INTERFACE"),
            )
            .at(-1)?.start
        : undefined;
    const wrapper =
      edit.operation === "remove" && ["stateDecl", "edgeDecl"].includes(node.kind)
        ? [...walkSyntax(syntax.root)]
            .filter(
              (entry) =>
                ["conformanceItem", "sharedAttachmentDecl"].includes(entry.kind) &&
                entry.start <= node.start &&
                entry.end >= node.end,
            )
            .sort((a, b) => a.end - a.start - (b.end - b.start))[0]
        : undefined;
    result = applySourceEdits(source, [
      {
        start: wrapper?.start ?? header ?? node.start,
        end: wrapper?.end ?? node.end,
        text: edit.operation === "replace" ? edit.source : "",
      },
    ]);
  }
  const checked = parseQx(result);
  if (checked.diagnostics.length)
    throw new Error(`Invalid structural change: ${checked.diagnostics.map((entry) => entry.message).join("; ")}`);
  return result;
};

export const scaffoldResourceSource = (kind: "interface" | "package", name: string, id: string, revision: string) => {
  if (!/^[A-Z][A-Za-z0-9]*$/.test(name) || !id || !revision)
    throw new Error("Resource scaffold requires a PascalCase name and explicit identities");
  const source = `${kind} ${name} id ${JSON.stringify(id)} revision ${JSON.stringify(revision)} {\n}\n`;
  if (parseQx(source).diagnostics.length) throw new Error("Invalid resource scaffold");
  return source;
};