RecoReco/Model/RecoRecoModel.php

<?php

namespace Kanboard\Plugin\RecoReco\Model;

use Kanboard\Core\Base;
use Kanboard\Model\TaskModel;

/**
 * The RecoReco engine: find enabled templates and spawn their due occurrences.
 *
 * Called by the recoreco:run CLI command (from cron, or from the identical "Run now" button). One
 * run is one pass over every enabled template; running it five times a day instead of four is
 * harmless -- see the idempotency note below.
 *
 * Per template there is a SINGLE algorithm (no first-run vs catch-up split):
 *
 *   1. Yield to native recurrence if the card became native-recurring (decision 13).
 *   2. Walk occurrences forward from the cursor (the template due date), collecting every one whose
 *      fire time (occurrence - days_before) has arrived (before this run's horizon). The first
 *      occurrence still ahead of the horizon is the "next future" one.
 *   3. Cap to the most recent MAX_BACKFILL: if more than that are due (a template set far in the
 *      past), skip the OLDEST overflow and keep the newest ones -- contiguous, no gap.
 *   4. Spawn each kept occurrence into the target column, dated to that occurrence.
 *   5. Park the cursor on the next future occurrence and stop.
 *
 * Idempotency: after a run the cursor sits on a future occurrence, so a second run the same day
 * collects nothing. As a belt-and-suspenders guard against a run overlapping cron on the same
 * occurrence, spawn() is skipped when a clone for that (template, due) already exists (cloneExists).
 */
class RecoRecoModel extends Base
{
    // Most recent occurrences to actually spawn in one run. A template set far in the past spawns
    // these newest ones and skips the older overflow (no gap), rather than flooding the board.
    const MAX_BACKFILL = 12;

    // Safety bound on the occurrence walk so a misbehaving calculator can never loop forever
    // (1200 monthly steps is a century).
    const MAX_ITERATIONS = 1200;

    private $calc;

    public function run($now = null)
    {
        $now = $now ?: time();
        $horizon = $this->horizon($now);
        $spawned = 0;

        $task_ids = $this->db->table('task_has_metadata')
            ->eq('name', 'recoreco_enabled')
            ->eq('value', '1')
            ->findAllByColumn('task_id');

        foreach ($task_ids as $task_id) {
            $spawned += $this->processTemplate((int) $task_id, $now, $horizon);
        }

        return $spawned;
    }

    /**
     * The look-ahead horizon for this run: fire everything whose fire time is before it. Computed as
     * "ceil now to the next 6h boundary, then +12h", which lands on the four daily runs:
     * 05:58 -> 18:00, 11:58 -> 00:00, 17:58 -> 06:00, 23:58 -> 12:00. Gives a 12h look-ahead with a
     * 6h overlap between runs, so a missed run is covered by its neighbour. Past-due occurrences are
     * naturally included (their fire time is < now < horizon) -- that is the back-fill.
     *
     * @param  int $now
     * @return int
     */
    private function horizon($now)
    {
        $startOfDay = mktime(0, 0, 0, (int) date('n', $now), (int) date('j', $now), (int) date('Y', $now));
        $boundaryHour = (intdiv((int) date('G', $now), 6) + 1) * 6;

        return $startOfDay + $boundaryHour * 3600 + 12 * 3600;
    }

    public function processTemplate($task_id, $now, $horizon)
    {
        $task = $this->taskFinderModel->getById($task_id);

        if (empty($task)) {
            return 0;
        }

        // Native wins: if the card became native-recurring, RecoReco yields (decision 13). Leave a
        // visible trail in the task's activity stream (creator_id 0 = system action).
        if ($task['recurrence_status'] != TaskModel::RECURRING_STATUS_NONE) {
            $this->taskMetadataModel->save($task_id, array('recoreco_enabled' => 0));
            $this->logger->info('RecoReco: disabled on task '.$task_id.' (now native-recurring)');
            $this->projectActivityModel->createEvent(
                (int) $task['project_id'],
                $task_id,
                0,
                'recoreco.task.disable',
                array('task' => array('id' => $task_id, 'title' => $task['title']))
            );
            return 0;
        }

        $meta = $this->taskMetadataModel->getAll($task_id);
        $frequency = isset($meta['recoreco_frequency']) ? $meta['recoreco_frequency'] : '';

        // All five frequencies are supported since v1.1; skip anything unknown.
        if (! in_array($frequency, array('daily', 'weekly', 'monthly_day', 'monthly_dow', 'yearly'), true)) {
            return 0;
        }

        // The anchor defines the recurrence PATTERN (which day-of-month, which weekday ordinal); the
        // cursor (the template due date) is our POSITION in that pattern.
        $anchor = isset($meta['recoreco_anchor']) ? (int) $meta['recoreco_anchor'] : 0;

        if ($anchor <= 0) {
            return 0;
        }

        $lastDay = isset($meta['recoreco_last_day']) && $meta['recoreco_last_day'] == 1;
        $daysBefore = isset($meta['recoreco_days_before']) ? (int) $meta['recoreco_days_before'] : 0;
        $targetColumn = isset($meta['recoreco_target_column']) ? (int) $meta['recoreco_target_column'] : (int) $task['column_id'];
        // Default off: only keep the duplicate link when explicitly turned on.
        $linkCopies = isset($meta['recoreco_link_copies']) && $meta['recoreco_link_copies'] == 1;

        // Phase 1 -- walk forward from the cursor, collecting every occurrence whose fire time has
        // arrived. The loop exits on the first occurrence still ahead of the horizon, which is then
        // the "next future" one to park on.
        $cursor = (int) $task['date_due'];
        $due = array();
        $iterations = 0;

        while ($cursor - $daysBefore * 86400 < $horizon && $iterations < self::MAX_ITERATIONS) {
            $due[] = $cursor;

            $next = $this->calculator()->occurrenceFrom($anchor, $frequency, $lastDay, $cursor, false);

            if ($next === null || $next <= $cursor) {
                break; // calculator cannot advance -- stop rather than loop
            }

            $cursor = $next;
            $iterations++;
        }

        $nextFuture = $cursor;

        // Phase 2 -- cap to the most recent MAX_BACKFILL, skipping the oldest overflow (no gap).
        $skip = max(0, count($due) - self::MAX_BACKFILL);
        $toSpawn = array_slice($due, $skip);

        // Phase 3 -- spawn each kept occurrence, dated to that occurrence. Idempotent: skip any that
        // this template has already spawned (survives a run overlapping cron on the same occurrence).
        $spawned = 0;

        foreach ($toSpawn as $occurrence) {
            if ($this->cloneExists($task_id, $occurrence)) {
                continue;
            }

            // duplicate() copies the template's date_due onto the clone, so set it to this occurrence
            // first, then spawn.
            $this->setDue($task_id, $occurrence);
            $this->spawn($task, $targetColumn);
            $spawned++;
        }

        // Phase 4 -- park the cursor on the next future occurrence and stop.
        $this->setDue($task_id, $nextFuture);

        // Reconcile the duplicate links with the setting (removes both new and old ones when off).
        $this->syncCloneLinks($task_id, $linkCopies);

        return $spawned;
    }

    /**
     * Has this template already spawned a clone for the given occurrence? A clone records its source
     * template (recoreco_source) and carries the occurrence as its due date, so the pair identifies
     * it. This makes a repeated or overlapping run idempotent -- an occurrence is never spawned twice.
     *
     * @param  int $template_id
     * @param  int $due
     * @return bool
     */
    private function cloneExists($template_id, $due)
    {
        $clone_ids = $this->db->table('task_has_metadata')
            ->eq('name', 'recoreco_source')
            ->eq('value', (string) $template_id)
            ->findAllByColumn('task_id');

        if (empty($clone_ids)) {
            return false;
        }

        return $this->db->table(TaskModel::TABLE)
            ->in('id', $clone_ids)
            ->eq('date_due', $due)
            ->exists();
    }

    /**
     * Reconcile a template's "is a duplicate of" links with the link-copies setting. When off, remove
     * the links to THIS template's own RecoReco clones (identified by recoreco_source, so manual
     * links are left untouched). When on, do nothing -- new spawns already carry the link.
     *
     * @param int  $template_id
     * @param bool $linkCopies
     */
    public function syncCloneLinks($template_id, $linkCopies)
    {
        if ($linkCopies) {
            return;
        }

        foreach ($this->taskLinkModel->getAll($template_id) as $link) {
            $opposite = (int) $link['task_id'];

            if ((int) $this->taskMetadataModel->get($opposite, 'recoreco_source', 0) === (int) $template_id) {
                $this->taskLinkModel->remove($link['id']);
            }
        }
    }

    private function setDue($task_id, $due)
    {
        // Move the template's due date directly (no task events fired). This is the cursor.
        $this->db->table(TaskModel::TABLE)->eq('id', $task_id)->update(array('date_due' => $due));
    }

    private function spawn(array $template, $targetColumn)
    {
        // The template's date_due is already the occurrence (setDue), so duplicate() copies it onto
        // the clone. duplicate() copies fields + tags + links + subtasks, but NO metadata, so the
        // clone is not a template.
        $newId = $this->taskDuplicationModel->duplicate($template['id']);

        if ($newId === false) {
            $this->logger->error('RecoReco: duplicate failed for task '.$template['id']);
            return false;
        }

        // duplicate() lands the clone in the source column; move it to the chosen target (top).
        if ($targetColumn > 0 && $targetColumn != $template['column_id']) {
            $this->taskPositionModel->movePosition($template['project_id'], $newId, $targetColumn, 1, $template['swimlane_id']);
        }

        // Reset the "[DUPLICATE]" prefix back to the source title (no events).
        $this->taskModificationModel->update(array('id' => $newId, 'title' => $template['title']), false);

        // Kanboard's duplicate() adds an "is a duplicate of" task link between the template and the
        // clone. It is reconciled with the recoreco_link_copies setting by syncCloneLinks() after
        // the spawn loop (kept when on, removed when off).

        // Mark the clone: white icon + cannot itself be made recurring; record its source template.
        $this->taskMetadataModel->save($newId, array(
            'recoreco_clone' => 1,
            'recoreco_source' => $template['id'],
        ));

        // Signal FinanceBuddy (advance the installment). Harmless no-op if nothing listens.
        $payload = array('source_task_id' => (int) $template['id'], 'new_task_id' => (int) $newId);
        $this->hook->reference('recoreco:task:spawned', $payload);

        // Record the spawn in the clone's activity stream (creator_id 0 = system action).
        $this->projectActivityModel->createEvent(
            (int) $template['project_id'],
            $newId,
            0,
            'recoreco.task.spawn',
            array(
                'task' => array('id' => $newId, 'title' => $template['title']),
                'template_id' => (int) $template['id'],
                'template_title' => $template['title'],
            )
        );

        return $newId;
    }

    private function calculator()
    {
        if ($this->calc === null) {
            $this->calc = new OccurrenceCalculator();
        }

        return $this->calc;
    }
}