swift-pterodactyl / Sources / PterodactylSyntax / SyntaxCursor.swift

// SPDX-FileCopyrightText: 2025 The Project Pterodactyl Developers
// SPDX-FileCopyrightText: 2026 The Project Pterodactyl Developers
//
// SPDX-License-Identifier: MPL-2.0

import LanguageServerProtocol

public protocol Located {
	var utf16Offset: Int { get }
	var utf16Length: Int { get }
}

extension Located {
	public var utf16Range: Range<Int> {
		utf16Offset..<utf16Offset + utf16Length
	}
}

public struct SyntaxTokenCursor: Located {
	public let token: Token
	public let metadata: TokenMetadata?
	public let utf16Offset: Int
	public var utf16Length: Int { token.utf16Length }

	public var kind: TokenKind { token.kind }

	public init(token: Token, metadata: TokenMetadata?, utf16Offset: Int) {
		self.token = token
		self.metadata = metadata
		self.utf16Offset = utf16Offset
	}

	public var text: String { token.text }
}

public struct AbsoluteSyntaxInfo: Located, Sendable {
	public let lineMap: LineMap

	/// The offset below must be taken from the start of the file.
	public let cursorOptions: SyntaxTreeCursor.Options

	public init(lineMap: LineMap, cursorOptions: SyntaxTreeCursor.Options) {
		self.lineMap = lineMap
		self.cursorOptions = cursorOptions
	}

	public var cursor: SyntaxTreeCursor { cursorOptions.cursor }
	public var utf16Length: Int { cursorOptions.tree.utf16Length }
	public var utf16Offset: Int { cursorOptions.utf16Offset }
}

/// This is similar to a “red tree” in the sense of Roslyn. In essence it instruments syntax trees with location information; unlike Roslyn, offsets are understood to be relative to some base offset known to the owner of the cursor.
public final class SyntaxTreeCursor: Located {
	public let tree: SyntaxTree
	public let utf16Offset: Int

	public init(tree: SyntaxTree, utf16Offset: Int) {
		self.tree = tree
		self.utf16Offset = utf16Offset
	}

	public var utf16Length: Int { tree.utf16Length }
	public var kind: SyntaxTreeKind { tree.kind }

	public enum Child {
		case token(SyntaxTokenCursor)
		case tree(SyntaxTreeCursor)
	}

	public private(set) lazy var children: [Child] = {
		var children: [Child] = []
		var utf16Offset = utf16Offset
		for childNode in tree.children {
			switch childNode {
			case .token(let token, let metadata):
				let tokenCursor = SyntaxTokenCursor(token: token, metadata: metadata, utf16Offset: utf16Offset)
				children.append(.token(tokenCursor))
			case .tree(let tree):
				let treeCursor = SyntaxTreeCursor(tree: tree, utf16Offset: utf16Offset)
				children.append(.tree(treeCursor))
			}

			utf16Offset += childNode.utf16Length
		}

		return children
	}()

	public private(set) lazy var subtrees: [SyntaxTreeCursor] = {
		children.compactMap(\.treeCursor)
	}()

	public var text: String { tree.text }
}

extension SyntaxTreeCursor.Child: Located {
	public var treeCursor: SyntaxTreeCursor? {
		switch self {
		case .tree(let cursor): cursor
		default: nil
		}
	}

	public var tokenCursor: SyntaxTokenCursor? {
		switch self {
		case .token(let cursor): cursor
		default: nil
		}
	}

	public var text: String {
		delocated.text
	}

	public var utf16Offset: Int {
		switch self {
		case .token(let syntaxTokenCursor): syntaxTokenCursor.utf16Offset
		case .tree(let syntaxTreeCursor): syntaxTreeCursor.utf16Offset
		}
	}

	public var utf16Length: Int {
		switch self {
		case .token(let syntaxTokenCursor): syntaxTokenCursor.utf16Length
		case .tree(let syntaxTreeCursor): syntaxTreeCursor.utf16Length
		}
	}
}

extension SyntaxTreeCursor.Child {
	var delocated: SyntaxTree.Child {
		switch self {
		case .token(let syntaxTokenCursor): .token(syntaxTokenCursor.token, metadata: syntaxTokenCursor.metadata)
		case .tree(let syntaxTreeCursor): .tree(syntaxTreeCursor.tree)
		}
	}
}

extension SyntaxTreeCursor {
	/// A sendable type capturing the initialisation parameters of a ``SyntaxCursor``.
	public struct Options: Sendable {
		let tree: SyntaxTree
		let utf16Offset: Int
		public init(tree: SyntaxTree, utf16Offset: Int) {
			self.tree = tree
			self.utf16Offset = utf16Offset
		}

		public var cursor: SyntaxTreeCursor {
			SyntaxTreeCursor(tree: tree, utf16Offset: utf16Offset)
		}
	}

	public var options: Options {
		Options(tree: tree, utf16Offset: utf16Offset)
	}
}

extension SyntaxTreeCursor {
	public func collectHints(sink: inout [(Range<Int>, String)], in range: Range<Int>) {
		guard range.overlaps(utf16Range) else { return }

		if let hint = tree.metadata?.hint {
			sink.append((utf16Range, hint))
		}

		for subtree in subtrees {
			subtree.collectHints(sink: &sink, in: range)
		}
	}
}