rule_pack = $rule_pack; $this->sanitizer = $sanitizer; $this->assertions = $assertions; $this->runs = $runs; $this->findings = $findings; $this->factory = $factory; $this->transaction = $transaction; } /** * @return array{run_uuid:string,language:string,packs:list>} */ public function view( string $run_uuid ): array { $run = $this->completed_full_run( $run_uuid ); return $this->view_for_run( $run ); } /** * @param list $answers Submitted boundary values. * @return array{run_uuid:string,language:string,packs:list>} */ public function save( string $run_uuid, string $check_id, array $answers, int $actor_id ): array { $run = $this->completed_full_run( $run_uuid ); $pack = $this->rule_pack->pack( $check_id ); if ( $actor_id < 1 || count( $answers ) < 1 || count( $answers ) > count( $pack['statements'] ) ) { throw new InvalidArgumentException( 'manual_assertion_request_invalid' ); } $statement_ids = array(); foreach ( $pack['statements'] as $statement ) { $statement_ids[] = (string) $statement['id']; } $seen = array(); $this->transaction->begin(); try { foreach ( $answers as $answer ) { if ( ! is_array( $answer ) || ! isset( $answer['id'], $answer['state'], $answer['comment'] ) || ! is_string( $answer['id'] ) || ! is_string( $answer['state'] ) || ! is_string( $answer['comment'] ) ) { throw new InvalidArgumentException( 'manual_assertion_request_invalid' ); } $statement_id = $answer['id']; if ( ! in_array( $statement_id, $statement_ids, true ) || in_array( $statement_id, $seen, true ) ) { throw new InvalidArgumentException( 'manual_assertion_statement_invalid' ); } $seen[] = $statement_id; $key = $check_id . '.' . $statement_id; if ( 'unreviewed' === $answer['state'] ) { $this->assertions->delete( $run->id(), $key, $actor_id ); continue; } if ( ! in_array( $answer['state'], array( 'confirmed', 'not_confirmed', 'not_applicable' ), true ) ) { throw new InvalidArgumentException( 'manual_assertion_state_invalid' ); } $comment = $this->sanitizer->sanitize( $answer['comment'] ); if ( 'not_applicable' === $answer['state'] && '' === $comment ) { throw new InvalidArgumentException( 'manual_assertion_comment_required' ); } $this->assertions->upsert( $run->id(), $key, $answer['state'], $comment, $actor_id, current_time( 'mysql', true ) ); } $this->findings->save( $run->id(), $this->aggregate_finding( $run, $check_id ) ); $this->transaction->commit(); } catch ( Throwable $exception ) { $this->transaction->rollback(); throw $exception; } return $this->view_for_run( $run ); } /** * @return array{run_uuid:string,language:string,packs:list>} */ private function view_for_run( RunRecord $run ): array { $rows = $this->assertions->list_for_run( $run->id() ); $packs = array(); foreach ( $this->rule_pack->check_ids() as $check_id ) { $pack = $this->rule_pack->localized_pack( $check_id, $run->language() ); $pack['answers'] = $this->answers_for_pack( $check_id, $rows ); $packs[] = $pack; } return array( 'run_uuid' => $run->uuid(), 'language' => $run->language(), 'packs' => $packs, ); } private function completed_full_run( string $run_uuid ): RunRecord { $run = $this->runs->get_by_uuid( $run_uuid ); if ( null === $run ) { throw new StorageException( 'run_not_found' ); } if ( 'full' !== $run->profile() || RunStatus::COMPLETED !== $run->status() ) { throw new InvalidArgumentException( 'manual_assertion_run_unavailable' ); } return $run; } /** * @param list $rows Stored rows. * @return array */ private function answers_for_pack( string $check_id, array $rows ): array { $answers = array(); $prefix = $check_id . '.'; foreach ( $rows as $row ) { if ( 0 !== strpos( $row['assertion_key'], $prefix ) ) { continue; } $statement_id = substr( $row['assertion_key'], strlen( $prefix ) ); $answers[ $statement_id ] = array( 'state' => $row['state'], 'comment' => $row['comment_masked'], 'asserted_at' => mysql_to_rfc3339( $row['asserted_at'] ), ); } return $answers; } /** @return array */ private function aggregate_finding( RunRecord $run, string $check_id ): array { $pack = $this->rule_pack->pack( $check_id ); $rows = $this->assertions->list_for_run( $run->id() ); $answers = $this->answers_for_pack( $check_id, $rows ); $total = count( $pack['statements'] ); $reviewed = count( $answers ); $not_confirmed = 0; $comments = 0; $latest = ''; foreach ( $answers as $answer ) { if ( 'not_confirmed' === $answer['state'] ) { ++$not_confirmed; } if ( '' !== $answer['comment'] ) { ++$comments; } if ( $answer['asserted_at'] > $latest ) { $latest = $answer['asserted_at']; } } if ( 0 === $reviewed ) { $status = 'not_tested'; $coverage_state = 'none'; $state = 'unreviewed'; } elseif ( $not_confirmed > 0 ) { $status = 'fail'; $coverage_state = $reviewed === $total ? 'complete' : 'partial'; $state = 'operator_reported_gap'; } elseif ( $reviewed < $total ) { $status = 'warning'; $coverage_state = 'partial'; $state = 'partially_reviewed'; } elseif ( ! $this->rule_pack->is_current() ) { $status = 'warning'; $coverage_state = 'complete'; $state = 'source_review_due'; } else { $status = 'pass'; $coverage_state = 'complete'; $state = 'operator_review_complete'; } $evidence = array( 'statement' => 'reviewed_' . $reviewed . '_of_' . $total, 'state' => $state, 'limitations' => array( 'Every answer is an administrator statement stored locally. Completion means only that the checklist was answered; it does not verify truth, legal scope, compliance or professional review.' ), ); if ( '' !== $latest ) { $evidence['confirmed_at'] = $latest; } if ( $comments > 0 ) { $evidence['comment'] = $comments . '_locally_masked_comments'; } return $this->factory->build( $check_id, $status, $evidence, $reviewed, $total, $coverage_state, mysql_to_rfc3339( current_time( 'mysql', true ) ) ); } }