Merge "ImmutableRange: Add @property annotations for magic props"

includes/CommentFormatter.php

@@ -11,6 +11,8 @@ use ParserOutput;
 use Throwable;
 use Title;
 use WebRequest;
+use Wikimedia\Assert\Assert;
+use Wikimedia\Parsoid\DOM\Element;
 use Wikimedia\Parsoid\Utils\DOMCompat;
 use Wikimedia\Parsoid\Utils\DOMUtils;
 use Wikimedia\Parsoid\Wt2Html\XMLSerializer;
@@ -132,9 +134,12 @@ class CommentFormatter {
 			$itemJSON = json_encode( $itemData );
 
 			if ( $threadItem instanceof HeadingItem ) {
-				$threadItem->getRange()->endContainer->setAttribute( 'data-mw-comment', $itemJSON );
+				// <span class="mw-headline" …>, or <hN …> in Parsoid HTML
+				$headline = $threadItem->getRange()->endContainer;
+				Assert::precondition( $headline instanceof Element, 'HeadingItem refers to an element node' );
+				$headline->setAttribute( 'data-mw-comment', $itemJSON );
 				if ( $threadItem->isSubscribable() ) {
-					$headingNode = CommentUtils::closestElement( $threadItem->getRange()->endContainer, [ 'h2' ] );
+					$headingNode = CommentUtils::closestElement( $headline, [ 'h2' ] );
 
 					if ( $headingNode ) {
 						DOMCompat::getClassList( $headingNode )->add( 'ext-discussiontools-init-section' );

includes/CommentModifier.php

@@ -4,6 +4,7 @@ namespace MediaWiki\Extension\DiscussionTools;
 
 use MediaWiki\MediaWikiServices;
 use MWException;
+use Wikimedia\Assert\Assert;
 use Wikimedia\Parsoid\DOM\Document;
 use Wikimedia\Parsoid\DOM\DocumentFragment;
 use Wikimedia\Parsoid\DOM\Element;
@@ -151,6 +152,7 @@ class CommentModifier {
 			$target = $target->parentNode;
 		}
 
+		Assert::precondition( $target !== null, 'We have not stepped outside the document' );
 		// Instead of just using $curComment->getLevel(), consider indentation of lists within the
 		// comment (T252702)
 		$curLevel = CommentUtils::getIndentLevel( $target, $curComment->getRootNode() ) + 1;

includes/CommentParser.php

@@ -11,6 +11,7 @@ use Language;
 use MediaWiki\Languages\LanguageConverterFactory;
 use MWException;
 use Title;
+use Wikimedia\Assert\Assert;
 use Wikimedia\IPUtils;
 use Wikimedia\Parsoid\DOM\Element;
 use Wikimedia\Parsoid\DOM\Node;
@@ -930,6 +931,7 @@ class CommentParser {
 		} elseif ( $threadItem instanceof HeadingItem ) {
 			// <span class="mw-headline" …>, or <hN …> in Parsoid HTML
 			$headline = $threadItem->getRange()->startContainer;
+			Assert::precondition( $headline instanceof Element, 'HeadingItem refers to an element node' );
 			$id = 'h-' . $this->truncateForId( $headline->getAttribute( 'id' ) ?? '' );
 		} elseif ( $threadItem instanceof CommentItem ) {
 			$id = 'c-' . $this->truncateForId( str_replace( ' ', '_', $threadItem->getAuthor() ) ) .
@@ -944,6 +946,7 @@ class CommentParser {
 		if ( $threadItemParent instanceof HeadingItem && !$threadItemParent->isPlaceholderHeading() ) {
 			// <span class="mw-headline" …>, or <hN …> in Parsoid HTML
 			$headline = $threadItemParent->getRange()->startContainer;
+			Assert::precondition( $headline instanceof Element, 'HeadingItem refers to an element node' );
 			$id .= '-' . $this->truncateForId( $headline->getAttribute( 'id' ) ?? '' );
 		} elseif ( $threadItemParent instanceof CommentItem ) {
 			$id .= '-' . $this->truncateForId( str_replace( ' ', '_', $threadItemParent->getAuthor() ) ) .

includes/CommentUtils.php

@@ -349,7 +349,7 @@ class CommentUtils {
 	 * Get an array of sibling nodes that contain parts of the given range.
 	 *
 	 * @param ImmutableRange $range
-	 * @return Element[]
+	 * @return Node[]
 	 */
 	public static function getCoveredSiblings( ImmutableRange $range ): array {
 		$ancestor = $range->commonAncestorContainer;
@@ -385,7 +385,7 @@ class CommentUtils {
 	 * Get the nodes (if any) that contain the given thread item, and nothing else.
 	 *
 	 * @param ThreadItem $item
-	 * @return Element[]|null
+	 * @return Node[]|null
 	 */
 	public static function getFullyCoveredSiblings( ThreadItem $item ): ?array {
 		$siblings = self::getCoveredSiblings( $item->getRange() );

includes/HeadingItem.php

@@ -2,6 +2,9 @@
 
 namespace MediaWiki\Extension\DiscussionTools;
 
+use Wikimedia\Assert\Assert;
+use Wikimedia\Parsoid\DOM\Element;
+
 class HeadingItem extends ThreadItem {
 	private $placeholderHeading = false;
 	private $headingLevel;
@@ -40,6 +43,7 @@ class HeadingItem extends ThreadItem {
 		if ( !$this->isPlaceholderHeading() ) {
 			// <span class="mw-headline" …>, or <hN …> in Parsoid HTML
 			$headline = $this->getRange()->startContainer;
+			Assert::precondition( $headline instanceof Element, 'HeadingItem refers to an element node' );
 			$id = $headline->getAttribute( 'id' );
 			if ( $id ) {
 				// Replace underscores with spaces to undo Sanitizer::escapeIdInternal().

includes/ImmutableRange.php

@@ -18,6 +18,13 @@ use Wikimedia\Parsoid\DOM\Text;
  * which is lazy evaluated.
  *
  * setStart and setEnd are still available but return a cloned range.
+ *
+ * @property bool $collapsed
+ * @property Node $commonAncestorContainer
+ * @property Node $endContainer
+ * @property int $endOffset
+ * @property Node $startContainer
+ * @property int $startOffset
  */
 class ImmutableRange {
 	private $mCommonAncestorContainer;

modules/utils.js

@@ -302,7 +302,7 @@ function getIndentLevel( node, rootNode ) {
  * Get an array of sibling nodes that contain parts of the given range.
  *
  * @param {Range} range
- * @return {HTMLElement[]}
+ * @return {Node[]}
  */
 function getCoveredSiblings( range ) {
 	var ancestor = range.commonAncestorContainer;
@@ -336,7 +336,7 @@ function getCoveredSiblings( range ) {
  * Get the nodes (if any) that contain the given thread item, and nothing else.
  *
  * @param {ThreadItem} item Thread item
- * @return {HTMLElement[]|null}
+ * @return {Node[]|null}
  */
 function getFullyCoveredSiblings( item ) {
 	var siblings = getCoveredSiblings( item.getNativeRange() );