Редактирование: Тептар:Глобальный код/Автоматическая проверка соответствия критериям

'''[[MediaWiki:Script/criteriaCheck.js|criteriaCheck.js]]''' — скрипт для автоматической проверки соответствия тем или иным критериям на выборах, в голосованиях, при присвоении флагов и в иных случаях.

В скрипте задан набор [[#Критерии|методов]], позволяющих проверять участников на соответствие разнообразным критериям. При помощи <code>[[#criteriaCheck.addHandler|criteriaCheck.addHandler()]]</code> можно добавить свои методы. Если проверяемая учётная запись была переименована впоследствии, скрипт это учтёт.

Для проверки на соответствие некоторым критериям (например, учитывающим [[Special:DeletedContributions|удалённый вклад]]) требуются права администратора или арбитра.

== Подключение ==
Чтобы скрипт вызывался у всех пользователей на определённой странице, добавьте в неё код {{tlc|выполнить скрипт|criteriaCheck}}.

Чтобы вызвать скрипт из другого скрипта, используйте
<syntaxhighlight lang="js">
mw.loader.getScript('https://ru.wikipedia.org/w/index.php?title=MediaWiki:Script/criteriaCheck.js&action=raw&ctype=text/javascript').done(function () {
	// ...
});
</syntaxhighlight>

Чтобы вызвать скрипт только для вас на произвольной странице, запустите код выше в консоли браузера.

== Объект criteriaCheck ==
Скрипт создаёт в глобальной области видимости объект <code>criteriaCheck</code> со следующими свойствами/методами:
{| class="wikitable ts-propertiesTable"
|+ Свойства
! Свойство
! Тип
! Описание
|-
| apiRateLimit
| число
| Максимальное число рядов, которое можно получать в результате запросов к API. Это число равно 5000 у участников, [[Служебная:Права групп участников|обладающих]] правом <code>apihighlimits</code>, и 500 у всех остальных. Заполняется при первой проверке соответствия критерию.
|-
| currentUser
| User
| Участник, от имени которого выполняется скрипт.
|-
| util
| объект
| Набор утилитарных методов, которые могут использоваться в методах [[#Критерии|критериев]] или в [[#Применения|применениях]].
|-
| style="font-family: inherit;" | свойства по случаям применения (<code>admin</code>, <code>arbcom</code>)
| объект
| Объекты [[#Применения|применений]]. Они содержат свойства и методы по каждому из случаев применения.
|}

{{Таблица свойств объекта JavaScript}}
{| class="wikitable ts-propertiesTable"
|+ Методы
! Метод
! Тип возвращаемого значения
! Описание
|-
| {{якорь|criteriaCheck.addHandler}}addHandler(criterionType, handler)
| ''нет''
| Добавить метод для проверки соответствия критерию. <code>criterionType</code> — тип критерия, для которого будет вызываться этот метод (один тип — один метод), <code>handler</code> — метод. Метод должен получать на вход [[#criteriaCheck.getUser|объект участника]] и [[#Критерии|объект критерия]] (его можно назвать <code>options</code>) и возвращать [[#Объект результата|объект результата]].
|-
| <source lang="js" inline style="border:0; padding:0; color:#202122;">check(userNames, criteria, [options])</source>
| массив объектов
| Проверить список пользователей на соответствие критериям. Аргументы:
* <code>userNames</code> (массив строк или строка) — список имён участников или одно имя.
* <code>criteria</code> (массив объектов или объект) — набор [[#Критерии|критериев]] или один критерий.
* <code>options</code> (объект) — набор опций:
** <code>namesAsOf</code> (дата) — считать имена участников актуальными на данную дату (параметр служит для правильной обработки переименований учётных записей).
** <code>callback</code> (функция) — колбэк, вызываемый после обработки результата для каждого участника и получающий в качестве аргумента этот результат.
** <code>doSummarize</code> (булево значение) — пропускать ли каждый результат через функцию <code>criteriaCheck.summarize()</code> (см. ниже). По умолчанию <source lang="js" inline>true</source>.

Возвращает массив [[#Объект результата|объектов результата]].
|-
| createMessage(message, [anchor])
| jQuery
| Сформировать сообщение (например, о соответствии/несоответствии критериям), которое можно вывести на странице. <code>message</code> — объект, содержащий свойства:
* <code>icons</code> (массив строк) или <code>icon</code> (строка) — имена иконок из следующего перечня: <code>check</code>, <code>close</code>, <code>help</code>, <code>error</code>, <code>warning</code>, <code>loading</code>.
* <code>texts</code> (массив строк) или <code>text</code> (строка или объект jQuery) — HTML-коды сообщений. Если их несколько, они нумеруются.
* <code>accented</code> (булево значение) — приводит к выделению сообщения полужирным шрифтом.
* <code>big</code> (булево значение) — приводит к использованию шрифта большего кегля в сообщении.

<code>anchor</code> — название якоря элемента сообщения (содержимое атрибута <code>id</code>).
|-
| {{якорь|criteriaCheck.getUser}}getUser(name, nameAsOf)
| User
| Получить объект участника по его имени. Переименования учётных записей здесь не учитываются (каждому имени соответствует собственный экземпляр объекта User). Параметр <code>nameAsOf</code> (дата, на которую актуально имя) позволяет впоследствии правильно обрабатывать переименования учётных записей, но пока невозможно иметь двух участников с одинаковыми именами, но на разную дату. Свойство <code>name</code> будет содержать имя участника. Тот факт, что участник был переименован, отразится в том, что это свойство будет не равно значению аргумента <code>name</code> рассматриваемого метода. Тот факт, что участник с таким именем не найден, отразится в значении <source lang="js" inline>true</source> свойства <code>missing</code> после вызова метода <code>registrationDateNotLater()</code> или <code>getUserInfo()</code> у экземпляра объекта User.
|-
| {{якорь|criteriaCheck.extractCriteria}}extractCriteria($container)
| массив объектов
| Извлечь критерии, записанные как атрибуты <code>data-</code> (см. [[#Критерии]]), из содержимого контейнера (объект jQuery).
|-
| summarize(results)
| объект
| Резюмировать, соответствует ли участник критериям, на основе нескольких [[#Объект результата|объектов результата]]. <code>results</code> — массив с объектами результата. Возвращает объект со свойствами:
* <code>conclusion</code> (значения <code>meets</code>, <code>notMeets</code>, <code>possiblyMeets</code> или <code>userMissing</code>),
* <code>results</code> (тот же объект, что передаётся в аргументе),
* <code>warnings</code>,
* <code>user</code>.
|}

== Критерии ==
Для указания набора критериев используются массивы с объектами критериев. Каждый объект критерия должен содержать свойства:
* <code>type</code> — тип критерия, он же метод, используемый для проверки, например <code>editCountNotLess</code>. Список типов критериев см. в таблице ниже.
** Это свойство может отсутствовать, а вместо него может присутствовать свойство <code>needsManualCheck</code> со значением <source lang="js" inline>true</source>. Если скрипт встретит такое свойство, он не будет осуществлять проверку, а просто выдаст <code>needsManualCheck</code> в свойстве <code>result</code> [[#Объект результата|объекта результата]].
* <code>text</code> — текст критерия, например <code>сделал в Тептар не менее 2000 правок до момента начала номинации</code>.
* Свойства, соответствующие параметрам типов критериев (см. в таблице).

Список методов, которые могут быть использованы «из коробки»:
{| class="wikitable ts-propertiesTable"
! Тип критерия
! Описание
! Параметры
|-
| actionCountNotLess
| Число действий не менее указанного.
* Число правок считается на основе вклада. Не учитываются правки на страницах, использующих [[Тептар:Structured Discussions|Structured Discussions]] (это бы требовало совершения лишнего запроса, а Structured Discussions в нашем разделе не был введён иначе, кроме как для экспериментов).
* Удалённый вклад по умолчанию учитывается. Чтобы отключить это, задайте <source lang="js" inline>false</source> параметру <code>deleted</code>.
* Исключаются автоматические действия, а именно действия со следующими кодами: <code>approve-a</code>, <code>approve-ia</code>, <code>approve2-a</code>, <code>approve2-ia</code>, <code>thank</code>, <code>hit</code> (такой код имеют действия типов <code>spamblacklist</code> и <code>abusefilter</code>), <code>move</code>, <code>move_redir</code>, <code>move_prot</code>, <code>delete_redir</code>, <code>renameuser</code>, <code>autopromote</code>, <code>autopatrol</code>, <code>create</code> (тип действия тоже должен быть <code>create</code>), все действия типа <code>newusers</code>. Cм. [[mw:API:Logevents]], [[Тептар:Патрулирование#Обозначения действий патрулирования в API]].

Вместе с результатом проверки возвращается число полученных действий в свойстве <code>actionCount</code> (если это число больше необходимого для соответствия критерию, оно может быть меньше общего числа действий в указанный период, так как нет нужды запрашивать с сервера ещё).
|
* <code>value</code> (число) — необходимое число правок.
* <code>periodStart</code> (дата) — дата начала периода{{efn|name=*|См. [[#Периоды времени]].}}.
* <code>periodEnd</code> (дата) — дата конца периода{{efn|name=*}}.
* Также могут использоваться параметры для типа критерия <code>editCountNotLess</code>: они будут применяться к правкам.
|-
| editCountNotLess
| Число правок не менее указанного. Число правок считается на основе вклада. Если параметр <code>deleted</code> не равен <source lang="js" inline>true</source>, удалённый вклад не учитывается. Не учитываются правки на страницах, использующих [[Тептар:Structured Discussions|Structured Discussions]] (это бы требовало совершения лишнего запроса, а Structured Discussions в нашем разделе не был введён иначе, кроме как для экспериментов).

Вместе с результатом проверки возвращается число полученных правок в свойстве <code>editCount</code> (если это число больше необходимого для соответствия критерию, оно может быть меньше общего числа правок в указанный период, так как нет нужды запрашивать с сервера ещё).
|
* <code>value</code> (число) — необходимое число правок.
* <code>periodStart</code> (дата) — дата начала периода{{efn|name=*|См. [[#Периоды времени]].}}.
* <code>periodEnd</code> (дата) — дата конца периода{{efn|name=*}}.
* <code>ns</code> (число) — считать только правки в данном пространстве имён.
* <code>deleted</code> (булево значение) — учитывать [[Special:DeletedContributions|удалённый вклад]] (требует прав администратора или арбитра).
* <code>meaningful</code> (булево значение) — должны учитываться только осмысленные/значительные правки. Так как автоматически это проверить нельзя, метод будет возвращать результат <code>possiblyMeets</code> вместо <code>meets</code>, если число правок меньше значения, в 1,5 раз большего необходимого числа правок (например, если требуется 100 правок, то <code>possiblyMeets</code> будет возвращаться для числа правок от 100 до 149).
|-
| editsBetweenDates
| Есть хотя бы одна правка в промежутке между двумя датами.
|
* <code>periodStart</code> (дата) — дата начала периода{{efn|name=*}}.
* <code>periodEnd</code> (дата) — дата конца периода{{efn|name=*}}.
|-
| hadFlagFor
| Участник обладал указанным(-и) флагом(-ами) в течение как минимум указанного периода времени на указанный момент.

Если участник обладал флагом в течение единственного (непрерывного) периода времени, разница в N месяцев и лет в том случае, когда в другом месяце или годе нет соответствующего числа, вычисляется так: 31 марта − 1 месяц = 28 февраля. Если участник обладал флагом в течение нескольких периодов и то, обладал ли участник флагом в течение этого периода, может зависеть от трактовки месяцев и лет, возвращается значение <code>possiblyMeets</code>.

Вместе с результатом проверки возвращается название флага и период в миллисекундах в свойствах <code>flag</code> и <code>period</code> соответственно.
|
* <code>flags</code> (массив строк) или <code>flag</code> (строка) — названия флагов согласно базе данных (например, администратор — <code>sysop</code>; чтобы узнать название, выберите флаг на странице [[Служебная:Список участников]] и посмотрите значение параметра ''group'' в URL).
* <code>value</code> (число) — период времени, в течение которого участник должен обладать флагом.
* <code>unit</code> (строка) — единица измерения (<code>day</code>, <code>month</code> или <code>year</code>).
* <code>referenceDate</code> (дата) — дата, на которую проверяется истинность утверждения{{efn|name=*}}.
|-
| noActiveBlockBetweenDates
| Участник не имеет активных блокировок, период действия которых включает указанный период.
|
* <code>periodStart</code> (дата) — дата начала периода{{efn|name=*}}.
* <code>periodEnd</code> (дата) — дата конца периода{{efn|name=*}}.
* <code>ns</code> (число) — если нужно также учитывать частичные блокировки, укажите пространство имён, на которое должна распространяться блокировка, чтобы участник не соответствовал критерию.
|-
| notInactiveFor
| Участник не имел периодов неактивности длиннее указанного периода времени между указанными датами.
|
* <code>value</code> (число) — минимальный период времени, в течение которого участник должен быть неактивен, чтобы не соответствовать критерию.
* <code>unit</code> (строка) — единица измерения (<code>day</code>, <code>month</code> или <code>year</code>).
* <code>periodStart</code> (дата) — дата начала периода, активность внутри которого требуется изучить{{efn|name=*}}.
* <code>periodEnd</code> (дата) — дата конца периода, активность внутри которого требуется изучить{{efn|name=*}}.
* <code>deleted</code> (булево значение) — учитывать [[Special:DeletedContributions|удалённый вклад]] (по умолчанию <source lang="js" inline>true</source>, требует прав администратора или арбитра).
|-
| notLostFlagInLast
| Участник не потерял один из указанных флагов в указанном промежутке времени. Вместе с результатом проверки в случае несоответствия критерию возвращается название потерянного флага и дата потери в свойствах <code>flag</code> и <code>lostFlagTimestamp</code> соответственно.
|
* <code>flags</code> (массив строк) или <code>flag</code> (строка) — названия флагов согласно базе данных (например, администратор — <code>sysop</code>; чтобы узнать название, выберите флаг на странице [[Служебная:Список участников]] и посмотрите значение параметра ''group'' в URL).
* <code>value</code> (число) — период времени, в течение которого участник должен не потерять флаг.
* <code>unit</code> (строка) — единица измерения (<code>day</code>, <code>month</code> или <code>year</code>).
* <code>referenceDate</code> (дата) — дата, от которой нужно отсчитывать период времени{{efn|name=*}}.
|-
| registrationDateNotLater
| Дата регистрации не позже указанной. Для участников, зарегистрировавшихся ранее 2 декабря 2005 года, берётся дата первой правки (даты регистрации в базе данных у них нет). Вместе с результатом проверки возвращается дата регистрации, а также общее число правок согласно внутреннему счётчику (не вкладу) в свойствах <code>registrationDate</code> и <code>overallEditCount</code> соответственно.
|
* <code>value</code> (число) — дата регистрации{{efn|name=*}}.
|}

{{notelist}}

=== Периоды времени ===
Все начальные даты периодов считаются включительно, а конечные (к ним относится и дата регистрации при обработке критериев типа <code>registrationDateNotLater</code>) — невключительно. Исключение — даты, [[#Указание критериев в HTML-коде|переданные в качестве строк в HTML-коде]] и не содержащие времени, в случае которых конечные даты тоже считаются включительно. Например, если начальная и конечная дата — <source lang="js" inline>new Date('2019-01-01')</source> и <source lang="js" inline>new Date('2019-02-01')</source> соответственно, в период будут входить даты, начиная с 1 января 2019 года 0:00:00 и кончая 31 января 2019 года 23:59:59. Если же конечная дата указана в HTML-коде как <code>2019-02-01</code> (например, <code>data-period-end="2019-02-01"</code>), то конечной датой будет 1 февраля 2019 года 23:59:59.

=== Указание критериев в HTML-коде ===
При указании критериев в HTML-коде оберните все их в контейнер, присвоив ему определённый класс (например, <code>criteriaCheck-criteria</code>).

Текст каждого критерия оберните в тег (например, {{tag|span}}), у которого задайте атрибут <code>data-criterion</code> с названием типа критерия. В прочих атрибутах <code>data-</code> задайте параметры. Дату записывайте в формате <code>ГГГГ-ММ-ДД [ЧЧ:ММ:СС]</code>. Если время не указано, конечные даты периодов [[#Периоды времени|будут считаться включительно]].

Пример того, как это может быть сделано, см. [[Тептар:Заявки на статус администратора/Шаблон требований к голосующим|здесь]].

Для извлечения критериев из HTML-кода используйте метод <code>[[#criteriaCheck.extractCriteria|criteriaCheck.extractCriteria()]]</code>.

=== Объект результата ===
Каждый метод, соответствующий типу критерия, возвращает объект результата. Он содержит свойство <code>result</code> (с одной из следующих строк: <code>meets</code>, <code>notMeets</code>, <code>possiblyMeets</code>, <code>notEnoughRights</code>, <code>userMissing</code>, <code>needsManualCheck</code>), а также дополнительные свойства, которые может записывать метод.

== Применения ==
Каждое применение получает объект, являющийся свойством объекта <code>criteriaCheck</code>. На страницах выборов администраторов, бюрократов и конфирмации используется объект <code>criteriaCheck.admin</code>.

К выборам Арбитражного комитета относится объект <code>criteriaCheck.arbcom</code>. Так, чтобы получить набор критериев для голосующих, воспользуйтесь методом <code>criteriaCheck.arbcom.getVoterCriteria()</code>, передав в параметре дату начала выдвижения. Чтобы получить набор критериев для кандидатов — <code>criteriaCheck.arbcom.getCandidateCriteria()</code>. Также можно извлечь список всех проголосовавших на тех или иных выборов при помощи <code>criteriaCheck.arbcom.extractVoters()</code> (в параметре укажите ту часть пути к странице выборов, по которой их можно идентифицировать, например <source lang="js" inline>'Лето 2019'</source>).

При помощи <code>criteriaCheck.arbcom.checkVoters()</code> можно сразу получить список проголосовавших и проверить их. Пример кода для [[Тептар:Выборы арбитров/Лето 2019|выборов в Арбитражный комитет летом 2019 года]]:
<source lang="js">
(async () => {
  window.results = await criteriaCheck.arbcom.checkVoters(
    'Лето 2019',
    (result) => { console.log(result.user.name, result); },
  );
})();
</source>

Если вы будете добавлять новые применения, размещайте их в папке [https://github.com/jwbth/criteria-check/tree/master/src/applications applications].

== Разработка ==
Разработка скрипта ведётся [https://github.com/jwbth/criteria-check на GitHub]. Если на ваши пулл-реквесты не отвечают, создайте форк (лучше связаться с техниками раздела напрямую через канал #tech в [[Тептар:Discord|Discord]]).

[[Категория:Тептар:Справка]]