Add Special:DiscussionToolsDebug

It demonstrates how the DiscussionTools extension recognizes
the threads and comments present on a page, to help in debugging
or understanding its behavior.

Co-Authored-By: Ed Sanders <esanders@wikimedia.org>
Change-Id: Idbc90bd8d7742615178331889daae5f94a007fcc

DiscussionTools.alias.php

@@ -13,6 +13,7 @@ $specialPageAliases['en'] = [
 	'TopicSubscriptions' => [ 'TopicSubscriptions' ],
 	'FindComment' => [ 'FindComment' ],
 	'GoToComment' => [ 'GoToComment' ],
+	'DiscussionToolsDebug' => [ 'DiscussionToolsDebug' ],
 ];
 
 /** Czech (čeština) */

extension.json

@@ -35,6 +35,9 @@
 				"mobile"
 			]
 		},
+		"ext.discussionTools.debug.styles": {
+			"styles": "dt.debug.less"
+		},
 		"ext.discussionTools.init": {
 			"packageFiles": [
 				"dt.init.js",
@@ -397,6 +400,13 @@
 			"services": [
 				"DiscussionTools.ThreadItemStore"
 			]
+		},
+		"DiscussionToolsDebug": {
+			"class": "\\MediaWiki\\Extension\\DiscussionTools\\SpecialDiscussionToolsDebug",
+			"services": [
+				"ParserOutputAccess",
+				"DiscussionTools.CommentParser"
+			]
 		}
 	},
 	"Hooks": {

i18n/en.json

@@ -8,6 +8,9 @@
 	"discussiontools-autotopicsubpopup-preferences": "Edit preferences",
 	"discussiontools-autotopicsubpopup-title": "You have been subscribed",
 	"discussiontools-defaultsummary-reply": "Reply",
+	"discussiontoolsdebug-title": "Discussion tools data structure",
+	"discussiontoolsdebug-pagetitle": "Page title",
+	"discussiontoolsdebug-intro": "This page demonstrates how the [https://www.mediawiki.org/wiki/Special:MyLanguage/Extension:DiscussionTools DiscussionTools extension] recognizes the threads and comments present on the page '''[[:$1]]'''. You may find it useful in debugging issues with the extension or understanding how it works. The same information is available in the [[Special:ApiSandbox#action=discussiontoolspageinfo&prop=threaditemshtml&page=$1|discussiontoolspageinfo API]].",
 	"discussiontools-desc": "Tools to enhance discussion pages.",
 	"discussiontools-emptystate-button": "Start a discussion",
 	"discussiontools-emptystate-desc": "[[{{MediaWiki:discussiontools-emptystate-link-talkpages}}|Talk pages]] are where people discuss how to make content on {{SITENAME}} the best that it can be. You can use this page to start a discussion with others about how to improve [[:{{SUBJECTPAGENAME}}]].",

i18n/qqq.json

@@ -22,6 +22,9 @@
 	"discussiontools-autotopicsubpopup-preferences": "Label for a link to Special:Preferences",
 	"discussiontools-autotopicsubpopup-title": "Popup title",
 	"discussiontools-defaultsummary-reply": "Default edit summary for a reply.\n\n'''Note that this is a noun (''a reply''), not a verb (''to reply''). Alternatively you can use a past tense verb if that's more natural in your language.'''",
+	"discussiontoolsdebug-title": "Title of a special page",
+	"discussiontoolsdebug-pagetitle": "Form field label",
+	"discussiontoolsdebug-intro": "Message at the beginning of a special page",
 	"discussiontools-desc": "{{desc\n| name = DiscussionTools\n| url = https://www.mediawiki.org/wiki/Extension:DiscussionTools\n}}",
 	"discussiontools-emptystate-button": "Label for add new topic button on empty talk pages.",
 	"discussiontools-emptystate-desc": "Description of the purpose of talk pages, shown on empty talk pages. <code><nowiki>{{PAGENAME}}</nowiki></code> is a page title.\n\n'''Do not translate these magic words in this message:'''\n* <code><nowiki>{{SUBJECTPAGENAME}}</nowiki></code>\n* <code><nowiki>{{PAGENAME}}</nowiki></code>\n* <code><nowiki>{{MediaWiki:discussiontools-emptystate-link-talkpages}}</nowiki></code>",

includes/SpecialDiscussionToolsDebug.php

@@ -0,0 +1,158 @@
+<?php
+
+namespace MediaWiki\Extension\DiscussionTools;
+
+use FormSpecialPage;
+use Html;
+use MediaWiki\Extension\DiscussionTools\ThreadItem\ContentCommentItem;
+use MediaWiki\Extension\DiscussionTools\ThreadItem\ContentHeadingItem;
+use MediaWiki\Extension\DiscussionTools\ThreadItem\ContentThreadItem;
+use MediaWiki\Linker\Linker;
+use MediaWiki\Page\ParserOutputAccess;
+use MWTimestamp;
+use ParserOptions;
+use Title;
+use Wikimedia\Assert\Assert;
+use Wikimedia\Parsoid\Utils\DOMCompat;
+use Wikimedia\Parsoid\Utils\DOMUtils;
+
+class SpecialDiscussionToolsDebug extends FormSpecialPage {
+
+	private ParserOutputAccess $parserOutputAccess;
+	private CommentParser $commentParser;
+
+	public function __construct(
+		ParserOutputAccess $parserOutputAccess,
+		CommentParser $commentParser
+	) {
+		parent::__construct( 'DiscussionToolsDebug' );
+		$this->parserOutputAccess = $parserOutputAccess;
+		$this->commentParser = $commentParser;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function getDescription() {
+		return $this->msg( 'discussiontoolsdebug-title' )->text();
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	protected function getFormFields() {
+		return [
+			'pagetitle' => [
+				'label-message' => 'discussiontoolsdebug-pagetitle',
+				'name' => 'pagetitle',
+				'type' => 'title',
+				'required' => true,
+			],
+		];
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	protected function getSubpageField() {
+		return 'pagetitle';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	protected function getDisplayFormat() {
+		return 'ooui';
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function requiresPost() {
+		return false;
+	}
+
+	/**
+	 * @inheritDoc
+	 */
+	public function onSubmit( array $data ) {
+		$title = Title::newFromText( $data['pagetitle'] );
+
+		$status = $this->parserOutputAccess->getParserOutput(
+			$title->toPageRecord(),
+			ParserOptions::newFromAnon()
+		);
+		if ( !$status->isOK() ) {
+			return $status;
+		}
+
+		$parserOutput = $status->getValue();
+		$html = $parserOutput->getText();
+
+		$doc = DOMUtils::parseHTML( $html );
+		$container = DOMCompat::getBody( $doc );
+		$threadItemSet = $this->commentParser->parse( $container, $title->getTitleValue() );
+
+		$out = $this->getOutput();
+
+		$out->addHTML( $this->msg( 'discussiontoolsdebug-intro', $title->getPrefixedText() )->parseAsBlock() );
+
+		$pageLang = $title->getPageViewLanguage();
+		$pageLangAttribs = [
+			'lang' => $pageLang->getHtmlCode(),
+			'dir' => $pageLang->getDir(),
+			'class' => 'mw-content-' . $pageLang->getDir(),
+		];
+
+		foreach ( $threadItemSet->getThreads() as $thread ) {
+			$out->addHTML( $this->formatComments( $thread, $pageLangAttribs ) );
+		}
+
+		$out->addModuleStyles( 'ext.discussionTools.debug.styles' );
+
+		return true;
+	}
+
+	/**
+	 * Format a thread item with replies.
+	 *
+	 * @param ContentThreadItem $comment
+	 * @param array $pageLangAttribs
+	 * @return string HTML
+	 */
+	private function formatComments( ContentThreadItem $comment, array $pageLangAttribs ) {
+		if ( $comment instanceof ContentHeadingItem ) {
+			$contents = '<span class="mw-dt-heading">' . $comment->getHTML() . '</span>';
+		} else {
+			Assert::precondition( $comment instanceof ContentCommentItem, 'Must be ContentCommentItem' );
+			$contents =
+				'<span class="mw-dt-comment-signature">' .
+					'<span class="mw-dt-comment-author">' .
+						Linker::userLink( 0, $comment->getAuthor() ) .
+					'</span>' . ' ' .
+					'(' . Linker::userTalkLink( 0, $comment->getAuthor() ) . ') ' .
+					'<span class="mw-dt-comment-timestamp">' .
+						htmlspecialchars( $this->getLanguage()->getHumanTimestamp(
+							new MWTimestamp( $comment->getTimestamp()->getTimestamp() )
+						) ) .
+					'</span>' .
+				'</span>' .
+				Html::rawElement( 'div', $pageLangAttribs,
+					'<div class="mw-dt-comment-body mw-parser-output">' . $comment->getBodyHtml( true ) . '</div>'
+				);
+		}
+		$level = $comment->getLevel();
+
+		$replies = '';
+		foreach ( $comment->getReplies() as $reply ) {
+			$replies .= $this->formatComments( $reply, $pageLangAttribs );
+		}
+
+		return Html::rawElement( $replies ? 'details' : 'div', [
+			'open' => (bool)$replies,
+			'class' => 'mw-dt-comment',
+			'data-level' => $level,
+		], ( $replies ? Html::rawElement( 'summary', [], $contents ) : $contents ) . $replies );
+	}
+
+}

modules/dt.debug.less

@@ -0,0 +1,65 @@
+.mw-dt-heading {
+	font-size: 110%;
+	font-weight: bold;
+}
+
+.mw-dt-comment {
+	border: 1px solid #ccc;
+	border-radius: 3px;
+	padding: 5px;
+	margin-top: 0.5em;
+
+	> summary {
+		padding-left: 0.25em;
+
+		&:focus {
+			outline: 0;
+			background: #f0f3fc !important; /* stylelint-disable-line declaration-no-important */
+		}
+	}
+
+	> .mw-dt-comment {
+		margin-left: 1.5em;
+	}
+
+	&-body {
+		margin-left: 1.25em;
+		overflow: hidden;
+	}
+
+	> .mw-dt-comment[ data-level='1' ] {
+		margin-left: 0;
+	}
+
+	&-signature {
+		margin-left: 1.25em / 0.9;
+		font-size: 90%;
+		color: #666;
+
+		summary > & {
+			margin-left: 0.25em / 0.9;
+		}
+	}
+
+	&-author {
+		font-weight: bold;
+	}
+
+	[ data-level='1' ],
+	[ data-level='3' ],
+	[ data-level='5' ],
+	[ data-level='7' ],
+	[ data-level='9' ],
+	[ data-level='11' ] {
+		background: #f6f6f6;
+	}
+
+	[ data-level='0' ],
+	[ data-level='2' ],
+	[ data-level='4' ],
+	[ data-level='6' ],
+	[ data-level='8' ],
+	[ data-level='10' ] {
+		background: #fff;
+	}
+}