@cassiomc1/forgeloop 1.12.0 → 1.14.0

package/src/core/test-intelligence/utility.js

@@ -0,0 +1,50 @@
+import { canonicalFingerprint } from "../artifacts.js";
+
+function classify(test, judgment = null, confidence = 1) {
+  const signal = test.signals ?? {};
+  if (signal.requiredBehavior) return { classification: "KEEP_REQUIRED", recommendation: "KEEP", protected: true };
+  if (signal.security) return { classification: "KEEP_RISK_GUARD", recommendation: "KEEP", protected: true };
+  if (signal.criticalPath) return { classification: "KEEP_RECOVERY_INVARIANT", recommendation: "KEEP", protected: true };
+  if (signal.migration) return { classification: "KEEP_MIGRATION_COMPATIBILITY", recommendation: "KEEP", protected: true };
+  if (signal.publicApi) return { classification: "KEEP_UNIQUE", recommendation: "KEEP", protected: true };
+  if (signal.release) return { classification: "KEEP_RELEASE_SMOKE", recommendation: "KEEP", protected: true };
+  if (signal.platformSpecific) return { classification: "KEEP_PLATFORM_BEHAVIOR", recommendation: "KEEP", protected: true };
+  if (signal.integration) return { classification: "KEEP_INTEGRATION_GUARD", recommendation: "KEEP", protected: true };
+  if (!judgment || confidence < 0.75) return { classification: "UNKNOWN", recommendation: "BLOCKED", protected: false };
+  if (judgment.protocol_invariant) return { classification: "KEEP_RECOVERY_INVARIANT", recommendation: "KEEP", protected: true };
+  if (judgment.semantic_duplicate) {
+    return {
+      classification: "REDUNDANT_CANDIDATE",
+      recommendation: judgment.requires_system_two_review ? "BLOCKED" : "PROBE_REMOVAL",
+      protected: false,
+    };
+  }
+  if (judgment.likely_obsolete) return { classification: "OBSOLETE_CANDIDATE", recommendation: "BLOCKED", protected: false };
+  if (judgment.likely_flaky_low_signal) return { classification: "FLAKY_LOW_SIGNAL", recommendation: "BLOCKED", protected: false };
+  if (judgment.expensive_relative_to_signal) return { classification: "EXPENSIVE_LOW_SIGNAL", recommendation: "BLOCKED", protected: false };
+  if (judgment.documentation_value) return { classification: "KEEP_DOCUMENTATION_VALUE", recommendation: "KEEP", protected: false };
+  if (judgment.integration_value) return { classification: "KEEP_INTEGRATION_GUARD", recommendation: "KEEP", protected: true };
+  if (judgment.has_unique_semantic_intent) return { classification: "KEEP_UNIQUE", recommendation: "KEEP", protected: false };
+  return { classification: "UNKNOWN", recommendation: "BLOCKED", protected: false };
+}
+
+export function buildTestUtilityArtifact({ taskId, inventory, semanticStatus = "NOT_REQUESTED", semanticDecision = null, semanticDecisions = [] } = {}) {
+  const decisions = semanticDecisions.length > 0 ? semanticDecisions : (semanticDecision ? [semanticDecision] : []);
+  const byTest = new Map(decisions.flatMap((decision) => Object.entries(decision.decision?.tests ?? {}).map(([testId, judgment]) => [testId, {
+    judgment, confidence: Math.min(...Object.keys(judgment).map((key) => decision.confidence?.[`test_${(decision.decision.candidateIds ?? []).indexOf(testId)}_${key}`] ?? 0)),
+  }])));
+  return {
+    schemaVersion: 1,
+    protocolVersion: 1,
+    taskId,
+    generatedAt: new Date().toISOString(),
+    inventoryFingerprint: canonicalFingerprint(inventory),
+    semanticStatus: decisions.length > 0 ? "PROVIDER_REPORTED" : semanticStatus,
+    ...(decisions.length > 0 ? {
+      ...(decisions.length === 1 ? { decisionId: decisions[0].decisionId, semanticDecisionFingerprint: canonicalFingerprint(decisions[0]) } : {}),
+      decisionIds: decisions.map((decision) => decision.decisionId),
+      semanticDecisionFingerprints: decisions.map((decision) => canonicalFingerprint(decision)),
+    } : {}),
+    tests: (inventory?.tests ?? []).map((test) => ({ ...test, ...classify(test, byTest.get(test.testId)?.judgment, byTest.get(test.testId)?.confidence ?? 0) })),
+  };
+}

package/src/core/trace.js

@@ -51,6 +51,7 @@ const EVENT_CATEGORY_MAP = Object.freeze({
   TASK_RECOVERY_RECORDED: "recovery",
   TASK_RECOVERY_RESUMED: "recovery",
   OPERATOR_RECOVERY_RECORDED: "recovery",
+  TASK_ABANDONED: "recovery",
   LEGACY_RECOVERY_MIGRATION_RECORDED: "recovery",
   GATE_SATISFIED: "policy",
   COMPLETION_VALIDATED: "completion",
@@ -82,6 +83,13 @@ const LIFECYCLE_TRANSITIONS = Object.freeze([
   "COMPLETION_REJECTED",
 ]);
 
+const STATIC_EVENT_SUMMARIES = Object.freeze({
+  TASK_RECOVERY_RESUMED: "Task resumed after recovery",
+  OPERATOR_RECOVERY_RECORDED: "Operator recovery recorded",
+  TASK_ABANDONED: "Task explicitly abandoned",
+  LEGACY_RECOVERY_MIGRATION_RECORDED: "Legacy recovery migration recorded",
+});
+
 export function eventCategory(eventType) {
   return EVENT_CATEGORY_MAP[eventType] ?? "integrity";
 }
@@ -93,6 +101,8 @@ export function timestampQuality(event) {
 
 function eventSummary(event) {
   const d = event.details ?? {};
+  const staticSummary = STATIC_EVENT_SUMMARIES[event.event];
+  if (staticSummary) return staticSummary;
   switch (event.event) {
     case "TASK_RECEIVED":
       return `Task received${d.taskId ? ` (${d.taskId})` : ""}`;
@@ -132,12 +142,6 @@ function eventSummary(event) {
       return "Continuity checkpoint recorded";
     case "TASK_RECOVERY_RECORDED":
       return `Task recovery recorded (${d.classification ?? "unknown"})`;
-    case "TASK_RECOVERY_RESUMED":
-      return "Task resumed after recovery";
-    case "OPERATOR_RECOVERY_RECORDED":
-      return "Operator recovery recorded";
-    case "LEGACY_RECOVERY_MIGRATION_RECORDED":
-      return "Legacy recovery migration recorded";
     case "COMPLETION_VALIDATED":
       return "Completion validated";
     case "COMPLETION_REJECTED":
@@ -451,7 +455,7 @@ export async function buildTaskTrace({ target, packageRoot, taskId = null, event
   const evidence = [...evidenceSources.values()].sort((a, b) => a.ref.localeCompare(b.ref));
 
   const recovery = taskEvents
-    .filter((event) => ["TASK_RECOVERY_RECORDED", "TASK_RECOVERY_RESUMED", "OPERATOR_RECOVERY_RECORDED", "LEGACY_RECOVERY_MIGRATION_RECORDED"].includes(event.event))
+    .filter((event) => ["TASK_RECOVERY_RECORDED", "TASK_RECOVERY_RESUMED", "OPERATOR_RECOVERY_RECORDED", "TASK_ABANDONED", "LEGACY_RECOVERY_MIGRATION_RECORDED"].includes(event.event))
     .map((event) => ({ sequence: event.seq, at: event.at, type: event.event, details: event.details ?? {} }));
 
   const completionEvents = taskEvents.filter((event) => ["COMPLETION_VALIDATED", "COMPLETION_REJECTED"].includes(event.event));

package/src/core/transaction.js

@@ -142,6 +142,7 @@ export async function withTaskTransaction({
       target,
       transactionId,
       taskId,
+      operation,
       lock,
       async readText(relativePath) {
         await assertSafePath(target, relativePath);

package/src/core/typescript-project.js

@@ -0,0 +1,349 @@
+import path from "node:path";
+
+import { createLanguageProject } from "./multi-language-project.js";
+
+const TS_CONFIG_NAME = /^tsconfig(?:\.[^/]+)?\.json$/u;
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function invalidConfig() {
+  return {
+    valid: false,
+    references: [],
+    extends: [],
+    compilerOptions: {},
+  };
+}
+
+function maskJsonComments(text) {
+  let result = "";
+  let state = "code";
+  let escaped = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    const next = text[index + 1];
+    if (state === "string") {
+      result += character;
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') state = "code";
+    } else if (state === "line-comment") {
+      if (character === "\n") {
+        result += character;
+        state = "code";
+      } else result += " ";
+    } else if (state === "block-comment") {
+      if (character === "*" && next === "/") {
+        result += "  ";
+        index += 1;
+        state = "code";
+      } else result += character === "\n" ? "\n" : " ";
+    } else if (character === '"') {
+      result += character;
+      state = "string";
+    } else if (character === "/" && next === "/") {
+      result += "  ";
+      index += 1;
+      state = "line-comment";
+    } else if (character === "/" && next === "*") {
+      result += "  ";
+      index += 1;
+      state = "block-comment";
+    } else result += character;
+  }
+  return state === "block-comment" ? null : result;
+}
+
+function removeTrailingCommas(text) {
+  let result = "";
+  let state = "code";
+  let escaped = false;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (state === "string") {
+      result += character;
+      if (escaped) escaped = false;
+      else if (character === "\\") escaped = true;
+      else if (character === '"') state = "code";
+      continue;
+    }
+    if (character === '"') {
+      result += character;
+      state = "string";
+    } else if (character === "," && /^[\s]*[}\]]/u.test(text.slice(index + 1))) {
+      continue;
+    } else result += character;
+  }
+  return result;
+}
+
+export function isTypeScriptConfigName(fileName) {
+  return typeof fileName === "string" && TS_CONFIG_NAME.test(fileName.toLowerCase());
+}
+
+function normalizedReferencePath(projectRoot, reference) {
+  return path.posix.normalize(path.posix.join(projectRoot, reference.replaceAll("\\", "/")));
+}
+
+function referenceMatchesConfig(projectRoot, reference, configRelative, allowBareReference = false) {
+  if (typeof reference !== "string" || reference.trim() === "") return false;
+  const normalizedReference = reference.replaceAll("\\", "/");
+  if ((!allowBareReference && !normalizedReference.startsWith("."))
+    || normalizedReference.startsWith("/")
+    || /^[A-Za-z]:\//u.test(normalizedReference)) return false;
+  const candidate = normalizedReferencePath(projectRoot, normalizedReference);
+  if (candidate === ".." || candidate.startsWith("../")) return false;
+  const normalizedConfig = configRelative.toLowerCase();
+  const normalizedCandidate = candidate.toLowerCase();
+  return normalizedConfig === normalizedCandidate
+    || normalizedConfig === normalizedCandidate + ".json"
+    || normalizedConfig === normalizedCandidate + "/tsconfig.json";
+}
+
+function isConfigCandidate(file) {
+  return file?.kind === "typescript" || file?.kind === "typescript-config";
+}
+
+function localConfigReferences(configRelative, projectFiles) {
+  return projectFiles.filter((file) => {
+    if (!isConfigCandidate(file)) return false;
+    const parsed = parseTypeScriptConfig(file.text, file.name);
+    return parsed.valid && (parsed.references
+      .some((reference) => referenceMatchesConfig(path.posix.dirname(file.relative), reference, configRelative, true))
+      || parsed.extends.some((reference) => referenceMatchesConfig(
+        path.posix.dirname(file.relative),
+        reference,
+        configRelative,
+      )));
+  });
+}
+
+function configRelationships(projectFiles) {
+  const entries = projectFiles
+    .filter(isConfigCandidate)
+    .map((file) => ({ file, parsed: parseTypeScriptConfig(file.text, file.name) }))
+    .filter(({ parsed }) => parsed.valid);
+  const forward = new Map();
+  const reverse = new Map();
+  for (const { file, parsed } of entries) {
+    const relations = [
+      ...parsed.references.map((value) => ({ value, kind: "reference", allowBare: true })),
+      ...parsed.extends.map((value) => ({ value, kind: "extends", allowBare: false })),
+    ];
+    for (const relation of relations) {
+      const target = entries.find(({ file: candidate }) => referenceMatchesConfig(
+        path.posix.dirname(file.relative), relation.value, candidate.relative, relation.allowBare,
+      ));
+      if (!target) continue;
+      const sourceRelative = file.relative.toLowerCase();
+      const targetRelative = target.file.relative.toLowerCase();
+      if (!forward.has(sourceRelative)) forward.set(sourceRelative, []);
+      if (!reverse.has(targetRelative)) reverse.set(targetRelative, []);
+      forward.get(sourceRelative).push({ relative: targetRelative, kind: relation.kind });
+      reverse.get(targetRelative).push({ relative: sourceRelative, kind: relation.kind });
+    }
+  }
+  return { entries, forward, reverse };
+}
+
+export function resolveTypeScriptConfigGraph(projectFiles = [], directClaims = []) {
+  const { entries, forward, reverse } = configRelationships(projectFiles);
+  const byRelative = new Map(entries.map((entry) => [entry.file.relative.toLowerCase(), entry]));
+  const active = new Set(entries
+    .filter(({ file }) => file.name.toLowerCase() === "tsconfig.json")
+    .map(({ file }) => file.relative.toLowerCase()));
+  for (const claim of directClaims) {
+    if (byRelative.has(claim.toLowerCase())) active.add(claim.toLowerCase());
+  }
+
+  const queue = [...active];
+  for (let index = 0; index < queue.length; index += 1) {
+    const current = byRelative.get(queue[index]);
+    const parsed = current?.parsed;
+    if (!parsed) continue;
+    for (const relation of forward.get(queue[index]) ?? []) {
+      if (!active.has(relation.relative)) {
+        active.add(relation.relative);
+        queue.push(relation.relative);
+      }
+    }
+    if (directClaims.length > 0) {
+      for (const relation of reverse.get(queue[index]) ?? []) {
+        if (!active.has(relation.relative)) {
+          active.add(relation.relative);
+          queue.push(relation.relative);
+        }
+      }
+    }
+  }
+  return active;
+}
+
+export function resolveTypeScriptConfigOwnershipRoots(projectFiles = [], activeConfigRelatives = new Set(), directClaims = []) {
+  const { entries, reverse } = configRelationships(projectFiles);
+  const candidates = entries.filter(({ file }) => activeConfigRelatives.has(file.relative.toLowerCase()));
+  const hasIndependentConfigSemantics = (parsed) => (parsed.compilerOptions
+    && Object.keys(parsed.compilerOptions).length > 0)
+    || parsed.references.length > 0
+    || parsed.extends.length > 0;
+  const roots = new Set(candidates
+    .filter(({ file, parsed }) => file.name.toLowerCase() === "tsconfig.json"
+      && (directClaims.length === 0 || hasIndependentConfigSemantics(parsed)))
+    .map(({ file }) => file.relative.toLowerCase()));
+  for (const claim of directClaims) {
+    const relative = claim.toLowerCase();
+    const consumers = (reverse.get(relative) ?? [])
+      .filter((relation) => relation.kind === "extends")
+      .map((relation) => relation.relative);
+    if (consumers.length === 0 && candidates.some(({ file }) => file.relative.toLowerCase() === relative)) {
+      roots.add(relative);
+    }
+    const queue = [...consumers];
+    const seen = new Set(queue);
+    for (let index = 0; index < queue.length; index += 1) {
+      const consumer = candidates.find(({ file }) => file.relative.toLowerCase() === queue[index]);
+      if (consumer?.file.name.toLowerCase() === "tsconfig.json") roots.add(queue[index]);
+      for (const relation of reverse.get(queue[index]) ?? []) {
+        if (relation.kind === "extends" && !seen.has(relation.relative)) {
+          seen.add(relation.relative);
+          queue.push(relation.relative);
+        }
+      }
+    }
+  }
+  for (const { file, parsed } of candidates) {
+    for (const reference of parsed.references) {
+      const target = candidates.find(({ file: candidate }) => referenceMatchesConfig(
+        path.posix.dirname(file.relative),
+        reference,
+        candidate.relative,
+        true,
+      ));
+      if (target) roots.add(target.file.relative.toLowerCase());
+    }
+  }
+  return roots;
+}
+
+export function shouldActivateTypeScriptConfig({
+  manifestName,
+  manifestRelative,
+  projectFiles = [],
+  directClaim = false,
+  configKind = "typescript",
+  activeConfigRelatives = null,
+  ownershipConfigRelatives = null,
+}) {
+  if (!isConfigCandidate({ kind: configKind }) || manifestName.toLowerCase() === "jsconfig.json") return false;
+  if (activeConfigRelatives) {
+    return activeConfigRelatives.has(manifestRelative.toLowerCase())
+      && (!ownershipConfigRelatives || ownershipConfigRelatives.has(manifestRelative.toLowerCase()));
+  }
+  if (manifestName.toLowerCase() === "tsconfig.json" || directClaim) return true;
+  return localConfigReferences(manifestRelative, projectFiles).length > 0;
+}
+
+export function parseJsonc(text) {
+  if (typeof text !== "string" || text.length > 1024 * 1024 || /\r(?!\n)/u.test(text)) return null;
+  try {
+    return JSON.parse(removeTrailingCommas(maskJsonComments(text)));
+  } catch {
+    return null;
+  }
+}
+
+export function parseTypeScriptConfig(text, fileName = "tsconfig.json") {
+  const value = parseJsonc(text);
+  if (!isPlainObject(value)) return invalidConfig();
+  const references = value.references === undefined
+    ? []
+    : Array.isArray(value.references) && value.references.every((reference) => isPlainObject(reference) && typeof reference.path === "string" && reference.path.trim() !== "")
+      ? value.references.map((reference) => reference.path)
+      : null;
+  const extendsValue = value.extends === undefined
+    ? []
+    : typeof value.extends === "string" && value.extends.trim() !== ""
+      ? [value.extends]
+      : Array.isArray(value.extends) && value.extends.every((reference) => typeof reference === "string" && reference.trim() !== "")
+        ? [...value.extends]
+        : undefined;
+  const compilerOptions = value.compilerOptions === undefined
+    ? {}
+    : isPlainObject(value.compilerOptions) ? value.compilerOptions : null;
+  if (references === null || extendsValue === undefined || compilerOptions === null) return invalidConfig();
+  for (const key of ["files", "include", "exclude"]) {
+    if (value[key] !== undefined && (!Array.isArray(value[key])
+      || value[key].some((entry) => typeof entry !== "string" || entry.trim() === ""))) return invalidConfig();
+  }
+  return {
+    valid: true,
+    references,
+    extends: extendsValue,
+    compilerOptions,
+    fileName,
+  };
+}
+
+export function inspectTypeScriptProject({
+  projectRoot,
+  manifestRelative,
+  manifestText,
+  manifestName,
+  targetRoot,
+  projectFiles,
+  directClaim = false,
+  configKind = "typescript",
+  activeConfigRelatives = null,
+  ownershipConfigRelatives = null,
+}) {
+  const parsed = parseTypeScriptConfig(manifestText, manifestName);
+  const isConfig = shouldActivateTypeScriptConfig({
+    manifestName,
+    manifestRelative,
+    projectFiles,
+    directClaim,
+    configKind,
+    activeConfigRelatives,
+    ownershipConfigRelatives,
+  });
+  const primary = parsed.valid && isConfig;
+  const primarySignals = primary ? [`${manifestRelative}:tsconfig`] : [];
+  const supportingSignals = [];
+  for (const reference of parsed.references) supportingSignals.push(`${manifestRelative}:reference=${reference}`);
+  for (const reference of parsed.extends) supportingSignals.push(`${manifestRelative}:extends=${reference}`);
+  const localReferences = parsed.references.filter((reference) => {
+    return projectFiles.some((file) => referenceMatchesConfig(
+      projectRoot,
+      reference,
+      path.posix.normalize(file.relative ?? ""),
+      true,
+    ));
+  });
+  const localExtends = parsed.extends.flatMap((reference) => projectFiles
+    .filter((file) => referenceMatchesConfig(path.posix.dirname(manifestRelative), reference, file.relative))
+    .map((file) => file.relative.toLowerCase()));
+  for (const reference of localReferences) supportingSignals.push(`${manifestRelative}:local-reference=${reference}`);
+  for (const reference of parsed.extends) {
+    if (projectFiles.some((file) => referenceMatchesConfig(
+      path.posix.dirname(manifestRelative),
+      reference,
+      file.relative,
+    ))) supportingSignals.push(`${manifestRelative}:local-extends=${reference}`);
+  }
+  return createLanguageProject({
+    kind: "typescript",
+    root: projectRoot,
+    manifest: manifestRelative,
+    frameworks: primary ? ["typescript"] : [],
+    primary,
+    primarySignals,
+    supportingSignals,
+    internal: { ...parsed, valid: parsed.valid, localReferences, localExtends },
+  });
+}
+
+export function isDeclarationFile(fileName) {
+  return typeof fileName === "string" && /\.d\.(?:ts|mts|cts)$/iu.test(fileName);
+}

package/src/core/xml-structure.js

@@ -0,0 +1,123 @@
+const DEFAULT_XML_MAX_BYTES = 1024 * 1024;
+
+function findTagEnd(text, start) {
+  let quote = null;
+  for (let index = start; index < text.length; index += 1) {
+    const character = text[index];
+    if (quote) {
+      if (character === quote) quote = null;
+    } else if (character === "\"" || character === "'") {
+      quote = character;
+    } else if (character === ">") {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function parseAttributes(text) {
+  const attributes = {};
+  let index = 0;
+  while (index < text.length) {
+    while (index < text.length && /\s/u.test(text[index])) index += 1;
+    if (index >= text.length) break;
+    const name = text.slice(index).match(/^[A-Za-z_][A-Za-z0-9_.:-]*/u)?.[0];
+    if (!name) return null;
+    index += name.length;
+    while (index < text.length && /\s/u.test(text[index])) index += 1;
+    if (text[index] !== "=") return null;
+    index += 1;
+    while (index < text.length && /\s/u.test(text[index])) index += 1;
+    const quote = text[index];
+    if (quote !== "\"" && quote !== "'") return null;
+    index += 1;
+    const end = text.indexOf(quote, index);
+    if (end < 0 || Object.prototype.hasOwnProperty.call(attributes, name)) return null;
+    attributes[name] = text.slice(index, end);
+    index = end + 1;
+  }
+  return attributes;
+}
+
+function appendText(stack, value) {
+  if (value === "") return true;
+  const current = stack[stack.length - 1];
+  if (!current) return value.trim() === "";
+  current.textParts.push(value);
+  return true;
+}
+
+function specialToken(text, start, stack) {
+  if (text.startsWith("<!--", start)) {
+    const end = text.indexOf("-->", start + 4);
+    return end < 0 ? { valid: false } : { valid: true, next: end + 3 };
+  }
+  if (text.startsWith("<![CDATA[", start)) {
+    const end = text.indexOf("]]>", start + 9);
+    if (end < 0 || stack.length === 0) return { valid: false };
+    stack[stack.length - 1].textParts.push(text.slice(start + 9, end));
+    return { valid: true, next: end + 3 };
+  }
+  if (text.startsWith("<?", start)) {
+    const end = text.indexOf("?>", start + 2);
+    return end < 0 ? { valid: false } : { valid: true, next: end + 2 };
+  }
+  if (text.startsWith("<!", start)) return { valid: false };
+  return null;
+}
+
+function closeNode(raw, state) {
+  const closing = raw.slice(1).trim().match(/^([A-Za-z_][A-Za-z0-9_.:-]*)\s*$/u)?.[1];
+  const open = state.stack.pop();
+  if (!closing || !open || open.name !== closing) return false;
+  open.text = open.textParts.join("");
+  if (state.stack.length === 0) {
+    if (state.rootClosed || open !== state.root) return false;
+    state.rootClosed = true;
+  }
+  return true;
+}
+
+function openNode(raw, state) {
+  const selfClosing = /\/\s*$/u.test(raw);
+  const body = selfClosing ? raw.replace(/\/\s*$/u, "").trimEnd() : raw;
+  const name = body.match(/^([A-Za-z_][A-Za-z0-9_.:-]*)/u)?.[1];
+  if (!name || (state.stack.length === 0 && (state.root || state.rootClosed))) return false;
+  if (!state.root && state.expectedRoot && name !== state.expectedRoot) return false;
+  const attributes = parseAttributes(body.slice(name.length).trim());
+  if (!attributes) return false;
+  const node = { name, attributes, textParts: [], children: [], text: "" };
+  state.nodes.push(node);
+  if (state.stack.length > 0) state.stack[state.stack.length - 1].children.push(node);
+  if (!state.root) state.root = node;
+  if (!selfClosing) state.stack.push(node);
+  else if (node === state.root) state.rootClosed = true;
+  return true;
+}
+
+export function parseXmlStructure(text, expectedRoot = null, maxBytes = DEFAULT_XML_MAX_BYTES) {
+  if (typeof text !== "string" || text.length > maxBytes || /\r(?!\n)/u.test(text)) return null;
+  const state = { nodes: [], stack: [], root: null, rootClosed: false, expectedRoot };
+  let index = 0;
+  while (index < text.length) {
+    const tagStart = text.indexOf("<", index);
+    if (tagStart < 0) break;
+    if (!appendText(state.stack, text.slice(index, tagStart))) return null;
+    const special = specialToken(text, tagStart, state.stack);
+    if (special) {
+      if (!special.valid) return null;
+      index = special.next;
+      continue;
+    }
+    const tagEnd = findTagEnd(text, tagStart + 1);
+    if (tagEnd < 0) return null;
+    const raw = text.slice(tagStart + 1, tagEnd).trim();
+    if (raw === "") return null;
+    const valid = raw.startsWith("/") ? closeNode(raw, state) : openNode(raw, state);
+    if (!valid) return null;
+    index = tagEnd + 1;
+  }
+  if (!appendText(state.stack, text.slice(index))) return null;
+  if (!state.root || state.stack.length > 0 || !state.rootClosed) return null;
+  return { root: state.root, nodes: state.nodes };
+}