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

criteriaCheck.js — скрипт для автоматической проверки соответствия тем или иным критериям на выборах, в голосованиях, при присвоении флагов и в иных случаях.

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

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

Подключение

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

Чтобы вызвать скрипт из другого скрипта, используйте

mw.loader.getScript('https://ru.wikipedia.org/w/index.php?title=MediaWiki:Script/criteriaCheck.js&action=raw&ctype=text/javascript').done(function () {
	// ...
});

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

Объект criteriaCheck

Скрипт создаёт в глобальной области видимости объект criteriaCheck со следующими свойствами/методами:

Свойства

Свойство	Тип	Описание
apiRateLimit	число	Максимальное число рядов, которое можно получать в результате запросов к API. Это число равно 5000 у участников, обладающих правом apihighlimits, и 500 у всех остальных. Заполняется при первой проверке соответствия критерию.
currentUser	User	Участник, от имени которого выполняется скрипт.
util	объект	Набор утилитарных методов, которые могут использоваться в методах критериев или в применениях.
свойства по случаям применения (admin, arbcom)	объект	Объекты применений. Они содержат свойства и методы по каждому из случаев применения.

Методы

Метод	Тип возвращаемого значения	Описание
addHandler(criterionType, handler)	нет	Добавить метод для проверки соответствия критерию. criterionType — тип критерия, для которого будет вызываться этот метод (один тип — один метод), handler — метод. Метод должен получать на вход объект участника и объект критерия (его можно назвать options) и возвращать объект результата.
check(userNames, criteria, [options])	массив объектов	Проверить список пользователей на соответствие критериям. Аргументы: userNames (массив строк или строка) — список имён участников или одно имя. criteria (массив объектов или объект) — набор критериев или один критерий. options (объект) — набор опций: namesAsOf (дата) — считать имена участников актуальными на данную дату (параметр служит для правильной обработки переименований учётных записей). callback (функция) — колбэк, вызываемый после обработки результата для каждого участника и получающий в качестве аргумента этот результат. doSummarize (булево значение) — пропускать ли каждый результат через функцию criteriaCheck.summarize() (см. ниже). По умолчанию true. Возвращает массив объектов результата.
createMessage(message, [anchor])	jQuery	Сформировать сообщение (например, о соответствии/несоответствии критериям), которое можно вывести на странице. message — объект, содержащий свойства: icons (массив строк) или icon (строка) — имена иконок из следующего перечня: check, close, help, error, warning, loading. texts (массив строк) или text (строка или объект jQuery) — HTML-коды сообщений. Если их несколько, они нумеруются. accented (булево значение) — приводит к выделению сообщения полужирным шрифтом. big (булево значение) — приводит к использованию шрифта большего кегля в сообщении. anchor — название якоря элемента сообщения (содержимое атрибута id).
getUser(name, nameAsOf)	User	Получить объект участника по его имени. Переименования учётных записей здесь не учитываются (каждому имени соответствует собственный экземпляр объекта User). Параметр nameAsOf (дата, на которую актуально имя) позволяет впоследствии правильно обрабатывать переименования учётных записей, но пока невозможно иметь двух участников с одинаковыми именами, но на разную дату. Свойство name будет содержать имя участника. Тот факт, что участник был переименован, отразится в том, что это свойство будет не равно значению аргумента name рассматриваемого метода. Тот факт, что участник с таким именем не найден, отразится в значении true свойства missing после вызова метода registrationDateNotLater() или getUserInfo() у экземпляра объекта User.
extractCriteria($container)	массив объектов	Извлечь критерии, записанные как атрибуты data- (см. #Критерии), из содержимого контейнера (объект jQuery).
summarize(results)	объект	Резюмировать, соответствует ли участник критериям, на основе нескольких объектов результата. results — массив с объектами результата. Возвращает объект со свойствами: conclusion (значения meets, notMeets, possiblyMeets или userMissing), results (тот же объект, что передаётся в аргументе), warnings, user.

Критерии

Для указания набора критериев используются массивы с объектами критериев. Каждый объект критерия должен содержать свойства:

• type — тип критерия, он же метод, используемый для проверки, например editCountNotLess. Список типов критериев см. в таблице ниже.
  • Это свойство может отсутствовать, а вместо него может присутствовать свойство needsManualCheck со значением true. Если скрипт встретит такое свойство, он не будет осуществлять проверку, а просто выдаст needsManualCheck в свойстве result объекта результата.
• text — текст критерия, например сделал в Тептар не менее 2000 правок до момента начала номинации.
• Свойства, соответствующие параметрам типов критериев (см. в таблице).

Список методов, которые могут быть использованы «из коробки»:

Тип критерия	Описание	Параметры
actionCountNotLess	Число действий не менее указанного. Число правок считается на основе вклада. Не учитываются правки на страницах, использующих Structured Discussions (это бы требовало совершения лишнего запроса, а Structured Discussions в нашем разделе не был введён иначе, кроме как для экспериментов). Удалённый вклад по умолчанию учитывается. Чтобы отключить это, задайте false параметру deleted. Исключаются автоматические действия, а именно действия со следующими кодами: approve-a, approve-ia, approve2-a, approve2-ia, thank, hit (такой код имеют действия типов spamblacklist и abusefilter), move, move_redir, move_prot, delete_redir, renameuser, autopromote, autopatrol, create (тип действия тоже должен быть create), все действия типа newusers. Cм. mw:API:Logevents, Тептар:Патрулирование#Обозначения действий патрулирования в API. Вместе с результатом проверки возвращается число полученных действий в свойстве actionCount (если это число больше необходимого для соответствия критерию, оно может быть меньше общего числа действий в указанный период, так как нет нужды запрашивать с сервера ещё).	value (число) — необходимое число правок. periodStart (дата) — дата начала периода. periodEnd (дата) — дата конца периода. Также могут использоваться параметры для типа критерия editCountNotLess: они будут применяться к правкам.
editCountNotLess	Число правок не менее указанного. Число правок считается на основе вклада. Если параметр deleted не равен true, удалённый вклад не учитывается. Не учитываются правки на страницах, использующих Structured Discussions (это бы требовало совершения лишнего запроса, а Structured Discussions в нашем разделе не был введён иначе, кроме как для экспериментов). Вместе с результатом проверки возвращается число полученных правок в свойстве editCount (если это число больше необходимого для соответствия критерию, оно может быть меньше общего числа правок в указанный период, так как нет нужды запрашивать с сервера ещё).	value (число) — необходимое число правок. periodStart (дата) — дата начала периода. periodEnd (дата) — дата конца периода. ns (число) — считать только правки в данном пространстве имён. deleted (булево значение) — учитывать удалённый вклад (требует прав администратора или арбитра). meaningful (булево значение) — должны учитываться только осмысленные/значительные правки. Так как автоматически это проверить нельзя, метод будет возвращать результат possiblyMeets вместо meets, если число правок меньше значения, в 1,5 раз большего необходимого числа правок (например, если требуется 100 правок, то possiblyMeets будет возвращаться для числа правок от 100 до 149).
editsBetweenDates	Есть хотя бы одна правка в промежутке между двумя датами.	periodStart (дата) — дата начала периода. periodEnd (дата) — дата конца периода.
hadFlagFor	Участник обладал указанным(-и) флагом(-ами) в течение как минимум указанного периода времени на указанный момент. Если участник обладал флагом в течение единственного (непрерывного) периода времени, разница в N месяцев и лет в том случае, когда в другом месяце или годе нет соответствующего числа, вычисляется так: 31 марта − 1 месяц = 28 февраля. Если участник обладал флагом в течение нескольких периодов и то, обладал ли участник флагом в течение этого периода, может зависеть от трактовки месяцев и лет, возвращается значение possiblyMeets. Вместе с результатом проверки возвращается название флага и период в миллисекундах в свойствах flag и period соответственно.	flags (массив строк) или flag (строка) — названия флагов согласно базе данных (например, администратор — sysop; чтобы узнать название, выберите флаг на странице Служебная:Список участников и посмотрите значение параметра group в URL). value (число) — период времени, в течение которого участник должен обладать флагом. unit (строка) — единица измерения (day, month или year). referenceDate (дата) — дата, на которую проверяется истинность утверждения.
noActiveBlockBetweenDates	Участник не имеет активных блокировок, период действия которых включает указанный период.	periodStart (дата) — дата начала периода. periodEnd (дата) — дата конца периода. ns (число) — если нужно также учитывать частичные блокировки, укажите пространство имён, на которое должна распространяться блокировка, чтобы участник не соответствовал критерию.
notInactiveFor	Участник не имел периодов неактивности длиннее указанного периода времени между указанными датами.	value (число) — минимальный период времени, в течение которого участник должен быть неактивен, чтобы не соответствовать критерию. unit (строка) — единица измерения (day, month или year). periodStart (дата) — дата начала периода, активность внутри которого требуется изучить. periodEnd (дата) — дата конца периода, активность внутри которого требуется изучить. deleted (булево значение) — учитывать удалённый вклад (по умолчанию true, требует прав администратора или арбитра).
notLostFlagInLast	Участник не потерял один из указанных флагов в указанном промежутке времени. Вместе с результатом проверки в случае несоответствия критерию возвращается название потерянного флага и дата потери в свойствах flag и lostFlagTimestamp соответственно.	flags (массив строк) или flag (строка) — названия флагов согласно базе данных (например, администратор — sysop; чтобы узнать название, выберите флаг на странице Служебная:Список участников и посмотрите значение параметра group в URL). value (число) — период времени, в течение которого участник должен не потерять флаг. unit (строка) — единица измерения (day, month или year). referenceDate (дата) — дата, от которой нужно отсчитывать период времени.
registrationDateNotLater	Дата регистрации не позже указанной. Для участников, зарегистрировавшихся ранее 2 декабря 2005 года, берётся дата первой правки (даты регистрации в базе данных у них нет). Вместе с результатом проверки возвращается дата регистрации, а также общее число правок согласно внутреннему счётчику (не вкладу) в свойствах registrationDate и overallEditCount соответственно.	value (число) — дата регистрации.

Периоды времени

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

Указание критериев в HTML-коде

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

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

Пример того, как это может быть сделано, см. здесь.

Для извлечения критериев из HTML-кода используйте метод criteriaCheck.extractCriteria().

Объект результата

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

Применения

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

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

При помощи criteriaCheck.arbcom.checkVoters() можно сразу получить список проголосовавших и проверить их. Пример кода для выборов в Арбитражный комитет летом 2019 года:

(async () => {
  window.results = await criteriaCheck.arbcom.checkVoters(
    'Лето 2019',
    (result) => { console.log(result.user.name, result); },
  );
})();

Если вы будете добавлять новые применения, размещайте их в папке applications.

Разработка

Разработка скрипта ведётся на GitHub. Если на ваши пулл-реквесты не отвечают, создайте форк (лучше связаться с техниками раздела напрямую через канал #tech в Discord).