@getodk/xforms-engine 0.4.0 → 0.5.0

package/src/parse/model/SecondaryInstance/sources/GeoJSONExternalSecondaryInstance.ts

@@ -0,0 +1,414 @@
+import { XFORMS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import { assertUnknownArray } from '@getodk/common/lib/type-assertions/assertUnknownArray.ts';
+import type { UnknownObject } from '@getodk/common/lib/type-assertions/assertUnknownObject.ts';
+import { assertUnknownObject } from '@getodk/common/lib/type-assertions/assertUnknownObject.ts';
+import type {
+	GeoJsonProperties as BaseGeoJSONProperties,
+	LineString as BaseLineString,
+	Point as BasePoint,
+	Polygon as BasePolygon,
+	Feature as GeoJSONFeature,
+	FeatureCollection as GeoJSONFeatureCollection,
+} from 'geojson';
+import { ErrorProductionDesignPendingError } from '../../../../error/ErrorProductionDesignPendingError.ts';
+import { StaticAttribute } from '../../../../integration/xpath/static-dom/StaticAttribute.ts';
+import { StaticElement } from '../../../../integration/xpath/static-dom/StaticElement.ts';
+import { StaticText } from '../../../../integration/xpath/static-dom/StaticText.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceRootDefinition } from '../SecondaryInstanceRootDefinition.ts';
+import { ExternalSecondaryInstanceSource } from './ExternalSecondaryInstanceSource.ts';
+
+const FEATURE_COLLECTION = 'FeatureCollection';
+type FEATURE_COLLECTION = typeof FEATURE_COLLECTION;
+
+const FEATURE = 'Feature';
+type FEATURE = typeof FEATURE;
+
+const POINT = 'Point';
+type POINT = typeof POINT;
+
+const LINE_STRING = 'LineString';
+type LINE_STRING = typeof LINE_STRING;
+
+const POLYGON = 'Polygon';
+type POLYGON = typeof POLYGON;
+
+type SupportedGeometryType = LINE_STRING | POINT | POLYGON;
+
+const SUPPORTED_TYPES = new Set<SupportedGeometryType>([POINT, LINE_STRING, POLYGON]);
+
+const SUPPORTED_TYPES_MESSAGE = 'Only Points, LineStrings and Polygons are currently supported';
+
+type LongLatCoordinates = readonly [longitude: number, latitude: number];
+
+interface UnknownCoordinatesObject {
+	readonly coordinates: unknown;
+}
+
+// prettier-ignore
+type ExtensibleBaseGeoJSONType<T> =
+	T extends UnknownCoordinatesObject
+		? Readonly<Omit<T, 'coordinates'>>
+		: Readonly<T>;
+
+interface Point extends ExtensibleBaseGeoJSONType<BasePoint> {
+	readonly coordinates: LongLatCoordinates;
+}
+
+type LineStringCoordinates = readonly LongLatCoordinates[];
+
+interface LineString extends ExtensibleBaseGeoJSONType<BaseLineString> {
+	readonly coordinates: LineStringCoordinates;
+}
+
+// prettier-ignore
+type PolygonCoordinates =
+	| readonly []
+	| readonly [LineStringCoordinates];
+
+interface Polygon extends ExtensibleBaseGeoJSONType<BasePolygon> {
+	readonly coordinates: PolygonCoordinates;
+}
+
+// prettier-ignore
+type SupportedGeometry =
+	| LineString
+	| Point
+	| Polygon;
+
+interface UnparsedGeometry<Type extends SupportedGeometryType> {
+	readonly type: Type;
+	readonly coordinates: readonly unknown[];
+}
+
+type UnknownGeometry = {
+	[Type in SupportedGeometryType]: UnparsedGeometry<Type>;
+}[SupportedGeometryType];
+
+/**
+ * This is a stricter variant of {@link BaseGeoJSONProperties}.
+ */
+type GeoJSONProperties = UnknownObject;
+
+/**
+ * This is our supported variant/subset of {@link GeoJSONFeature} where:
+ *
+ * - {@link geometry} is parsed/validated to be one of our
+ *   {@link SupportedGeometry | supported geometries}
+ *
+ * - all properties and non-primitive property values are deeply `readonly`
+ */
+interface Feature {
+	readonly type: FEATURE;
+	readonly geometry: SupportedGeometry;
+	readonly id?: number | string | undefined;
+
+	/**
+	 * Perhaps surprising: this property is required by the
+	 * {@link https://datatracker.ietf.org/doc/html/rfc7946#section-3.2 | GeoJSON spec}!
+	 */
+	readonly properties: GeoJSONProperties | null;
+}
+
+/**
+ * This is our supported variant/subset of {@link GeoJSONFeatureCollection}, as
+ * described for {@link Feature}.
+ */
+interface FeatureCollection {
+	readonly type: FEATURE_COLLECTION;
+	readonly features: readonly Feature[];
+}
+
+type AssertLongLatCoordinates = (data: unknown) => asserts data is LongLatCoordinates;
+
+const assertLongLatCoordinates: AssertLongLatCoordinates = (data) => {
+	assertUnknownArray(data);
+
+	const [longitude, latitude, ...rest] = data;
+
+	if (typeof longitude === 'number' && typeof latitude === 'number' && rest.length === 0) {
+		return;
+	}
+
+	throw new ErrorProductionDesignPendingError(
+		`Only ${POINT}s with latitude and longitude are currently supported`
+	);
+};
+
+type AssertUnknownGeometry = (value: unknown) => asserts value is UnknownGeometry;
+
+const assertUnknownGeometry: AssertUnknownGeometry = (value) => {
+	assertUnknownObject(value);
+
+	if (!SUPPORTED_TYPES.has(value.type as SupportedGeometryType)) {
+		throw new ErrorProductionDesignPendingError(SUPPORTED_TYPES_MESSAGE);
+	}
+
+	assertUnknownArray(value.coordinates);
+};
+
+type AssertSupportedGeometry = (value: unknown) => asserts value is SupportedGeometry;
+
+const assertSupportedGeometry: AssertSupportedGeometry = (value) => {
+	assertUnknownGeometry(value);
+
+	switch (value.type) {
+		case LINE_STRING:
+			value.coordinates.forEach(assertLongLatCoordinates);
+			break;
+
+		case POINT:
+			assertLongLatCoordinates(value.coordinates);
+			break;
+
+		case POLYGON: {
+			const [coordinates, ...rest] = value.coordinates;
+
+			if (coordinates == null) {
+				return;
+			}
+
+			if (rest.length > 0) {
+				throw new ErrorProductionDesignPendingError(
+					`Unsupported ${POLYGON}: multiple sets of coordinates`
+				);
+			}
+
+			assertUnknownArray(coordinates);
+			coordinates.forEach(assertLongLatCoordinates);
+
+			break;
+		}
+
+		default:
+			throw new UnreachableError(value);
+	}
+};
+
+type AssertFeature = (value: unknown) => asserts value is Feature;
+
+const assertFeature: AssertFeature = (value) => {
+	assertUnknownObject(value);
+
+	const { geometry, type, id, properties } = value;
+
+	if (type !== FEATURE) {
+		throw new ErrorProductionDesignPendingError(
+			`Expected Feature.type ${FEATURE}, got ${String(type)}`
+		);
+	}
+
+	assertSupportedGeometry(geometry);
+
+	if ('id' in value) {
+		const typeofId = typeof id;
+
+		switch (typeofId) {
+			case 'number':
+			case 'string':
+			case 'undefined':
+				break;
+
+			default:
+				throw new ErrorProductionDesignPendingError(
+					`Unexpected type of feature id property: ${typeofId}`
+				);
+		}
+	}
+
+	// Note: atypical strict check for `null` value! The `properties` key is
+	// required per
+	if (properties === null) {
+		return;
+	}
+
+	assertUnknownObject(properties);
+};
+
+type AssertFeatureCollection = (value: unknown) => asserts value is FeatureCollection;
+
+const assertFeatureCollection: AssertFeatureCollection = (value) => {
+	assertUnknownObject(value);
+
+	const { type, features } = value;
+
+	if (type !== FEATURE_COLLECTION) {
+		throw new ErrorProductionDesignPendingError(
+			`Expected FeatureCollection.type ${FEATURE_COLLECTION}, got ${String(type)}`
+		);
+	}
+
+	assertUnknownArray(features);
+
+	features.forEach(assertFeature);
+};
+
+type SerializedCoordinates = `${LongLatCoordinates[1]} ${LongLatCoordinates[0]} 0 0`;
+
+const serializeCoordinates = (coordinates: LongLatCoordinates): SerializedCoordinates => {
+	const [longitude, latitude] = coordinates;
+
+	return `${latitude} ${longitude} 0 0`;
+};
+
+class GeoJSONSecondaryInstanceFeatureGeometryElement extends StaticElement {
+	static from(
+		parent: StaticElement,
+		feature: Feature
+	): GeoJSONSecondaryInstanceFeatureGeometryElement {
+		const { geometry } = feature;
+
+		switch (geometry.type) {
+			case 'LineString':
+				return new this(parent, geometry.coordinates);
+
+			case 'Point':
+				return new this(parent, [geometry.coordinates]);
+
+			case 'Polygon':
+				return new this(parent, geometry.coordinates[0] ?? []);
+
+			default:
+				throw new UnreachableError(geometry);
+		}
+	}
+
+	constructor(parent: StaticElement, points: readonly LongLatCoordinates[]) {
+		const values = points.map(serializeCoordinates);
+		const value = values.join('; ');
+
+		super(
+			parent,
+			() => [],
+			(self) => [new StaticText(self, value)],
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'geometry',
+			}
+		);
+	}
+}
+
+class GeoJSONSecondaryInstanceFeaturePropertyElement extends StaticElement {
+	static *buildPropertyElements(
+		parent: StaticElement,
+		feature: Feature
+	): Iterable<GeoJSONSecondaryInstanceFeaturePropertyElement> {
+		const { properties } = feature;
+
+		if (properties == null) {
+			return [];
+		}
+
+		const { id: propertiesId, ...nonIdProperties } = properties;
+		const { id = propertiesId } = feature;
+
+		if (id !== undefined) {
+			yield new this(parent, 'id', String(id));
+		}
+
+		for (const [propertyName, propertyValue] of Object.entries(nonIdProperties)) {
+			yield new this(parent, propertyName, String(propertyValue));
+		}
+	}
+
+	constructor(parent: StaticElement, propertyName: string, propertyValue: string) {
+		super(
+			parent,
+			() => [],
+			(self) => [new StaticText(self, propertyValue)],
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: propertyName,
+			}
+		);
+	}
+}
+
+class GeoJSONSecondaryInstanceFeatureItemElement extends StaticElement {
+	constructor(parent: StaticElement, feature: Feature) {
+		super(
+			parent,
+			() => [],
+			(self) => {
+				const geometry = GeoJSONSecondaryInstanceFeatureGeometryElement.from(self, feature);
+				const properties = GeoJSONSecondaryInstanceFeaturePropertyElement.buildPropertyElements(
+					self,
+					feature
+				);
+
+				return [geometry, ...properties];
+			},
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'item',
+			}
+		);
+	}
+}
+
+class GeoJSONSecondaryInstanceRootElement extends StaticElement {
+	constructor(parent: StaticElement, featureCollection: FeatureCollection) {
+		super(
+			parent,
+			() => [],
+			(self) => {
+				return featureCollection.features.map((feature) => {
+					return new GeoJSONSecondaryInstanceFeatureItemElement(self, feature);
+				});
+			},
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'root',
+			}
+		);
+	}
+}
+
+class GeoJSONExternalSecondaryInstanceDocumentElement extends SecondaryInstanceRootDefinition {
+	constructor(
+		instanceId: string,
+		parent: GeoJSONExternalSecondaryInstanceDefinition,
+		featureCollection: FeatureCollection
+	) {
+		super(
+			parent,
+			(self) => [
+				new StaticAttribute(self, {
+					namespaceURI: XFORMS_NAMESPACE_URI,
+					localName: 'id',
+					value: instanceId,
+				}),
+			],
+			(self) => [new GeoJSONSecondaryInstanceRootElement(self, featureCollection)],
+			{
+				namespaceURI: XFORMS_NAMESPACE_URI,
+				localName: 'instance',
+			}
+		);
+	}
+}
+
+class GeoJSONExternalSecondaryInstanceDefinition extends SecondaryInstanceDefinition {
+	constructor(instanceId: string, featureCollection: FeatureCollection) {
+		super((self) => {
+			return new GeoJSONExternalSecondaryInstanceDocumentElement(
+				instanceId,
+				self,
+				featureCollection
+			);
+		});
+	}
+}
+
+export class GeoJSONExternalSecondaryInstanceSource extends ExternalSecondaryInstanceSource<'geojson'> {
+	parseDefinition(): SecondaryInstanceDefinition {
+		const { data } = this.resource;
+		const value = JSON.parse(data) as unknown;
+
+		assertFeatureCollection(value);
+
+		return new GeoJSONExternalSecondaryInstanceDefinition(this.instanceId, value);
+	}
+}

package/src/parse/model/SecondaryInstance/sources/InternalSecondaryInstanceSource.ts

@@ -0,0 +1,19 @@
+import { parseStaticDocumentFromDOMSubtree } from '../../../shared/parseStaticDocumentFromDOMSubtree.ts';
+import type { DOMSecondaryInstanceElement } from '../../../XFormDOM.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceRootDefinition } from '../SecondaryInstanceRootDefinition.ts';
+import { SecondaryInstanceSource } from './SecondaryInstanceSource.ts';
+
+export class InternalSecondaryInstanceSource extends SecondaryInstanceSource<'internal'> {
+	constructor(instanceId: string, resourceURL: null, domElement: DOMSecondaryInstanceElement) {
+		super('internal', instanceId, resourceURL, domElement);
+	}
+
+	parseDefinition(): SecondaryInstanceDefinition {
+		return parseStaticDocumentFromDOMSubtree(
+			SecondaryInstanceDefinition,
+			SecondaryInstanceRootDefinition,
+			this.domElement
+		);
+	}
+}

package/src/parse/model/SecondaryInstance/sources/SecondaryInstanceSource.ts

@@ -0,0 +1,29 @@
+import type { JRResourceURL } from '@getodk/common/jr-resources/JRResourceURL.ts';
+import type { DOMSecondaryInstanceElement } from '../../../XFormDOM.ts';
+import type { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+
+// prettier-ignore
+export type ExternalSecondaryInstanceSourceFormat =
+	| 'csv'
+	| 'geojson'
+	| 'xml';
+
+// prettier-ignore
+export type SecondaryInstanceSourceFormat =
+	// eslint-disable-next-line @typescript-eslint/sort-type-constituents
+	| ExternalSecondaryInstanceSourceFormat
+	| 'internal'
+	| 'blank';
+
+export abstract class SecondaryInstanceSource<
+	Format extends SecondaryInstanceSourceFormat = SecondaryInstanceSourceFormat,
+> {
+	constructor(
+		readonly format: Format,
+		readonly instanceId: string,
+		readonly resourceURL: JRResourceURL | null,
+		readonly domElement: DOMSecondaryInstanceElement
+	) {}
+
+	abstract parseDefinition(): SecondaryInstanceDefinition;
+}

package/src/parse/model/SecondaryInstance/sources/XMLExternalSecondaryInstanceSource.ts

@@ -0,0 +1,32 @@
+import { XFORMS_NAMESPACE_URI } from '@getodk/common/constants/xmlns.ts';
+import { parseStaticDocumentFromDOMSubtree } from '../../../shared/parseStaticDocumentFromDOMSubtree.ts';
+import { SecondaryInstanceDefinition } from '../SecondaryInstanceDefinition.ts';
+import { SecondaryInstanceRootDefinition } from '../SecondaryInstanceRootDefinition.ts';
+import { ExternalSecondaryInstanceSource } from './ExternalSecondaryInstanceSource.ts';
+import type { InternalSecondaryInstanceSource } from './InternalSecondaryInstanceSource.ts';
+
+export class XMLExternalSecondaryInstanceSource extends ExternalSecondaryInstanceSource<'xml'> {
+	/**
+	 * Note: this logic is a superset of the logic in
+	 * {@link InternalSecondaryInstanceSource.parseDefinition}. That subset is so
+	 * trivial/already sufficiently abstracted that it doesn't really make a lot
+	 * of sense to abstract further, but it might be worth considering if both
+	 * method implementations grow their responsibilities in the same ways.
+	 */
+	parseDefinition(): SecondaryInstanceDefinition {
+		const xmlDocument = this.domElement.ownerDocument.implementation.createDocument(
+			XFORMS_NAMESPACE_URI,
+			'instance'
+		);
+		const instanceElement = xmlDocument.documentElement;
+
+		instanceElement.setAttribute('id', this.instanceId);
+		instanceElement.innerHTML = this.resource.data;
+
+		return parseStaticDocumentFromDOMSubtree(
+			SecondaryInstanceDefinition,
+			SecondaryInstanceRootDefinition,
+			instanceElement
+		);
+	}
+}

package/src/parse/shared/parseStaticDocumentFromDOMSubtree.ts

@@ -0,0 +1,149 @@
+import { UnreachableError } from '@getodk/common/lib/error/UnreachableError.ts';
+import type { AnyConstructor } from '@getodk/common/types/helpers.js';
+import { StaticAttribute } from '../../integration/xpath/static-dom/StaticAttribute.ts';
+import type {
+	StaticDocument,
+	StaticDocumentRootFactory,
+} from '../../integration/xpath/static-dom/StaticDocument.ts';
+import type {
+	StaticElementAttributesFactory,
+	StaticElementChildNodesFactory,
+} from '../../integration/xpath/static-dom/StaticElement.ts';
+import { StaticElement } from '../../integration/xpath/static-dom/StaticElement.ts';
+import type { StaticNamedNodeOptions } from '../../integration/xpath/static-dom/StaticNamedNode.ts';
+import type { StaticParentNode } from '../../integration/xpath/static-dom/StaticNode.ts';
+import { StaticText } from '../../integration/xpath/static-dom/StaticText.ts';
+
+type ConcreteConstructor<T extends AnyConstructor> = Pick<T, keyof T>;
+
+// prettier-ignore
+export type ConcreteStaticDocumentConstructor<
+	T extends StaticDocument<Root>,
+	Root extends StaticElement,
+> =
+	& ConcreteConstructor<typeof StaticDocument<Root>>
+	& (new (rootFactory: StaticDocumentRootFactory<T, Root>) => T);
+
+const domElementAttributesFactory = (domElement: Element): StaticElementAttributesFactory => {
+	const attributes = Array.from(domElement.attributes);
+
+	return (element) => {
+		return attributes.map((attr) => {
+			return new StaticAttribute(element, attr);
+		});
+	};
+};
+
+const { ELEMENT_NODE, CDATA_SECTION_NODE, TEXT_NODE } = Node;
+
+interface StaticChildElementSource {
+	readonly domType: typeof ELEMENT_NODE;
+	readonly domNode: Element;
+}
+
+interface StaticChildTextSource {
+	readonly domType: typeof CDATA_SECTION_NODE | typeof TEXT_NODE;
+	readonly domNode: CharacterData;
+}
+
+// prettier-ignore
+type StaticChildNodeSource =
+	| StaticChildElementSource
+	| StaticChildTextSource;
+
+export const toStaticChildNodeSource = (childNode: ChildNode): StaticChildNodeSource | null => {
+	const domType = childNode.nodeType;
+
+	switch (domType) {
+		case ELEMENT_NODE:
+			return {
+				domType,
+				domNode: childNode as Element,
+			};
+
+		case TEXT_NODE:
+			return {
+				domType,
+				domNode: childNode as Text,
+			};
+
+		case CDATA_SECTION_NODE:
+			return {
+				domType,
+				domNode: childNode as CDATASection,
+			};
+
+		default:
+			return null;
+	}
+};
+
+const toStaticChildNodeSources = (childNode: ChildNode): StaticChildNodeSource | readonly [] => {
+	return toStaticChildNodeSource(childNode) ?? [];
+};
+
+const domElementChildNodesFactory = (domElement: Element): StaticElementChildNodesFactory => {
+	const childNodeSources = Array.from(domElement.childNodes).flatMap(toStaticChildNodeSources);
+
+	return (parent) => {
+		return childNodeSources.map((domSource) => {
+			switch (domSource.domType) {
+				case ELEMENT_NODE:
+					return parseStaticElementFromDOMElement(parent, StaticElement, domSource.domNode);
+
+				case TEXT_NODE:
+				case CDATA_SECTION_NODE:
+					return new StaticText(parent, domSource.domNode.data);
+
+				default:
+					throw new UnreachableError(domSource);
+			}
+		});
+	};
+};
+
+// prettier-ignore
+export type StaticElementConstructor<
+	T extends StaticElement<Parent>,
+	Parent extends StaticParentNode = StaticParentNode
+> =
+	& ConcreteConstructor<typeof StaticElement>
+	& {
+			readonly prototype: T;
+
+			new (
+				parent: Parent,
+				attributesFactory: StaticElementAttributesFactory,
+				childNodesFactory: StaticElementChildNodesFactory,
+				options: StaticNamedNodeOptions
+			): T;
+	};
+
+const parseStaticElementFromDOMElement = <
+	T extends StaticElement,
+	Parent extends StaticParentNode = StaticParentNode,
+>(
+	parent: Parent,
+	ElementConstructor: StaticElementConstructor<T, Parent>,
+	domElement: Element
+): T => {
+	const attributesFactory = domElementAttributesFactory(domElement);
+	const childNodesFactory = domElementChildNodesFactory(domElement);
+
+	return new ElementConstructor(parent, attributesFactory, childNodesFactory, domElement);
+};
+
+export const parseStaticDocumentFromDOMSubtree = <
+	T extends StaticDocument<Root>,
+	Root extends StaticElement<T>,
+>(
+	DocumentConstructor: ConcreteStaticDocumentConstructor<T, Root>,
+	DocumentRootConstructor: StaticElementConstructor<Root, T>,
+	subtreeRootElement: Element
+): T => {
+	const rootFactory: StaticDocumentRootFactory<T, Root> = (parent) => {
+		return parseStaticElementFromDOMElement(parent, DocumentRootConstructor, subtreeRootElement);
+	};
+
+	return new DocumentConstructor(rootFactory);
+};

package/src/parse/text/abstract/TextRangeDefinition.ts

@@ -2,7 +2,6 @@ import type { LocalNamedElement } from '@getodk/common/types/dom.ts';
 import type { TextRole } from '../../../client/TextRange.ts';
 import type { XFormDefinition } from '../../../parse/XFormDefinition.ts';
 import { DependencyContext } from '../../expression/abstract/DependencyContext.ts';
-import type { AnyDependentExpression } from '../../expression/abstract/DependentExpression.ts';
 import type { AnyTextChunkExpression } from '../../expression/abstract/TextChunkExpression.ts';
 import type { AnyMessageDefinition } from '../MessageDefinition.ts';
 import type { AnyTextElementDefinition } from './TextElementDefinition.ts';
@@ -52,11 +51,6 @@ export abstract class TextRangeDefinition<Role extends TextRole> extends Depende
 		this.parentReference = ownerContext.parentReference;
 	}
 
-	override registerDependentExpression(expression: AnyDependentExpression): void {
-		this.ownerContext.registerDependentExpression(expression);
-		super.registerDependentExpression(expression);
-	}
-
 	toJSON(): object {
 		const { form, ownerContext, ...rest } = this;
 

package/src/parse/xpath/semantic-analysis.ts

@@ -9,7 +9,9 @@ import type {
 	FilterPathExprNode,
 	FunctionCallNode,
 	FunctionNameNode,
+	LocalPartNode,
 	NumberNode,
+	PrefixNode,
 	RelativeLocationPathNode,
 	StringLiteralNode,
 } from '@getodk/xpath/static/grammar/SyntaxNode.js';
@@ -464,3 +466,30 @@ export const isConstantTruthyExpression = (
 			throw new UnreachableError(syntaxNode);
 	}
 };
+
+interface QualifiedNameExpression {
+	readonly prefix: string;
+	readonly localPart: string;
+}
+
+export const parseQualifiedNameExpression = (
+	expression: string
+): QualifiedNameExpression | null => {
+	const { rootNode } = expressionParser.parse(expression);
+	const syntaxNode = findTypedPrincipalExpressionNode(['prefixed_name'], rootNode);
+
+	if (syntaxNode == null) {
+		return null;
+	}
+
+	const [prefixNode, localPartNode, ...rest] = syntaxNode.children;
+
+	prefixNode satisfies PrefixNode;
+	localPartNode satisfies LocalPartNode;
+	rest satisfies readonly [];
+
+	return {
+		prefix: prefixNode.text,
+		localPart: localPartNode.text,
+	};
+};