DNM: Add WikibaseQualityConstraints

dist-persist/wbstack/src/Settings/LocalSettings.php

@@ -360,6 +360,8 @@
 wfLoadExtension( 'DeleteBatch' );
 wfLoadExtension( 'MultimediaViewer' );
 wfLoadExtension( 'WikiHiero' );
+wfLoadExtension( 'WikibaseQualityConstraints' );
+
 
 # ConfirmAccount (only loaded when the setting is on)
 if( $wikiInfo->getSetting('wwExtEnableConfirmAccount') ) {

dist/extensions/WikibaseQualityConstraints/.coveralls.yml

@@ -0,0 +1,2 @@
+coverage_clover: build/logs/clover.xml
+service_name: travis-ci

dist/extensions/WikibaseQualityConstraints/.mailmap

@@ -0,0 +1,18 @@
+Aleksey Bekh-Ivanov <[email protected]>
+Amir E. Aharoni <[email protected]>
+Andreas Burmeister <[email protected]>
+Dimitri Schmidt <[email protected]>
+Dominic Sauer <[email protected]>
+Jan Zerebecki <[email protected]>
+Jeroen De Dauw <[email protected]>
+Jonas Keutel <[email protected]> <[email protected]>
+Jonas Kress <[email protected]>
+Katie Filbert <[email protected]>
+Lucas Werkmeister <[email protected]>
+Olga Bode <[email protected]>
+Sam Reed <[email protected]>
+Sören Oldag <[email protected]>
+Tamara Slosarek <[email protected]>
+Thiemo Kreuz <[email protected]>
+Thiemo Kreuz <[email protected]> <[email protected]>
+Timo Tijhof <[email protected]>

dist/extensions/WikibaseQualityConstraints/CODE_OF_CONDUCT.md

@@ -0,0 +1 @@
+The development of this software is covered by a [Code of Conduct](https://www.mediawiki.org/wiki/Special:MyLanguage/Code_of_Conduct).

dist/extensions/WikibaseQualityConstraints/README.md

@@ -0,0 +1,254 @@
+# Wikibase Quality Constraints
+[![Scrutinizer Code Quality][scrutinizer-badge]][scrutinizer]
+
+Extension to Wikibase Repository that performs constraint checks.
+
+[scrutinizer-badge]: https://scrutinizer-ci.com/g/wikimedia/mediawiki-extensions-WikibaseQualityConstraints/badges/quality-score.png?b=master
+[scrutinizer]: https://scrutinizer-ci.com/g/wikimedia/mediawiki-extensions-WikibaseQualityConstraints/?branch=master
+
+## Installation
+
+* Clone `WikibaseQualityConstraints` inside the `extensions/` directory of your MediaWiki installations.
+
+  ``` sh
+  cd .../extensions/
+  git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/WikibaseQualityConstraints
+  ```
+
+* Install dependencies.
+  The simplest way is to set up [composer-merge-plugin](https://www.mediawiki.org/wiki/Composer#Using_composer-merge-plugin)
+  and then run `composer install` in the MediaWiki base directory;
+  alternatively, you can run `composer install` inside the `WikibaseQualityConstraints` directory.
+
+* Load the extension.
+
+  ```php
+  wfLoadExtension( 'WikibaseQualityConstraints' );
+  ```
+
+* Run `php maintenance/update.php --quick`.
+
+* Configure the extension.
+  You can find the configuration settings with documentation in `extension.json`.
+  (Note that the variable name for `LocalSettings.php` always begins with `wg`,
+  e. g. `$wgWBQualityConstraintsClassId` for the `WBQualityConstraintsClassId` setting.)
+
+  * Specify the entity IDs of entities that are used to define constraints.
+    See the “Data import” section for an automatic way to do this.
+
+  * If you have a SPARQL endpoint, configure it in `WBQualityConstraintsSparqlEndpoint`.
+
+  * Alternatively, to check “format” constraints without running a full SPARQL server,
+    you can use the [minisparql] server.
+
+* Run `php maintenance/runScript.php extensions/WikibaseQualityConstraints/maintenance/ImportConstraintStatements.php`.
+
+[minisparql]: https://github.com/lucaswerkmeister/minisparql
+
+### Client-side script
+
+The extension includes a client-side script that checks constraints on entity pages and displays violations on statements.
+It is loaded by default for all logged-in users;
+anonymous users can load it on a page by entering the following code into the web console:
+
+```js
+mw.loader.load( 'wikibase.quality.constraints.gadget' );
+```
+
+### Data import
+
+For local development, it’s easiest to import some data from Wikidata.
+You can use the `ImportConstraintEntities` maintenance script script to do this;
+it will import all the required entities from Wikidata that don’t exist in your local wiki yet
+and then print a config snippet which you can append to your `LocalSettings.php`.
+
+```sh
+# working directory should be the MediaWiki installation folder, i.e. where LocalSettings.php is
+php extensions/WikibaseQualityConstraints/maintenance/ImportConstraintEntities.php | tee -a LocalSettings.php
+```
+
+(The new entities will not show up in your wiki’s recent changes until they have been processed in the job queue;
+try running the `maintenance/runJobs.php` script if it doesn’t happen automatically.)
+
+### Running the tests
+
+#### PHP
+
+There are two ways to run the tests of this extension:
+
+- Using the included configuration file:
+
+  ```sh
+  # from the MediaWiki installation folder
+  php tests/phpunit/phpunit.php -c extensions/WikibaseQualityConstraints/phpunit.xml.dist
+  ```
+
+  This creates test coverage reports
+  (in `tests/coverage/` and `build/logs/clover.xml`)
+  and is therefore fairly slow.
+
+- Without the configuration file:
+
+  ```sh
+  # from the MediaWiki installation folder
+  php tests/phpunit/phpunit.php extensions/WikibaseQualityConstraints/tests/phpunit/
+  ```
+
+  This runs the tests without coverage report
+  and is therefore much faster.
+
+#### Javascript
+
+You can run the tests, combined with linting and few other tools for asserting code quality by
+
+```sh
+  # from this extension's folder
+  npm install
+  grunt test
+```
+
+### Adding a new constraint type
+
+To add a new constraint type, the following steps are necessary:
+
+* Define the constraint checker class.
+  * It should be defined in a new file in `src/ConstraintCheck/Checker/`,
+    named after the class name.
+    It should be in the `WikibaseQuality\ConstraintReport\ConstraintCheck\Checker` namespace.
+  * The class name should follow the constraint type name (in English), ending in “Checker”.
+  * The class must implement the `ConstraintChecker` interface.
+  * It should have at least the following class-level documentation comment:
+    ```php
+    /**
+     * @author YOUR NAME HERE
+     * @license GPL-2.0-or-later
+     */
+    ```
+  * Any services you need (`Config`, `EntityLookup`, …) should be injected as constructor parameters.
+  * If the constraint has parameters,
+    add support for parsing them to `ConstraintParameterParser`
+    (add a config setting for the associated property in `extension.json`
+    and a method to parse the parameter in `ConstraintParameterParser`),
+    and then add tests for them in `ConstraintParameterParserTest`.
+    This should be done in a separate commit.
+* Define new messages (at least a violation message for the constraint type).
+  * Define the message in `i18n/en.json`.
+    A violation message should have a key like `wbqc-violation-message-constraintType`.
+  * Document the message in `i18n/qqq.json`.
+    Use the same message key,
+    and insert the documentation in the same location where you also added the message in `en.json`
+    (that is, `en.json` and `qqq.json` should contain message keys in the same order).
+* Add a configuration setting for the constraint type item ID.
+  * Configuration settings are defined in `extension.json`,
+    as members of the `config` object.
+  * It should be added right after the current last `…ConstraintId` entry.
+  * It should be named after the constraint type item’s English label,
+    following the pattern `WBQualityConstraints…ConstraintId`.
+  * The default value should be the item ID on Wikidata,
+    so that no extra configuration is required for Wikidata
+    and importing the constraint type item (see “Data import” section) works.
+  * The first part of the description can be copied from similar settings,
+    the rest should contain a short description of the constraint type.
+  * The ID can always be public (`"public": true`).
+* Register the new constraint type checker.
+  * In `ConstraintCheckerServices.php`, add a constant like
+    ```php
+    public const …_CHECKER = 'WBQC_…Checker';
+    ```
+    at the end of the list of constants.
+    The value should be `'WBQC_'` followed by the class name,
+    and the constant name should be the class name converted to all caps separated by underscores.
+  * Also in `ConstraintCheckerServices.php`, add a method like
+    ```php
+    /**
+     * @param MediaWikiServices|null $services
+     * @return ConstraintChecker
+     */
+    public static function get…Checker( MediaWikiServices $services = null ) {
+    	return self::getService( $services, self::…_CHECKER );
+    }
+    ```
+    at the end of the class.
+  * In `ServiceWiring-ConstraintCheckers.php`, append a new function like
+    ```php
+    ConstraintCheckerServices::…_CHECKER => function( MediaWikiServices $services ) {
+    	return new …Checker(
+        	// injected services
+        );
+    },
+    ```
+    to the array of services.
+  * In `ServiceWiring.php`, append a new entry like
+    ```php
+    $config->get( 'WBQualityConstraints…ConstraintId' )
+    	=> ConstraintCheckerServices::get…Checker( $services ),
+    ```
+    to the `$checkerMap` array in the `DELEGATING_CONSTRAINT_CHECKER` function.
+  * In `ServicesTest.php`, append a new entry like
+    ```php
+    [ …Checker::class ],
+    ```
+    to the array in `provideConstraintCheckerServiceClasses()`.
+* Add tests for the new constraint checker.
+  * The test class name should be the same as the checker class name,
+    with an additional suffix `Test` (i. e., `…CheckerTest`).
+  * The test class should be placed somewhere in `tests/phpunit/Checker/`,
+    either in the most suitable subdirectory
+    or directly in that directory if none of the subdirectories are suitable.
+    (The division into subdirectories there is dubious anyways,
+    and we may get rid of it in the future.)
+  * It should have at least the following class-level documentation comment:
+    ```php
+    /**
+     * @covers WikibaseQuality\ConstraintReport\ConstraintCheck\Checker\…Checker
+     *
+     * @group WikibaseQualityConstraints
+     *
+     * @author YOUR NAME HERE
+     * @license GPL-2.0-or-later
+     */
+    ```
+  * It should have at least one test for compliance with a constraint,
+    one test for a constraint violation,
+    one test for behavior on a deprecated statement,
+    and one test for the `checkConstraintParameters` method.
+  * Use the `ResultAssertions` trait’s methods to check constraint check results.
+  * Use the `NewItem` and `NewStatement` builders to construct test data.
+    (You might see `JsonFileEntityLookup` and separate JSON files used in some existing tests,
+    but that’s a lot less readable.)
+  * If the checker uses a `Config`, use the `DefaultConfig` trait.
+  * If the constraint has parameters,
+    add methods for them to the `ConstraintParameters` trait and use it in the tests.
+  * You can copy+paste a `getConstraintMock` function from one of the existing tests,
+    adjusting the `getConstraintTypeItemId` mocked return value.
+    (Hopefully we’ll improve this in the future.)
+* Update the tests for `DelegatingConstraintChecker`.
+    * In `DelegatingConstraintCheckerTest`,
+      add an entry for your constraint type to the `$constraints` array in `addDBData()`.
+    * The `constraint_guid` should be `P1$`,
+      followed by a new UUID (e. g. `cat /proc/sys/kernel/random/uuid` or `journalctl --new-id128`).
+    * The `pid` should be `1`. (Not `'1'`!)
+    * The `constraint_type_qid` should be `$this->getConstraintTypeItemId( '…' )`,
+      where `…` is just the `…` part of the `WBQualityConstraints…ConstraintId` `extension.json` config key.
+    * The `constraint_parameters` should be a valid JSON serialization of constraint parameters.
+      If the constraint type doesn’t have any parameters, you can pass `{}`,
+      otherwise there should ideally be methods to create the parameters in the `ConstraintParameters` trait
+      so that you can use `json_encode( $this->…Parameter( … ) )`
+      (perhaps with `array_merge` if there are multiple parameters).
+* Ask someone with grafana-admin access to update the “constraint types” panel
+  in the [wikidata-quality board](https://grafana.wikimedia.org/dashboard/db/wikidata-quality)
+  to add the new constraint type.
+
+### Adding a new allowed entity type
+
+* Start by adding an Item reference to `extension.json`. For example:
+ 	```
+ 	"WBQualityConstraintsMediaInfoId": {
+        "value": "Q3898244",
+        "description": "The item ID of the 'MediaInfo' item, which represents the 'mediainfo' entity type for 'allowed entity types' constraints.",
+        "public": true
+    }
+ * The next step takes place inside `src/ConstraintCheck/Helper/ConstraintParameterParser.php`. The new allowed entity type
+ should be added to the switch/case within the method `parseEntityTypeItem()`.
+ Don't forget to add it to the default case as well!
+ * To be able to test the newly added allowed entity type locally, please perform the steps described in section "Data import".

dist/extensions/WikibaseQualityConstraints/WikibaseQualityConstraints.alias.php

@@ -0,0 +1,15 @@
+<?php
+/**
+ * Aliases for WikibaseQualityConstraints extension
+ *
+ * @file
+ * @ingroup Extensions
+ * @license GPL-2.0-or-later
+ */
+
+$specialPageAliases = [];
+
+/** English (English) */
+$specialPageAliases['en'] = [
+	'ConstraintReport' => [ 'ConstraintReport', 'Constraint Report' ],
+];

dist/extensions/WikibaseQualityConstraints/composer.json

@@ -0,0 +1,55 @@
+{
+	"name": "wikibase/constraints",
+	"type": "mediawiki-extension",
+	"description": "Extension to manage constraints in Wikibase.",
+	"keywords": [
+		"quality",
+		"trust",
+		"violation",
+		"constraint",
+		"wikibase",
+		"wikidata"
+	],
+	"homepage": "https://www.mediawiki.org/wiki/Wikibase_Quality_Extensions",
+	"license": "GPL-2.0-or-later",
+	"authors": [
+		{
+			"name": "BP2014N1"
+		}
+	],
+	"support": {
+		"issues": "https://phabricator.wikimedia.org/project/profile/1202/"
+	},
+	"require": {
+		"php": ">=7.2.0",
+		"serialization/serialization": "^3.2.1|^4.0.0",
+		"data-values/data-values": "^2.0.0|^1.0.0",
+		"data-values/common": "^0.4.0|^0.3.0",
+		"data-values/geo": "^4.2.1|^3.0.1|^2.1.2",
+		"data-values/number": "^0.11.0",
+		"data-values/time": "^1.0.1",
+		"data-values/serialization": "^1.2.1",
+		"wikimedia/purtle": "^1.0.7"
+	},
+	"require-dev": {
+		"mediawiki/mediawiki-codesniffer": "39.0.0",
+		"mediawiki/mediawiki-phan-config": "0.11.1",
+		"mediawiki/minus-x": "1.1.1",
+		"php-parallel-lint/php-console-highlighter": "1.0.0",
+		"php-parallel-lint/php-parallel-lint": "1.3.2"
+	},
+	"scripts": {
+		"fix": [
+			"minus-x fix .",
+			"phpcbf"
+		],
+		"test": [
+			"composer validate --no-interaction",
+			"parallel-lint . --exclude vendor --exclude node_modules",
+			"@phpcs",
+			"minus-x check ."
+		],
+		"phan": "phan -d . --long-progress-bar --allow-polyfill-parser",
+		"phpcs": "phpcs -sp --cache"
+	}
+}