Тептар:Глобальный код/Автоматическая проверка соответствия критериям
criteriaCheck.js — скрипт для автоматической проверки соответствия тем или иным критериям на выборах, в голосованиях, при присвоении флагов и в иных случаях.
В скрипте задан набор методов, позволяющих проверять участников на соответствие разнообразным критериям. При помощи criteriaCheck.addHandler() можно добавить свои методы. Если проверяемая учётная запись была переименована впоследствии, скрипт это учтёт.
Для проверки на соответствие некоторым критериям (например, учитывающим удалённый вклад) требуются права администратора или арбитра.
Подключение
Чтобы скрипт вызывался у всех пользователей на определённой странице, добавьте в неё код {{выполнить скрипт|criteriaCheck}}.
Чтобы вызвать скрипт из другого скрипта, используйте
mw.loader.getScript('https://massarn.com/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])
|
массив объектов | Проверить список пользователей на соответствие критериям. Аргументы:
Возвращает массив объектов результата. |
| createMessage(message, [anchor]) | jQuery | Сформировать сообщение (например, о соответствии/несоответствии критериям), которое можно вывести на странице. message — объект, содержащий свойства:
|
| getUser(name, nameAsOf) | User | Получить объект участника по его имени. Переименования учётных записей здесь не учитываются (каждому имени соответствует собственный экземпляр объекта User). Параметр nameAsOf (дата, на которую актуально имя) позволяет впоследствии правильно обрабатывать переименования учётных записей, но пока невозможно иметь двух участников с одинаковыми именами, но на разную дату. Свойство name будет содержать имя участника. Тот факт, что участник был переименован, отразится в том, что это свойство будет не равно значению аргумента name рассматриваемого метода. Тот факт, что участник с таким именем не найден, отразится в значении true свойства missing после вызова метода registrationDateNotLater() или getUserInfo() у экземпляра объекта User.
|
| extractCriteria($container) | массив объектов | Извлечь критерии, записанные как атрибуты data- (см. #Критерии), из содержимого контейнера (объект jQuery).
|
| summarize(results) | объект | Резюмировать, соответствует ли участник критериям, на основе нескольких объектов результата. results — массив с объектами результата. Возвращает объект со свойствами:
|
Критерии
Для указания набора критериев используются массивы с объектами критериев. Каждый объект критерия должен содержать свойства:
type— тип критерия, он же метод, используемый для проверки, напримерeditCountNotLess. Список типов критериев см. в таблице ниже.- Это свойство может отсутствовать, а вместо него может присутствовать свойство
needsManualCheckсо значениемtrue. Если скрипт встретит такое свойство, он не будет осуществлять проверку, а просто выдастneedsManualCheckв свойствеresultобъекта результата.
- Это свойство может отсутствовать, а вместо него может присутствовать свойство
text— текст критерия, напримерсделал в Тептар не менее 2000 правок до момента начала номинации.- Свойства, соответствующие параметрам типов критериев (см. в таблице).
Список методов, которые могут быть использованы «из коробки»:
| Тип критерия | Описание | Параметры |
|---|---|---|
| actionCountNotLess | Число действий не менее указанного.
Вместе с результатом проверки возвращается число полученных действий в свойстве |
|
| editCountNotLess | Число правок не менее указанного. Число правок считается на основе вклада. Если параметр deleted не равен true, удалённый вклад не учитывается. Не учитываются правки на страницах, использующих Structured Discussions (это бы требовало совершения лишнего запроса, а Structured Discussions в нашем разделе не был введён иначе, кроме как для экспериментов).
Вместе с результатом проверки возвращается число полученных правок в свойстве |
|
| editsBetweenDates | Есть хотя бы одна правка в промежутке между двумя датами. |
|
| hadFlagFor | Участник обладал указанным(-и) флагом(-ами) в течение как минимум указанного периода времени на указанный момент.
Если участник обладал флагом в течение единственного (непрерывного) периода времени, разница в N месяцев и лет в том случае, когда в другом месяце или годе нет соответствующего числа, вычисляется так: 31 марта − 1 месяц = 28 февраля. Если участник обладал флагом в течение нескольких периодов и то, обладал ли участник флагом в течение этого периода, может зависеть от трактовки месяцев и лет, возвращается значение Вместе с результатом проверки возвращается название флага и период в миллисекундах в свойствах |
|
| noActiveBlockBetweenDates | Участник не имеет активных блокировок, период действия которых включает указанный период. |
|
| notInactiveFor | Участник не имел периодов неактивности длиннее указанного периода времени между указанными датами. |
|
| notLostFlagInLast | Участник не потерял один из указанных флагов в указанном промежутке времени. Вместе с результатом проверки в случае несоответствия критерию возвращается название потерянного флага и дата потери в свойствах flag и lostFlagTimestamp соответственно.
|
|
| registrationDateNotLater | Дата регистрации не позже указанной. Для участников, зарегистрировавшихся ранее 2 декабря 2005 года, берётся дата первой правки (даты регистрации в базе данных у них нет). Вместе с результатом проверки возвращается дата регистрации, а также общее число правок согласно внутреннему счётчику (не вкладу) в свойствах registrationDate и overallEditCount соответственно.
|
|
Периоды времени
Все начальные даты периодов считаются включительно, а конечные (к ним относится и дата регистрации при обработке критериев типа 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).