@meith/moderation 0.16.0

package/LICENSE.md

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@meith/moderation",
+  "version": "0.16.0",
+  "license": "LGPL-3.0-or-later",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meith-dev/meith.git",
+    "directory": "packages/moderation"
+  },
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "files": [
+    "src",
+    "!src/**/*.test.*",
+    "!src/**/*.type-test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@meith/core": "0.16.0",
+    "@meith/i18n": "0.16.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,101 @@
+export {
+  INLINE_CHUNK,
+  INLINE_TOOL_ACTIONS,
+  InlineModeration,
+  type InlineModerationRepository,
+  type InlineOutcome,
+  type InlineRights,
+  type InlineRightsResolver,
+  type InlineTarget,
+  type InlineTool,
+  MAX_INLINE_SELECTION,
+  NO_INLINE_RIGHTS,
+  parseInlineTool,
+} from './inline'
+export {
+  type IpMatch,
+  MOD_LOG_ACTIONS,
+  MOD_LOG_LABEL_KEYS,
+  MODCP_PAGE_SIZE,
+  type ModCpRepository,
+  type ModeratedForum,
+  ModeratorPanel,
+  type ModeratorPanelRights,
+  type ModLogEntry,
+  type ModLogPage,
+} from './modcp'
+export {
+  MAX_CHUNK,
+  ModerationQueue,
+  type ModerationQueueRepository,
+  type PendingItem,
+  parseSelection,
+  QUEUE_PAGE_SIZE,
+  type QueueDecision,
+  type QueueItem,
+  type QueueItemKind,
+  type QueueOutcome,
+  type QueuePage,
+  type QueueSelection,
+} from './queue'
+export {
+  inScope,
+  type NewReport,
+  parseTargetKind,
+  REASON_MAX,
+  REASON_MIN,
+  REPORT_TARGET_KINDS,
+  REPORTS_PAGE_SIZE,
+  type ReportEvent,
+  type ReportNotifierPort,
+  type ReportPage,
+  type ReportRepository,
+  type ReportRow,
+  type ReportScope,
+  ReportService,
+  type ReportStatus,
+  type ReportTarget,
+  type ReportTargetKind,
+} from './reports'
+export {
+  type MergePlan,
+  type SplitPlan,
+  type SurgeryOutcome,
+  type SurgeryRights,
+  type SurgeryThread,
+  ThreadSurgery,
+  type ThreadSurgeryRepository,
+} from './surgery'
+export {
+  keepsThreads,
+  type MoveDestination,
+  parseThreadTool,
+  type ThreadTool,
+  type ThreadToolOutcome,
+  type ThreadToolRights,
+  ThreadTools,
+  type ThreadToolsRepository,
+  type ThreadToolTarget,
+} from './thread-tools'
+export {
+  type IssuedWarning,
+  NO_RESTRICTION,
+  POINTS_MAX,
+  type PostingRestriction,
+  parseWarningAction,
+  REASON_MAX as WARNING_REASON_MAX,
+  restrictsPosting,
+  TITLE_MAX as WARNING_TITLE_MAX,
+  WARNING_ACTIONS,
+  WARNINGS_PAGE_SIZE,
+  type WarningAction,
+  type WarningBanPort,
+  type WarningLevel,
+  type WarningNotifierPort,
+  type WarningPage,
+  type WarningRepository,
+  type WarningRow,
+  WarningService,
+  type WarningStanding,
+  type WarningType,
+} from './warnings'

package/src/inline.ts

@@ -0,0 +1,269 @@
+import { ValidationError } from '@meith/core'
+import { msg } from '@meith/i18n'
+
+import type { QueueSelection } from './queue'
+import { keepsThreads, type MoveDestination } from './thread-tools'
+
+export type InlineTool =
+  | 'approve'
+  | 'delete'
+  | 'restore'
+  | 'lock'
+  | 'unlock'
+  | 'stick'
+  | 'unstick'
+  | 'move'
+
+export interface InlineTarget extends QueueSelection {
+  readonly forumId: number
+  readonly visibility: 'visible' | 'unapproved' | 'deleted'
+  readonly threadVisibility: 'visible' | 'unapproved' | 'deleted'
+  readonly isLocked: boolean
+  readonly isSticky: boolean
+}
+
+export interface InlineRights {
+  readonly approve: boolean
+  readonly lock: boolean
+  readonly stick: boolean
+  readonly move: boolean
+  readonly deleteThreads: boolean
+  readonly deletePosts: boolean
+  readonly restoreThreads: boolean
+  readonly restorePosts: boolean
+}
+
+export const NO_INLINE_RIGHTS: InlineRights = {
+  approve: false,
+  lock: false,
+  stick: false,
+  move: false,
+  deleteThreads: false,
+  deletePosts: false,
+  restoreThreads: false,
+  restorePosts: false,
+}
+
+export interface InlineRightsResolver {
+  rightsIn(forumId: number): Promise<InlineRights>
+}
+
+export interface InlineOutcome {
+  readonly tool: InlineTool
+  readonly applied: number
+  readonly refused: number
+  readonly missing: number
+  readonly skipped: number
+}
+
+export interface InlineModerationRepository {
+  resolve(
+    selection: readonly QueueSelection[],
+    forumIds: readonly number[],
+  ): Promise<readonly InlineTarget[]>
+
+  findDestination(forumId: number): Promise<MoveDestination | null>
+
+  apply(input: {
+    readonly tool: InlineTool
+    readonly threadIds: readonly number[]
+    readonly postIds: readonly number[]
+    readonly toForumId?: number | undefined
+    readonly actorUserId: number
+    readonly at: Date
+  }): Promise<number>
+}
+
+export const INLINE_CHUNK = 25
+
+export const MAX_INLINE_SELECTION = 500
+
+const THREAD_ONLY: ReadonlySet<InlineTool> = new Set<InlineTool>([
+  'lock',
+  'unlock',
+  'stick',
+  'unstick',
+  'move',
+])
+
+export class InlineModeration {
+  private readonly repo: InlineModerationRepository
+  private readonly now: () => Date
+
+  constructor(deps: { inline: InlineModerationRepository; now?: () => Date }) {
+    this.repo = deps.inline
+    this.now = deps.now ?? (() => new Date())
+  }
+
+  async apply(input: {
+    readonly selection: readonly QueueSelection[]
+    readonly tool: InlineTool
+    readonly toForumId?: number | undefined
+    readonly scopeForumIds: readonly number[]
+    readonly rights: InlineRightsResolver
+    readonly actorUserId: number
+  }): Promise<InlineOutcome> {
+    if (input.selection.length === 0) {
+      throw new ValidationError(msg('error.moderation.select-at-least-one-item'))
+    }
+    if (input.selection.length > MAX_INLINE_SELECTION) {
+      throw new ValidationError(msg('error.moderation.inline-chunk', { max: MAX_INLINE_SELECTION }))
+    }
+
+    const unique = new Map<string, QueueSelection>()
+    for (const item of input.selection) unique.set(`${item.kind}:${item.id}`, item)
+
+    if (input.scopeForumIds.length === 0) {
+      return { tool: input.tool, applied: 0, refused: 0, missing: unique.size, skipped: 0 }
+    }
+
+    const targets = await this.repo.resolve([...unique.values()], input.scopeForumIds)
+    const missing = unique.size - targets.length
+
+    if (input.tool === 'move') {
+      await this.requireDestination(input.toForumId, input.rights)
+    }
+
+    let refused = 0
+    let skipped = 0
+    const allowed: InlineTarget[] = []
+    const rightsByForum = new Map<number, InlineRights>()
+
+    for (const target of targets) {
+      let rights = rightsByForum.get(target.forumId)
+      if (rights === undefined) {
+        rights = await input.rights.rightsIn(target.forumId)
+        rightsByForum.set(target.forumId, rights)
+      }
+
+      if (!holdsRight(input.tool, target.kind, rights)) {
+        refused += 1
+        continue
+      }
+      if (!isApplicable(input.tool, target, input.toForumId)) {
+        skipped += 1
+        continue
+      }
+      allowed.push(target)
+    }
+
+    let applied = 0
+    for (const chunk of chunked(allowed, INLINE_CHUNK)) {
+      applied += await this.repo.apply({
+        tool: input.tool,
+        threadIds: chunk.filter((i) => i.kind === 'thread').map((i) => i.id),
+        postIds: chunk.filter((i) => i.kind === 'post').map((i) => i.id),
+        ...(input.toForumId === undefined ? {} : { toForumId: input.toForumId }),
+        actorUserId: input.actorUserId,
+        at: this.now(),
+      })
+    }
+
+    return {
+      tool: input.tool,
+      applied,
+      refused,
+      missing,
+      skipped: skipped + (allowed.length - applied),
+    }
+  }
+
+  private async requireDestination(
+    toForumId: number | undefined,
+    rights: InlineRightsResolver,
+  ): Promise<void> {
+    if (toForumId === undefined) {
+      throw new ValidationError(msg('error.moderation.choose-forum-move-them'))
+    }
+    const destinationRights = await rights.rightsIn(toForumId)
+    if (!destinationRights.move) {
+      throw new ValidationError(msg('error.moderation.move-threads-into-forum'))
+    }
+    const destination = await this.repo.findDestination(toForumId)
+    if (destination === null || !keepsThreads(destination)) {
+      throw new ValidationError(msg('error.moderation.forum-threads-live'))
+    }
+  }
+}
+
+function holdsRight(tool: InlineTool, kind: QueueSelection['kind'], rights: InlineRights): boolean {
+  if (THREAD_ONLY.has(tool) && kind === 'post') return true
+
+  switch (tool) {
+    case 'approve':
+      return rights.approve
+    case 'delete':
+      return kind === 'thread' ? rights.deleteThreads : rights.deletePosts
+    case 'restore':
+      return kind === 'thread' ? rights.restoreThreads : rights.restorePosts
+    case 'lock':
+    case 'unlock':
+      return rights.lock
+    case 'stick':
+    case 'unstick':
+      return rights.stick
+    case 'move':
+      return rights.move
+  }
+}
+
+function isApplicable(
+  tool: InlineTool,
+  target: InlineTarget,
+  toForumId: number | undefined,
+): boolean {
+  if (THREAD_ONLY.has(tool) && target.kind === 'post') return false
+
+  switch (tool) {
+    case 'approve':
+      return (
+        target.visibility === 'unapproved' &&
+        (target.kind === 'thread' || target.threadVisibility === 'visible')
+      )
+    case 'delete':
+      return target.visibility === 'visible'
+    case 'restore':
+      return target.visibility === 'deleted'
+    case 'lock':
+      return target.visibility === 'visible' && !target.isLocked
+    case 'unlock':
+      return target.visibility === 'visible' && target.isLocked
+    case 'stick':
+      return target.visibility === 'visible' && !target.isSticky
+    case 'unstick':
+      return target.visibility === 'visible' && target.isSticky
+    case 'move':
+      return target.visibility === 'visible' && target.forumId !== toForumId
+  }
+}
+
+function chunked<T>(items: readonly T[], size: number): T[][] {
+  const out: T[][] = []
+  for (let i = 0; i < items.length; i += size) out.push(items.slice(i, i + size))
+  return out
+}
+
+export function parseInlineTool(value: string | undefined): InlineTool | null {
+  const tools: readonly InlineTool[] = [
+    'approve',
+    'delete',
+    'restore',
+    'lock',
+    'unlock',
+    'stick',
+    'unstick',
+    'move',
+  ]
+  return tools.includes(value as InlineTool) ? (value as InlineTool) : null
+}
+
+export const INLINE_TOOL_ACTIONS = {
+  approve: ['content.approve'],
+  lock: ['thread.lock'],
+  unlock: ['thread.lock'],
+  stick: ['thread.stick'],
+  unstick: ['thread.stick'],
+  move: ['thread.move'],
+  delete: ['thread.delete', 'post.softDelete'],
+  restore: ['thread.restore', 'post.restore'],
+} as const satisfies Readonly<Record<InlineTool, readonly string[]>>