@wirebench/engine 2.1.1

package/dist/xsd/sample-values.d.ts

@@ -0,0 +1,54 @@
+import type { QName } from '../wsdl/qname.js';
+import type { BuiltinType } from './builtins.js';
+import type { SimpleType, TypeDefinition } from './model.js';
+/** The lookups the value helpers need; satisfied by a built `SchemaSet`. */
+export interface SampleValueContext {
+    lookupType(name: QName): TypeDefinition | undefined;
+    builtin(name: QName): BuiltinType | undefined;
+}
+/** Options controlling how a leaf's content is produced. */
+export interface SampleValueOptions {
+    /** When false, every leaf is the placeholder `?`. */
+    readonly sampleValues: boolean;
+}
+/** A reference to a simple type: a name, an inline definition, or nothing. */
+export type SimpleTypeRef = QName | SimpleType | undefined;
+/** The placeholder emitted for every leaf when sample values are off. */
+export declare const PLACEHOLDER = "?";
+/**
+ * Walks a simple type's restriction chain down to the built-in it ultimately
+ * derives from. Returns `undefined` for unresolvable or non-atomic chains.
+ */
+export declare function builtinBaseOf(ctx: SampleValueContext, ref: SimpleTypeRef, visited?: Set<string>): BuiltinType | undefined;
+/** The constraining facets a form editor can act on, gathered from a restriction chain. */
+export interface FormFacets {
+    readonly enum?: readonly string[];
+    readonly pattern?: string;
+    /** Lexical `minInclusive`/`minExclusive` bound, whichever the chain declares first. */
+    readonly min?: string;
+    readonly max?: string;
+}
+/**
+ * Collects the facets a form field can enforce (`enumeration`, `pattern` and the
+ * numeric/date bounds) by walking a simple type's restriction chain, nearest
+ * declaration winning. Returns an empty object for built-ins and unresolvable
+ * references — the form never blocks on a facet it could not read.
+ */
+export declare function facetsOf(ctx: SampleValueContext, ref: SimpleTypeRef, visited?: Set<string>): FormFacets;
+/**
+ * Produces the text content for a simple-typed leaf: the placeholder
+ * `?` unless `sampleValues` is on, in which case a facet- and built-in-derived
+ * example value is returned. Callers apply `fixed`/`default` themselves; those
+ * always win over anything computed here.
+ *
+ * @param type the leaf's type: a named reference, an inline definition, or `undefined` (treated as `xs:anyType`)
+ */
+export declare function sampleValueFor(ctx: SampleValueContext, type: SimpleTypeRef, options: SampleValueOptions): string;
+/**
+ * Builds the body of a leaf's `<!--type: …-->` comment, e.g. `type: xs:int` or
+ * `type: xs:string - enumeration: [RED, GREEN, BLUE]`. Named simple types are
+ * reported by the built-in they ultimately restrict, so the comment always
+ * says what the value must look like. Returns `undefined` when nothing useful
+ * is known about the type.
+ */
+export declare function typeCommentFor(ctx: SampleValueContext, type: SimpleTypeRef): string | undefined;

package/dist/xsd/sample-values.js

@@ -0,0 +1,267 @@
+import { NS } from '../xml/namespaces.js';
+import { qnameToString } from '../wsdl/qname.js';
+/** The placeholder emitted for every leaf when sample values are off. */
+export const PLACEHOLDER = '?';
+const INTEGER_NAMES = new Set([
+    'integer',
+    'nonPositiveInteger',
+    'negativeInteger',
+    'long',
+    'int',
+    'short',
+    'byte',
+    'nonNegativeInteger',
+    'unsignedLong',
+    'unsignedInt',
+    'unsignedShort',
+    'unsignedByte',
+    'positiveInteger',
+]);
+function isQName(ref) {
+    return !('kind' in ref);
+}
+/** The value of the first `enumeration` facet, if the type declares one. */
+function enumerationFacet(facets) {
+    for (const facet of facets) {
+        if (facet.kind === 'enumeration') {
+            return facet.values;
+        }
+    }
+    return undefined;
+}
+/** The lexical value of the first bound facet of `kind`. */
+function boundFacet(facets, kind) {
+    for (const facet of facets) {
+        if (facet.kind === kind) {
+            return facet.value;
+        }
+    }
+    return undefined;
+}
+/** The value of the first `length` facet, falling back to `minLength`. */
+function lengthFacet(facets) {
+    for (const kind of ['length', 'minLength']) {
+        for (const facet of facets) {
+            if (facet.kind === kind) {
+                return facet.value;
+            }
+        }
+    }
+    return undefined;
+}
+/** Resolves a named reference to its simple type definition, if the schema has one. */
+function resolveSimple(ctx, ref) {
+    if (ref === undefined) {
+        return undefined;
+    }
+    if (!isQName(ref)) {
+        return ref;
+    }
+    const type = ctx.lookupType(ref);
+    return type !== undefined && type.kind === 'simpleType' ? type : undefined;
+}
+/**
+ * Walks a simple type's restriction chain down to the built-in it ultimately
+ * derives from. Returns `undefined` for unresolvable or non-atomic chains.
+ */
+export function builtinBaseOf(ctx, ref, visited = new Set()) {
+    if (ref === undefined) {
+        return undefined;
+    }
+    if (isQName(ref)) {
+        const key = qnameToString(ref);
+        if (visited.has(key)) {
+            return undefined;
+        }
+        visited.add(key);
+        const builtin = ctx.builtin(ref);
+        if (builtin !== undefined) {
+            return builtin.aliasOf !== undefined ? (ctx.builtin(builtin.aliasOf) ?? builtin) : builtin;
+        }
+        return builtinBaseOf(ctx, resolveSimple(ctx, ref), visited);
+    }
+    if (ref.variety !== 'atomic') {
+        return undefined;
+    }
+    return builtinBaseOf(ctx, ref.base ?? ref.baseType, visited);
+}
+/** The nearest `enumeration` facet in a simple type's restriction chain. */
+function enumerationOf(ctx, ref, visited = new Set()) {
+    const simple = resolveSimple(ctx, ref);
+    if (simple === undefined) {
+        return undefined;
+    }
+    if (isQName(ref)) {
+        const key = qnameToString(ref);
+        if (visited.has(key)) {
+            return undefined;
+        }
+        visited.add(key);
+    }
+    const values = enumerationFacet(simple.facets);
+    if (values !== undefined && values.length > 0) {
+        return values;
+    }
+    return simple.variety === 'atomic' ? enumerationOf(ctx, simple.base ?? simple.baseType, visited) : undefined;
+}
+/**
+ * Collects the facets a form field can enforce (`enumeration`, `pattern` and the
+ * numeric/date bounds) by walking a simple type's restriction chain, nearest
+ * declaration winning. Returns an empty object for built-ins and unresolvable
+ * references — the form never blocks on a facet it could not read.
+ */
+export function facetsOf(ctx, ref, visited = new Set()) {
+    const simple = resolveSimple(ctx, ref);
+    if (simple === undefined) {
+        return {};
+    }
+    if (ref !== undefined && isQName(ref)) {
+        const key = qnameToString(ref);
+        if (visited.has(key)) {
+            return {};
+        }
+        visited.add(key);
+    }
+    const inherited = simple.variety === 'atomic' ? facetsOf(ctx, simple.base ?? simple.baseType, visited) : {};
+    const values = enumerationFacet(simple.facets);
+    const pattern = simple.facets.find((f) => f.kind === 'pattern');
+    const min = boundFacet(simple.facets, 'minInclusive') ?? boundFacet(simple.facets, 'minExclusive');
+    const max = boundFacet(simple.facets, 'maxInclusive') ?? boundFacet(simple.facets, 'maxExclusive');
+    return {
+        ...inherited,
+        ...(values !== undefined && values.length > 0 ? { enum: values } : {}),
+        ...(pattern !== undefined && pattern.kind === 'pattern' ? { pattern: pattern.value } : {}),
+        ...(min !== undefined ? { min } : {}),
+        ...(max !== undefined ? { max } : {}),
+    };
+}
+/** Adds `delta` to an integer bound, leaving non-integer bounds untouched. */
+function shiftBound(value, delta, integer) {
+    if (!integer) {
+        return value;
+    }
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? String(Math.trunc(parsed) + delta) : value;
+}
+/**
+ * Derives a value from a simple type's facets. Facets are considered in a fixed
+ * order so output stays predictable: `enumeration` (first value), then the
+ * bounds (`minInclusive`, `minExclusive` + 1 for integers, `maxInclusive`,
+ * `maxExclusive` - 1 for integers), then `length`/`minLength` (that many `?`),
+ * and finally the built-in base's own sample value.
+ */
+function atomicSample(ctx, simple, visited) {
+    const values = enumerationFacet(simple.facets);
+    if (values !== undefined && values.length > 0) {
+        return values[0];
+    }
+    const base = builtinBaseOf(ctx, simple);
+    const integer = base !== undefined && base.name.namespaceUri === NS.XSD && INTEGER_NAMES.has(base.name.localName);
+    const minInclusive = boundFacet(simple.facets, 'minInclusive');
+    if (minInclusive !== undefined) {
+        return minInclusive;
+    }
+    const minExclusive = boundFacet(simple.facets, 'minExclusive');
+    if (minExclusive !== undefined) {
+        return shiftBound(minExclusive, 1, integer);
+    }
+    const maxInclusive = boundFacet(simple.facets, 'maxInclusive');
+    if (maxInclusive !== undefined) {
+        return maxInclusive;
+    }
+    const maxExclusive = boundFacet(simple.facets, 'maxExclusive');
+    if (maxExclusive !== undefined) {
+        return shiftBound(maxExclusive, -1, integer);
+    }
+    const length = lengthFacet(simple.facets);
+    if (length !== undefined && length > 0 && length <= 64) {
+        return PLACEHOLDER.repeat(length);
+    }
+    return sampleFor(ctx, simple.base ?? simple.baseType, visited);
+}
+function sampleFor(ctx, ref, visited) {
+    if (ref === undefined) {
+        return PLACEHOLDER;
+    }
+    if (isQName(ref)) {
+        const key = qnameToString(ref);
+        if (visited.has(key)) {
+            return PLACEHOLDER;
+        }
+        visited.add(key);
+        const builtin = ctx.builtin(ref);
+        if (builtin !== undefined) {
+            return builtin.sampleValue === '' ? PLACEHOLDER : builtin.sampleValue;
+        }
+        const simple = resolveSimple(ctx, ref);
+        return simple === undefined ? PLACEHOLDER : sampleFor(ctx, simple, visited);
+    }
+    switch (ref.variety) {
+        case 'list': {
+            // A list sample shows two items so the separator is visible.
+            const item = sampleFor(ctx, ref.itemType, visited);
+            return `${item} ${item}`;
+        }
+        case 'union': {
+            const first = ref.memberTypes?.[0];
+            return first === undefined ? PLACEHOLDER : sampleFor(ctx, first, visited);
+        }
+        default:
+            return atomicSample(ctx, ref, visited);
+    }
+}
+/**
+ * Produces the text content for a simple-typed leaf: the placeholder
+ * `?` unless `sampleValues` is on, in which case a facet- and built-in-derived
+ * example value is returned. Callers apply `fixed`/`default` themselves; those
+ * always win over anything computed here.
+ *
+ * @param type the leaf's type: a named reference, an inline definition, or `undefined` (treated as `xs:anyType`)
+ */
+export function sampleValueFor(ctx, type, options) {
+    if (!options.sampleValues) {
+        return PLACEHOLDER;
+    }
+    return sampleFor(ctx, type, new Set());
+}
+/** Renders a type name with its conventional prefix (`xs:int`, `soapenc:string`, `ColorCode`). */
+function typeLabel(name) {
+    if (name.namespaceUri === NS.XSD) {
+        return `xs:${name.localName}`;
+    }
+    if (name.namespaceUri === NS.SOAP11_ENC) {
+        return `soapenc:${name.localName}`;
+    }
+    return name.localName;
+}
+/**
+ * Builds the body of a leaf's `<!--type: …-->` comment, e.g. `type: xs:int` or
+ * `type: xs:string - enumeration: [RED, GREEN, BLUE]`. Named simple types are
+ * reported by the built-in they ultimately restrict, so the comment always
+ * says what the value must look like. Returns `undefined` when nothing useful
+ * is known about the type.
+ */
+export function typeCommentFor(ctx, type) {
+    if (type === undefined) {
+        return undefined;
+    }
+    const simple = resolveSimple(ctx, type);
+    if (simple !== undefined && simple.variety === 'list') {
+        const item = typeCommentFor(ctx, simple.itemType);
+        return item === undefined ? undefined : `type: list of ${item.replace(/^type: /, '')}`;
+    }
+    if (simple !== undefined && simple.variety === 'union') {
+        const members = (simple.memberTypes ?? [])
+            .map((m) => typeCommentFor(ctx, m)?.replace(/^type: /, ''))
+            .filter((m) => m !== undefined);
+        return members.length === 0 ? undefined : `type: union of [${members.join(', ')}]`;
+    }
+    const base = builtinBaseOf(ctx, type);
+    const label = base !== undefined ? typeLabel(base.name) : isQName(type) ? typeLabel(type) : undefined;
+    if (label === undefined) {
+        return undefined;
+    }
+    const values = enumerationOf(ctx, type);
+    const suffix = values !== undefined ? ` - enumeration: [${values.join(', ')}]` : '';
+    return `type: ${label}${suffix}`;
+}

package/dist/xsd/schema-set.d.ts

@@ -0,0 +1,51 @@
+import type { Element } from '@xmldom/xmldom';
+import type { QName } from '../wsdl/qname.js';
+import type { DefinitionBundle } from '../wsdl/resolver.js';
+import type { BuiltinType } from './builtins.js';
+import type { AttributeDecl, AttributeGroup, ComplexType, ElementDecl, Group, ResolvedContent, SchemaProblem, TypeDefinition } from './model.js';
+/** A WSDL definition (or anything else) that exposes the inline `xs:schema` elements to index. */
+export interface SchemaElementsInput {
+    readonly schemaElements: readonly Element[];
+}
+/** Everything {@link buildSchemaSet} accepts. */
+export type SchemaSetInput = DefinitionBundle | SchemaElementsInput;
+/** The queryable, resolved set of schema components collected from a WSDL/XSD bundle. */
+export interface SchemaSet {
+    /** Every distinct `targetNamespace` contributing components, in first-seen order. */
+    readonly namespaces: readonly string[];
+    /** Global element declarations, keyed by Clark notation. */
+    readonly elements: ReadonlyMap<string, ElementDecl>;
+    /** Global type definitions (complex and simple), keyed by Clark notation. */
+    readonly types: ReadonlyMap<string, TypeDefinition>;
+    readonly groups: ReadonlyMap<string, Group>;
+    readonly attributeGroups: ReadonlyMap<string, AttributeGroup>;
+    /** Global attribute declarations, keyed by Clark notation. */
+    readonly attributes: ReadonlyMap<string, AttributeDecl>;
+    readonly problems: readonly SchemaProblem[];
+    lookupElement(name: QName): ElementDecl | undefined;
+    lookupType(name: QName): TypeDefinition | undefined;
+    lookupGroup(name: QName): Group | undefined;
+    lookupAttributeGroup(name: QName): AttributeGroup | undefined;
+    lookupAttribute(name: QName): AttributeDecl | undefined;
+    /** Transitive substitution-group members of `head`, excluding the head, including abstract members. */
+    substitutionsFor(head: QName): readonly ElementDecl[];
+    /** Flattens a complex type's derivation chain, group refs and attribute groups. */
+    resolveContent(type: ComplexType): ResolvedContent;
+    isBuiltin(name: QName): boolean;
+    builtin(name: QName): BuiltinType | undefined;
+    elementsInNamespace(namespaceUri: string): readonly ElementDecl[];
+    typesInNamespace(namespaceUri: string): readonly TypeDefinition[];
+}
+/**
+ * Builds a queryable {@link SchemaSet} from every `xs:schema` in a resolved
+ * bundle (or from a bare list of `xs:schema` elements, e.g. a merged
+ * `WsdlDefinition.schemaElements`).
+ *
+ * Pure and synchronous: nothing is fetched. `xs:import`/`xs:include` are
+ * ignored because the bundle already resolved them; `xs:redefine` is reported
+ * as `unsupported`. Dangling references never throw — they are recorded in
+ * {@link SchemaSet.problems} and the corresponding lookup returns `undefined`.
+ *
+ * @param input a {@link DefinitionBundle}, or any object exposing `schemaElements`
+ */
+export declare function buildSchemaSet(input: SchemaSetInput): SchemaSet;

package/dist/xsd/schema-set.js

@@ -0,0 +1,203 @@
+import { NS } from '../xml/namespaces.js';
+import { childElements, firstChildElement, optionalAttribute } from '../wsdl/dom-utils.js';
+import { qnameToString } from '../wsdl/qname.js';
+import { isBuiltinType, lookupBuiltin } from './builtins.js';
+import { parseSchemaElement } from './parse-schema.js';
+import { resolveContent } from './resolve-content.js';
+import { checkReferences } from './check-references.js';
+function isDefinitionBundle(input) {
+    return 'documents' in input && 'root' in input;
+}
+function schemaElementsOfWsdl(document) {
+    const root = document.documentElement;
+    if (root === null) {
+        return [];
+    }
+    const types = firstChildElement(root, NS.WSDL, 'types');
+    return types === undefined ? [] : childElements(types, NS.XSD, 'schema');
+}
+function collectSources(input) {
+    if (!isDefinitionBundle(input)) {
+        return input.schemaElements.map((element) => ({ element, location: '<inline>' }));
+    }
+    const sources = [];
+    for (const doc of input.documents) {
+        if (doc.kind === 'wsdl') {
+            for (const element of schemaElementsOfWsdl(doc.document)) {
+                sources.push({ element, location: doc.location });
+            }
+            continue;
+        }
+        const root = doc.document.documentElement;
+        if (root === null || root.namespaceURI !== NS.XSD || root.localName !== 'schema') {
+            continue;
+        }
+        // A chameleon include has no `targetNamespace` of its own: the bundle records
+        // the namespace it adopted from the including schema.
+        sources.push({
+            element: root,
+            location: doc.location,
+            ...(doc.chameleonFor !== undefined && doc.namespace !== undefined ? { namespaceOverride: doc.namespace } : {}),
+        });
+    }
+    return sources;
+}
+class SchemaSetImpl {
+    namespaces;
+    elements;
+    types;
+    groups;
+    attributeGroups;
+    attributes;
+    problems;
+    substitutionIndex = new Map();
+    constructor(namespaces, elements, types, groups, attributeGroups, attributes, problems) {
+        this.namespaces = namespaces;
+        this.elements = elements;
+        this.types = types;
+        this.groups = groups;
+        this.attributeGroups = attributeGroups;
+        this.attributes = attributes;
+        for (const decl of elements.values()) {
+            if (decl.substitutionGroup !== undefined) {
+                const key = qnameToString(decl.substitutionGroup);
+                const bucket = this.substitutionIndex.get(key);
+                if (bucket === undefined) {
+                    this.substitutionIndex.set(key, [decl]);
+                }
+                else {
+                    bucket.push(decl);
+                }
+            }
+        }
+        checkReferences(this, problems);
+        this.problems = problems;
+    }
+    lookupElement(name) {
+        return this.elements.get(qnameToString(name));
+    }
+    lookupType(name) {
+        return this.types.get(qnameToString(name));
+    }
+    lookupGroup(name) {
+        return this.groups.get(qnameToString(name));
+    }
+    lookupAttributeGroup(name) {
+        return this.attributeGroups.get(qnameToString(name));
+    }
+    lookupAttribute(name) {
+        return this.attributes.get(qnameToString(name));
+    }
+    substitutionsFor(head) {
+        const result = [];
+        const seen = new Set([qnameToString(head)]);
+        const queue = [qnameToString(head)];
+        while (queue.length > 0) {
+            const key = queue.shift();
+            for (const member of this.substitutionIndex.get(key) ?? []) {
+                const memberKey = qnameToString(member.name);
+                if (seen.has(memberKey)) {
+                    continue;
+                }
+                seen.add(memberKey);
+                result.push(member);
+                queue.push(memberKey);
+            }
+        }
+        return result;
+    }
+    resolveContent(type) {
+        return resolveContent(type, this);
+    }
+    isBuiltin(name) {
+        return isBuiltinType(name);
+    }
+    builtin(name) {
+        return lookupBuiltin(name);
+    }
+    elementsInNamespace(namespaceUri) {
+        return [...this.elements.values()].filter((e) => e.name.namespaceUri === namespaceUri);
+    }
+    typesInNamespace(namespaceUri) {
+        return [...this.types.values()].filter((t) => t.name?.namespaceUri === namespaceUri);
+    }
+}
+/** Indexes a component, keeping the first occurrence and reporting real duplicates. */
+function addComponent(map, key, component, what, problems) {
+    const existing = map.get(key);
+    if (existing === undefined) {
+        map.set(key, component);
+        return;
+    }
+    // The same schema reached twice (e.g. included from two places) is not a
+    // conflict: identical location *and* line means it is literally the same
+    // declaration, so it is skipped silently.
+    if (existing.source.location === component.source.location && existing.source.line === component.source.line) {
+        return;
+    }
+    problems.push({
+        code: 'duplicate-component',
+        message: `Duplicate ${what} ${key}; keeping the declaration from ${existing.source.location}`,
+        location: component.source.location,
+        ...(component.source.line !== undefined
+            ? { line: component.source.line, column: component.source.column ?? 1 }
+            : {}),
+    });
+}
+/**
+ * Builds a queryable {@link SchemaSet} from every `xs:schema` in a resolved
+ * bundle (or from a bare list of `xs:schema` elements, e.g. a merged
+ * `WsdlDefinition.schemaElements`).
+ *
+ * Pure and synchronous: nothing is fetched. `xs:import`/`xs:include` are
+ * ignored because the bundle already resolved them; `xs:redefine` is reported
+ * as `unsupported`. Dangling references never throw — they are recorded in
+ * {@link SchemaSet.problems} and the corresponding lookup returns `undefined`.
+ *
+ * @param input a {@link DefinitionBundle}, or any object exposing `schemaElements`
+ */
+export function buildSchemaSet(input) {
+    const problems = [];
+    const elements = new Map();
+    const types = new Map();
+    const groups = new Map();
+    const attributeGroups = new Map();
+    const attributes = new Map();
+    const namespaces = [];
+    for (const source of collectSources(input)) {
+        const schemaEl = source.element;
+        if (schemaEl.namespaceURI !== NS.XSD || schemaEl.localName !== 'schema') {
+            continue;
+        }
+        const targetNamespace = source.namespaceOverride ?? optionalAttribute(schemaEl, 'targetNamespace') ?? '';
+        const ctx = {
+            location: source.location,
+            targetNamespace,
+            elementFormDefault: optionalAttribute(schemaEl, 'elementFormDefault') === 'qualified' ? 'qualified' : 'unqualified',
+            attributeFormDefault: optionalAttribute(schemaEl, 'attributeFormDefault') === 'qualified' ? 'qualified' : 'unqualified',
+            problems,
+        };
+        if (!namespaces.includes(targetNamespace)) {
+            namespaces.push(targetNamespace);
+        }
+        const components = parseSchemaElement(schemaEl, ctx);
+        for (const decl of components.elements) {
+            addComponent(elements, qnameToString(decl.name), decl, 'element', problems);
+        }
+        for (const type of components.types) {
+            if (type.name !== undefined) {
+                addComponent(types, qnameToString(type.name), type, 'type', problems);
+            }
+        }
+        for (const group of components.groups) {
+            addComponent(groups, qnameToString(group.name), group, 'group', problems);
+        }
+        for (const group of components.attributeGroups) {
+            addComponent(attributeGroups, qnameToString(group.name), group, 'attribute group', problems);
+        }
+        for (const attribute of components.attributes) {
+            addComponent(attributes, qnameToString(attribute.name), attribute, 'attribute', problems);
+        }
+    }
+    return new SchemaSetImpl(namespaces, elements, types, groups, attributeGroups, attributes, problems);
+}

package/dist/xsd/xml-scan.d.ts

@@ -0,0 +1,64 @@
+/**
+ * A tolerant, dependency-free XML fragment scanner used by the form model.
+ *
+ * It walks the raw text once and produces an element tree in which every node,
+ * attribute value and text run carries the exact UTF-16 offset range it came
+ * from, so the form view can splice a single value back into the envelope
+ * without reformatting anything around it. Never throws: malformed input stops
+ * the scan and is reported, and elements still open at end-of-input are closed
+ * at the document end.
+ *
+ * Deliberately minimal — it exists to read a body fragment, not to validate
+ * one, so entities are decoded but DTDs, namespaces beyond `xmlns` bookkeeping
+ * and processing instructions are skipped.
+ */
+/** A half-open UTF-16 character range in a text document. */
+export interface TextRange {
+    readonly start: number;
+    readonly end: number;
+}
+/** One attribute, with the range of its value inside (not including) the quotes. */
+export interface ScannedAttribute {
+    /** As written, including any prefix (e.g. `xsi:type`). */
+    readonly name: string;
+    readonly value: string;
+    readonly valueRange: TextRange;
+}
+/** One scanned element. */
+export interface ScannedElement {
+    /** As written, including any prefix (e.g. `tem:Add`). */
+    readonly name: string;
+    readonly localName: string;
+    readonly prefix?: string;
+    /** Resolved from the `xmlns`/`xmlns:*` declarations in scope; `''` when in no namespace. */
+    readonly namespaceUri: string;
+    /** Prefix → URI declared *on this element*, empty when it declares none. */
+    readonly declaredNamespaces: Readonly<Record<string, string>>;
+    readonly attributes: readonly ScannedAttribute[];
+    /** The whole element, `<` through the end of its close tag (or `/>`). */
+    readonly range: TextRange;
+    /** Text content and its range — only for a non-self-closing element with no child elements. */
+    readonly text?: {
+        readonly value: string;
+        readonly range: TextRange;
+    };
+    readonly children: readonly ScannedElement[];
+    readonly selfClosing: boolean;
+    /** Comments found directly before this element inside its parent, in source order. */
+    readonly leadingComments: readonly string[];
+    /** Comments found inside this element after its last child element. */
+    readonly trailingComments: readonly string[];
+}
+/** What {@link scanXml} returns: the top-level elements plus any tolerance notes. */
+export interface ScanXmlResult {
+    readonly elements: readonly ScannedElement[];
+    readonly problems: readonly string[];
+}
+/**
+ * Scans an XML fragment into an element tree with exact ranges.
+ *
+ * @param text the raw fragment; may contain several top-level elements
+ * @param inScope prefix → URI bindings inherited from an enclosing document (a
+ *   body fragment sliced out of an envelope carries none of its own)
+ */
+export declare function scanXml(text: string, inScope?: Readonly<Record<string, string>>): ScanXmlResult;