settings = $settings; } /** * Decide what setting one page aside (or putting it back) would do — without * changing anything. * * ⭐ The two directions are judged by DIFFERENT rules, on purpose. Setting a * page aside is a statement about a live page, so it requires one: published, * and of a type this site actually grades. Putting one back only requires the * id to be ON the list — a page parked months ago may since have been * unpublished or deleted, and refusing to restore it then would strand the * entry with no way to clear it. * * @param int $post_id Post ID. * @param bool $aside True to set aside, false to put back. * @return array One of: * { allowed: true, change: bool, parked: int[] } — parked is the CURRENT stored list; * { allowed: false, code: string, reason: string } — the honest refusal. */ public function plan( $post_id, $aside ) { $post_id = (int) $post_id; $aside = (bool) $aside; if ( $post_id < 1 ) { return $this->refuse( 'agentimus_bad_post', __( 'A post id is required. Every row read-content-issues returns carries one, as `id`.', 'agentimus' ) ); } $parked = $this->parked(); $is_in = in_array( $post_id, $parked, true ); if ( ! $aside ) { // Restoring: the list is the only thing that has to be true. return array( 'allowed' => true, 'change' => $is_in, 'parked' => $parked, ); } $post = get_post( $post_id ); if ( ! $post instanceof \WP_Post ) { return $this->refuse( 'agentimus_not_found', __( 'No post with that id.', 'agentimus' ) ); } if ( 'publish' !== $post->post_status ) { // Grading only ever reads published content, so a draft is already // outside the worklist. Parking it would be a decision with no effect, // recorded as though it had one. return $this->refuse( 'agentimus_not_published', __( 'Only published pages are graded, so this one is already outside the worklist — there is nothing to set aside.', 'agentimus' ) ); } $types = Gradeability::post_types(); if ( ! in_array( (string) $post->post_type, $types, true ) ) { return $this->refuse( 'agentimus_not_graded', sprintf( /* translators: 1: the post's type slug, 2: comma-separated list of graded type slugs. */ __( 'This site does not grade “%1$s” content for citability, so there is nothing to set aside. The types it grades are: %2$s.', 'agentimus' ), (string) $post->post_type, $types ? implode( ', ', $types ) : __( 'none', 'agentimus' ) ) ); } // Room check BEFORE the write, so a full list refuses out loud rather than // letting the sanitiser drop the id and answering "saved". if ( ! $is_in && count( $parked ) >= self::MAX_SET_ASIDE ) { return $this->refuse( 'agentimus_set_aside_full', sprintf( /* translators: %s: the maximum number of set-aside pages. */ __( 'The set-aside list is full at %s pages. Put some back before setting another aside.', 'agentimus' ), number_format_i18n( self::MAX_SET_ASIDE ) ) ); } return array( 'allowed' => true, 'change' => ! $is_in, 'parked' => $parked, ); } /** * Set one page aside as "not cited content", or put it back into grading. * * Nothing about the page itself is touched — it stays published exactly as it * is. What changes is whether the content checks judge it, and therefore the * site's content score. * * @param int $post_id Post ID. * @param bool $aside True to set aside, false to put back. * @return array|\WP_Error {@see result()} for the shape. */ public function set_aside( $post_id, $aside ) { $post_id = (int) $post_id; $aside = (bool) $aside; $plan = $this->plan( $post_id, $aside ); if ( empty( $plan['allowed'] ) ) { return new \WP_Error( $plan['code'], $plan['reason'], array( 'status' => 'agentimus_not_found' === $plan['code'] ? 404 : 400 ) ); } // Already in the state asked for: say so instead of reporting a write that // did not happen. if ( empty( $plan['change'] ) ) { return $this->result( $post_id, $aside, false, $aside ? __( 'Already set aside — nothing changed. It is not being graded.', 'agentimus' ) : __( 'Not set aside, so there was nothing to put back. It is already being graded.', 'agentimus' ) ); } // ⛔ stored(), never all() — see Settings::stored(). The two hand-rolled lines // that used to sit here also skipped the nested deep-merge, so a write could // drop sub-keys a later version had added. $all = $this->settings->stored(); $list = isset( $all['optimize_ignored'] ) && is_array( $all['optimize_ignored'] ) ? array_values( array_filter( array_map( 'intval', $all['optimize_ignored'] ) ) ) : array(); $list = array_values( array_diff( $list, array( $post_id ) ) ); if ( $aside ) { $list[] = $post_id; } $all['optimize_ignored'] = $list; $this->settings->update( $all ); // Sanitises + busts the OPTIMIZE cache, exactly as the owner's click does. // ⭐ READ IT BACK. The sanitiser is the last word on what got stored, and a // write whose effect it dropped must never answer "saved" — his bar: a // partial outcome never reports as success. if ( in_array( $post_id, $this->parked(), true ) !== $aside ) { return new \WP_Error( 'agentimus_set_aside_failed', __( 'The change did not stick. Read the page back with read-content-issues before trying again.', 'agentimus' ), array( 'status' => 500 ) ); } return $this->result( $post_id, $aside, true, $aside ? __( 'Set aside. It stays published exactly as it is, and no content check grades it any more.', 'agentimus' ) : __( 'Put back. It is graded again, and will reappear on the worklist if anything about it needs fixing.', 'agentimus' ) ); } /** * The one return literal, so every path answers in the same shape — including * the no-op ones. SetAsideAbilityTest reads the keys out of THIS method to * check the declared output schema, so a key added here is a key the schema * is made to declare. * * @param int $post_id Post ID. * @param bool $aside The page's state now. * @param bool $changed Whether this call is what put it there. * @param string $message Plain-language account of what happened. * @return array */ /** * Set a SEARCH aside, or put it back. * * ⭐ THE THIRD ANSWER, for the other half of a worklist row. `set_aside()` * excuses a PAGE from being judged; this excuses a QUESTION from being asked * of any page. Without it, the only lever when the SEARCH is the problem was * to set aside the page it landed on — removing good writing from the * worklist to silence a bad query, which the set-aside tool's own text warns * against. On a real site that had already happened: a post was excused from * grading because a spam URL pointed at it. * * ⛔ Dismissing demands the search be one this site was actually shown for; * restoring never does {@see \Agentimus\Search\Rest::dismiss()}. * * @param string $query The reported search. * @param bool $dismissed True to set it aside, false to put it back. * @return array|\WP_Error */ public function dismiss_search( $query, $dismissed ) { $query = Noise::normal( $query ); $dismissed = (bool) $dismissed; if ( '' === $query ) { return new \WP_Error( 'agentimus_bad_query', __( 'No search given.', 'agentimus' ), array( 'status' => 400 ) ); } if ( $dismissed && ! Table::has_query( $query ) ) { return new \WP_Error( 'agentimus_unknown_query', __( 'No search engine has reported that search for this site, so there is nothing to set aside. Check the spelling against a row from read-search-opportunities.', 'agentimus' ), array( 'status' => 400 ) ); } $already = Noise::is_dismissed( $query ); if ( $already === $dismissed ) { return $this->search_result( $query, $dismissed, false, $dismissed ? __( 'Already set aside — nothing changed. No page is being judged on it.', 'agentimus' ) : __( 'Not set aside, so there was nothing to put back. Pages are already judged on it.', 'agentimus' ) ); } // ⛔ stored(), never all() — see Settings::stored() and set_aside() above. $all = $this->settings->stored(); $list = isset( $all['search_dismissed'] ) && is_array( $all['search_dismissed'] ) ? array_values( array_map( 'strval', $all['search_dismissed'] ) ) : array(); $list = array_values( array_diff( $list, array( $query ) ) ); if ( $dismissed ) { $list[] = $query; } $all['search_dismissed'] = $list; $this->settings->update( $all ); // ⭐ READ IT BACK. The sanitiser is the last word on what got stored, and a // write whose effect it dropped must never answer "saved". if ( Noise::is_dismissed( $query ) !== $dismissed ) { return new \WP_Error( 'agentimus_dismiss_failed', __( 'The change did not stick. Read the searches back with read-search-opportunities before trying again.', 'agentimus' ), array( 'status' => 500 ) ); } return $this->search_result( $query, $dismissed, true, $dismissed ? __( 'Set aside. No page is judged on that search any more, and nothing about any page changed.', 'agentimus' ) : __( 'Put back. Pages are judged on that search again.', 'agentimus' ) ); } /** * The answer shape for a search decision — and the WHOLE ledger with it, so * a caller never has to keep its own count of what it has dismissed. * * @param string $query The search acted on, normalized. * @param bool $dismissed Its state now. * @param bool $changed Whether this call is what put it there. * @param string $message What happened, in the site's own words. * @return array */ /** * Set a page aside from the SEARCH worklist, or put it back. * * Its own list, not the citability one: excusing a page from "improve this for * quoting" and from "improve this for search" are different calls. A page with * no post behind it (the homepage on some sites, an archive, a gone permalink) * is held by its address. * * @param int $post_id The page, 0 when it has no post. * @param string $url Its address, used when $post_id is 0. * @param bool $aside True to set aside, false to put back. * @return array|\WP_Error { postId, url, aside, changed, message }. */ public function set_search_page_aside( $post_id, $url, $aside ) { $post_id = (int) $post_id; $url = trim( (string) $url ); $aside = (bool) $aside; if ( $post_id > 0 ) { // Putting back stays possible for a post that has since gone. if ( $aside && ! get_post( $post_id ) ) { return new \WP_Error( 'agentimus_bad_post', __( 'Invalid post.', 'agentimus' ), array( 'status' => 400 ) ); } $field = 'search_ignored'; $value = $post_id; } elseif ( '' !== $url ) { // Same host only: this ledger names OUR pages, and must not become a // store of arbitrary strings. $value = Pages::key( esc_url_raw( $url ) ); $host = strtolower( (string) wp_parse_url( home_url( '/' ), PHP_URL_HOST ) ); if ( '' === $value || strtolower( (string) wp_parse_url( $value, PHP_URL_HOST ) ) !== $host ) { return new \WP_Error( 'agentimus_bad_url', __( 'Invalid page address.', 'agentimus' ), array( 'status' => 400 ) ); } $field = 'search_ignored_urls'; } else { return new \WP_Error( 'agentimus_bad_post', __( 'Invalid post.', 'agentimus' ), array( 'status' => 400 ) ); } $all = $this->settings->stored(); $list = isset( $all[ $field ] ) && is_array( $all[ $field ] ) ? $all[ $field ] : array(); $list = 'search_ignored' === $field ? array_map( 'intval', $list ) : array_map( 'strval', $list ); $was = in_array( $value, $list, true ); if ( $was === $aside ) { return array( 'postId' => $post_id, 'url' => $post_id > 0 ? '' : (string) $value, 'aside' => $aside, 'changed' => false, 'message' => $aside ? __( 'This page was already set aside from the search worklist. Nothing changed.', 'agentimus' ) : __( 'This page was not set aside from the search worklist. Nothing changed.', 'agentimus' ), ); } $list = array_values( array_diff( $list, array( $value ) ) ); if ( $aside ) { $list[] = $value; } $all[ $field ] = $list; $this->settings->update( $all ); // ⭐ READ IT BACK. The save caps this list, and a page the cap dropped has not // been set aside, whatever this call says. $now = $this->settings->stored(); $now = isset( $now[ $field ] ) && is_array( $now[ $field ] ) ? $now[ $field ] : array(); if ( in_array( $value, 'search_ignored' === $field ? array_map( 'intval', $now ) : array_map( 'strval', $now ), true ) !== $aside ) { return new \WP_Error( 'agentimus_search_aside_failed', __( 'The site did not keep this change, so the page’s place on the search worklist has not changed. The list may be full.', 'agentimus' ), array( 'status' => 409 ) ); } return array( 'postId' => $post_id, 'url' => $post_id > 0 ? '' : (string) $value, 'aside' => $aside, 'changed' => true, 'message' => $aside ? __( 'Set aside from the search worklist. The page itself is unchanged, and the owner sees it in the list of pages set aside.', 'agentimus' ) : __( 'Back on the search worklist.', 'agentimus' ), ); } private function search_result( $query, $dismissed, $changed, $message ) { $all = Noise::dismissed(); sort( $all ); return array( 'query' => (string) $query, 'dismissed' => (bool) $dismissed, 'changed' => (bool) $changed, 'message' => (string) $message, 'setAside' => array_values( $all ), ); } private function result( $post_id, $aside, $changed, $message ) { return array( 'postId' => (int) $post_id, // ⛔ Through Worklist, never a bare get_the_title() — see title_of(). // Titles come out of the database entity-encoded, and an agent that is // handed one name by read-content-issues and a different one here has // been given two names for one page. 'title' => Worklist::title_of( $post_id ), 'aside' => (bool) $aside, 'changed' => (bool) $changed, 'message' => (string) $message, // ⛔ THE SAME COUNTS read-content-issues returns, from the same owner — // his law: two surfaces counting the same thing read ONE count. An // agent that sets a page aside and then quotes a tally it derived // itself is the disagreement that law exists to prevent. 'counts' => ( new Worklist( $this->settings ) )->counts(), ); } /** The stored set-aside list, as the reads see it. */ private function parked() { $raw = (array) $this->settings->get( 'optimize_ignored', array() ); return array_values( array_filter( array_map( 'intval', $raw ) ) ); } /** * A refusal carrying the reason in the owner's own language. * * @param string $code Error code. * @param string $reason Plain-language reason. * @return array */ private function refuse( $code, $reason ) { return array( 'allowed' => false, 'code' => $code, 'reason' => $reason, ); } }