diff --git a/.rubocop.yml b/.rubocop.yml index d48b4aa7..ee17f6ec 100644 --- a/.rubocop.yml +++ b/.rubocop.yml @@ -116,7 +116,7 @@ RSpec/NestedGroups: #### Style #### Style/Documentation: - Enabled: false + Enabled: true Style/FrozenStringLiteralComment: Exclude: diff --git a/app/controllers/application_controller.rb b/app/controllers/application_controller.rb index 297e8083..c15118e9 100644 --- a/app/controllers/application_controller.rb +++ b/app/controllers/application_controller.rb @@ -1,5 +1,7 @@ # frozen_string_literal: true +# The base class for most controllers. +# Manages authenticated user sessions and other auth methods. class ApplicationController < ActionController::Base helper_method :current_user, :logged_in? diff --git a/app/controllers/dashboard_controller.rb b/app/controllers/dashboard_controller.rb index 6049155d..da2ff379 100644 --- a/app/controllers/dashboard_controller.rb +++ b/app/controllers/dashboard_controller.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# The dashboard controller serves the logged-in homepage of the app. class DashboardController < ApplicationController def index; end end diff --git a/app/controllers/dev/accounts_controller.rb b/app/controllers/dev/accounts_controller.rb index fd7a74c3..51098cca 100644 --- a/app/controllers/dev/accounts_controller.rb +++ b/app/controllers/dev/accounts_controller.rb @@ -1,6 +1,7 @@ # frozen_string_literal: true module Dev + # AccountsController offers login convenience for dev and test environments only. class AccountsController < ApplicationController skip_before_action :check_session_expiration diff --git a/app/controllers/dev/sandbox_controller.rb b/app/controllers/dev/sandbox_controller.rb index eea7ec9c..87a22cc7 100644 --- a/app/controllers/dev/sandbox_controller.rb +++ b/app/controllers/dev/sandbox_controller.rb @@ -1,6 +1,7 @@ # frozen_string_literal: true module Dev + # Sandbox controller demos some USWDS components and layout. class SandboxController < ApplicationController def index; end end diff --git a/app/controllers/evaluation_forms_controller.rb b/app/controllers/evaluation_forms_controller.rb index b51f7cc2..cea28b06 100644 --- a/app/controllers/evaluation_forms_controller.rb +++ b/app/controllers/evaluation_forms_controller.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# Controller for evaluation forms CRUD actions. class EvaluationFormsController < ApplicationController before_action -> { authorize_user('challenge_manager') } before_action :set_evaluation_form, only: %i[show edit update destroy] diff --git a/app/controllers/evaluations_controller.rb b/app/controllers/evaluations_controller.rb index 7f8ddccb..96336e78 100644 --- a/app/controllers/evaluations_controller.rb +++ b/app/controllers/evaluations_controller.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# Controller for evaluations CRUD actions. class EvaluationsController < ApplicationController before_action -> { authorize_user('evaluator') } def index; end diff --git a/app/controllers/evaluators_controller.rb b/app/controllers/evaluators_controller.rb index 6e49075d..123f4523 100644 --- a/app/controllers/evaluators_controller.rb +++ b/app/controllers/evaluators_controller.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# Controller for evaluators CRUD actions. class EvaluatorsController < ApplicationController before_action -> { authorize_user('challenge_manager') } diff --git a/app/controllers/phases_controller.rb b/app/controllers/phases_controller.rb index a5d85943..e9015b80 100644 --- a/app/controllers/phases_controller.rb +++ b/app/controllers/phases_controller.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# Controller for challenge phases CRUD actions. class PhasesController < ApplicationController before_action -> { authorize_user('challenge_manager') } before_action :set_phase, except: [:index] diff --git a/app/controllers/sessions_controller.rb b/app/controllers/sessions_controller.rb index 6ea317df..1d6be238 100644 --- a/app/controllers/sessions_controller.rb +++ b/app/controllers/sessions_controller.rb @@ -1,5 +1,7 @@ # frozen_string_literal: true +# SessionsConroller manages session requests: login, logout and timeout functions. +# This controller receives the redirect from login.gov and stores the valid user session. class SessionsController < ApplicationController before_action :check_error_result, :require_code_param, :exchange_token, only: [:result] skip_before_action :check_session_expiration, only: [:timeout, :destroy] diff --git a/app/controllers/submissions_controller.rb b/app/controllers/submissions_controller.rb index 8f766380..b0fa2af9 100644 --- a/app/controllers/submissions_controller.rb +++ b/app/controllers/submissions_controller.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# Controller for challenge submissions CRUD actions. class SubmissionsController < ApplicationController before_action -> { authorize_user('challenge_manager') } before_action :set_submission, only: [:show, :update] diff --git a/app/helpers/application_helper.rb b/app/helpers/application_helper.rb index 15b06f0f..a8c434bb 100644 --- a/app/helpers/application_helper.rb +++ b/app/helpers/application_helper.rb @@ -1,4 +1,6 @@ # frozen_string_literal: true +# ApplicationHelper is the helper for generic helper methods. +# Think twice before adding random stuff here. module ApplicationHelper end diff --git a/app/helpers/dashboard_helper.rb b/app/helpers/dashboard_helper.rb index a1c93ee2..f0615d31 100644 --- a/app/helpers/dashboard_helper.rb +++ b/app/helpers/dashboard_helper.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# View helpers for the main dashboard templates supporting various user roles. module DashboardHelper def dashboard_cards_by_role { diff --git a/app/helpers/evaluation_forms_helper.rb b/app/helpers/evaluation_forms_helper.rb index 6164fe39..7aad7cda 100644 --- a/app/helpers/evaluation_forms_helper.rb +++ b/app/helpers/evaluation_forms_helper.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# View helpers for rendering evaluation forms. module EvaluationFormsHelper def challenge_with_phase(evaluation_form) challenge_phase_title(evaluation_form.challenge, evaluation_form.phase) diff --git a/app/helpers/evaluators_helper.rb b/app/helpers/evaluators_helper.rb index f39199e9..bfde479e 100644 --- a/app/helpers/evaluators_helper.rb +++ b/app/helpers/evaluators_helper.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# View helpers for rendering users with the evaluator role. module EvaluatorsHelper def user_status(evaluator) if evaluator.is_a?(User) diff --git a/app/helpers/navigation_helper.rb b/app/helpers/navigation_helper.rb index d1d21798..25a93eb2 100644 --- a/app/helpers/navigation_helper.rb +++ b/app/helpers/navigation_helper.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# View helpers for the top navigation bar and utility menu. module NavigationHelper def utility_menu_link(image_path, href, _alt, button_label) link_to(href, diff --git a/app/helpers/phases_helper.rb b/app/helpers/phases_helper.rb index 97829d9f..20ab10a4 100644 --- a/app/helpers/phases_helper.rb +++ b/app/helpers/phases_helper.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# View helpers for challenge phases. module PhasesHelper def phase_number(challenge, phase) challenge.phase_ids.index(phase.id) + 1 diff --git a/app/helpers/submissions_helper.rb b/app/helpers/submissions_helper.rb index 75e9cf9b..6e6f7f93 100644 --- a/app/helpers/submissions_helper.rb +++ b/app/helpers/submissions_helper.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# View helpers for submissions. module SubmissionsHelper def eligible_for_evaluation?(submission) submission.judging_status.in?(%w[selected winner]) diff --git a/app/helpers/users_helper.rb b/app/helpers/users_helper.rb index 4dc909ed..0771ab29 100644 --- a/app/helpers/users_helper.rb +++ b/app/helpers/users_helper.rb @@ -1,4 +1,5 @@ # frozen_string_literal: true +# View helpers for rendering generic users. module UsersHelper end diff --git a/app/mailers/application_mailer.rb b/app/mailers/application_mailer.rb index 5cc63a0c..6bcb26d4 100644 --- a/app/mailers/application_mailer.rb +++ b/app/mailers/application_mailer.rb @@ -1,5 +1,7 @@ # frozen_string_literal: true +# The main app mailer for sending emails. +# The app does not process inbound messages. class ApplicationMailer < ActionMailer::Base default from: "from@example.com" layout "mailer" diff --git a/app/models/application_record.rb b/app/models/application_record.rb index 4e9fa68d..fca03aaf 100644 --- a/app/models/application_record.rb +++ b/app/models/application_record.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# ApplicationRecord is the primary base class for DB backed models under app/models. class ApplicationRecord < ActiveRecord::Base primary_abstract_class diff --git a/app/models/challenge_manager.rb b/app/models/challenge_manager.rb index 8d0d2310..98476244 100644 --- a/app/models/challenge_manager.rb +++ b/app/models/challenge_manager.rb @@ -9,7 +9,6 @@ # user_id :bigint # revoked_at :datetime # - class ChallengeManager < ApplicationRecord belongs_to :challenge belongs_to :user diff --git a/app/models/evaluation_criterion.rb b/app/models/evaluation_criterion.rb index 922fb813..c0f83b49 100644 --- a/app/models/evaluation_criterion.rb +++ b/app/models/evaluation_criterion.rb @@ -4,18 +4,18 @@ # # Table name: evaluation_criteria # -# id :bigint not null, primary key -# title :string not null -# description :string not null -# points_or_weight :smallint not null -# scoring_type :integer not null -# option_range_start :smallint -# option_range_end :smallint -# option_labels :json default([]) -# evaluation_form_id :bigint not null -# created_at :datetime not null -# updated_at :datetime not null - +# id :bigint not null, primary key +# evaluation_form_id :bigint not null +# title :string not null +# description :string not null +# points_or_weight :integer not null +# scoring_type :integer not null +# option_range_start :integer +# option_range_end :integer +# option_labels :json +# created_at :datetime not null +# updated_at :datetime not null +# class EvaluationCriterion < ApplicationRecord self.table_name = 'evaluation_criteria' diff --git a/app/models/evaluation_form.rb b/app/models/evaluation_form.rb index 132813ae..5892021c 100644 --- a/app/models/evaluation_form.rb +++ b/app/models/evaluation_form.rb @@ -5,15 +5,15 @@ # Table name: evaluation_forms # # id :bigint not null, primary key -# title :string -# instructions :string -# phase_id :integer +# title :string not null +# instructions :string not null # comments_required :boolean default(FALSE) # weighted_scoring :boolean default(FALSE) -# closing_date :date -# challenge_id :bigint +# closing_date :date not null +# challenge_id :bigint not null # created_at :datetime not null # updated_at :datetime not null +# phase_id :bigint not null # class EvaluationForm < ApplicationRecord belongs_to :challenge diff --git a/app/models/evaluator_invitation.rb b/app/models/evaluator_invitation.rb index 42ffa177..b22ab9c1 100644 --- a/app/models/evaluator_invitation.rb +++ b/app/models/evaluator_invitation.rb @@ -10,7 +10,7 @@ # first_name :string not null # last_name :string not null # email :string not null -# last_invite_sent :datetime not null +# last_invite_sent :datetime # created_at :datetime not null # updated_at :datetime not null # diff --git a/app/models/evaluator_submission_assignment.rb b/app/models/evaluator_submission_assignment.rb index 77e6d210..3f246292 100644 --- a/app/models/evaluator_submission_assignment.rb +++ b/app/models/evaluator_submission_assignment.rb @@ -1,5 +1,16 @@ # frozen_string_literal: true +# == Schema Information +# +# Table name: evaluator_submission_assignments +# +# id :bigint not null, primary key +# user_id :bigint not null +# submission_id :bigint not null +# status :integer not null +# created_at :datetime not null +# updated_at :datetime not null +# class EvaluatorSubmissionAssignment < ApplicationRecord belongs_to :submission belongs_to :evaluator, class_name: "User", foreign_key: :user_id, inverse_of: :assigned_submissions diff --git a/app/models/login_gov.rb b/app/models/login_gov.rb index 7d4e398e..69ba7036 100644 --- a/app/models/login_gov.rb +++ b/app/models/login_gov.rb @@ -1,6 +1,9 @@ # frozen_string_literal: true +# LoginGov manages authentication with the external login.gov service +# login.gov is a single-signon (SSO) identity provider (IdP) for GSA. class LoginGov + # helper class for errors from the LoginGov API class LoginApiError < StandardError attr_reader :status_code, :response_body diff --git a/app/models/phase.rb b/app/models/phase.rb index 601ea989..e476c70f 100644 --- a/app/models/phase.rb +++ b/app/models/phase.rb @@ -5,21 +5,19 @@ # Table name: phases # # id :bigint not null, primary key -# uuid :uuid not null, default: -> { "gen_random_uuid()" } -# title :string +# challenge_id :bigint not null +# uuid :uuid not null +# title :string(255) # start_date :datetime # end_date :datetime -# open_to_submissions :boolean -# judging_criteria :string -# judging_criteria_delta :string -# judging_criteria_length :integer virtual -# how_to_enter :string -# how_to_enter_delta :string -# how_to_enter_length :integer virtual -# delete_phase :boolean virtual -# challenge_id :bigint not null -# created_at :datetime not null +# open_to_submissions :boolean +# judging_criteria :text +# judging_criteria_delta :text +# how_to_enter :text +# how_to_enter_delta :text +# inserted_at :datetime not null # updated_at :datetime not null +# submissions_count :integer default(0), not null # class Phase < ApplicationRecord belongs_to :challenge diff --git a/app/models/submission.rb b/app/models/submission.rb index 0090bd2c..6bd3c140 100644 --- a/app/models/submission.rb +++ b/app/models/submission.rb @@ -1,5 +1,30 @@ # frozen_string_literal: true +# == Schema Information +# +# Table name: submissions +# +# id :bigint not null, primary key +# submitter_id :bigint not null +# challenge_id :bigint not null +# title :string(255) +# brief_description :text +# description :text +# external_url :string(255) +# status :string(255) +# deleted_at :datetime +# inserted_at :datetime not null +# updated_at :datetime not null +# phase_id :bigint not null +# judging_status :string(255) default("not_selected") +# manager_id :bigint +# terms_accepted :boolean +# review_verified :boolean +# description_delta :text +# brief_description_delta :text +# pdf_reference :string(255) +# comments :text +# class Submission < ApplicationRecord enum :status, { draft: "draft", submitted: "submitted" } enum :judging_status, { not_selected: "not_selected", selected: "selected", qualified: "qualified", winner: "winner" } diff --git a/app/services/evaluator_management_service.rb b/app/services/evaluator_management_service.rb index 58c4e2d9..30bd8fe5 100644 --- a/app/services/evaluator_management_service.rb +++ b/app/services/evaluator_management_service.rb @@ -1,5 +1,6 @@ # frozen_string_literal: true +# This service handles evaluator invitation as well as adding and removing evalutors to challenge phases. class EvaluatorManagementService def initialize(challenge, phase) @challenge = challenge diff --git a/spec/factories/evaluation_criteria.rb b/spec/factories/evaluation_criteria.rb index 7ccac084..e546cdc3 100644 --- a/spec/factories/evaluation_criteria.rb +++ b/spec/factories/evaluation_criteria.rb @@ -1,3 +1,19 @@ +# == Schema Information +# +# Table name: evaluation_criteria +# +# id :bigint not null, primary key +# evaluation_form_id :bigint not null +# title :string not null +# description :string not null +# points_or_weight :integer not null +# scoring_type :integer not null +# option_range_start :integer +# option_range_end :integer +# option_labels :json +# created_at :datetime not null +# updated_at :datetime not null +# FactoryBot.define do factory :evaluation_criterion, class: 'EvaluationCriterion' do # Associations diff --git a/spec/models/challenge_phases_evaluator_spec.rb b/spec/models/challenge_phases_evaluator_spec.rb index aba181ed..2d2b914e 100644 --- a/spec/models/challenge_phases_evaluator_spec.rb +++ b/spec/models/challenge_phases_evaluator_spec.rb @@ -1,3 +1,14 @@ +# == Schema Information +# +# Table name: challenge_phases_evaluators +# +# id :bigint not null, primary key +# challenge_id :bigint not null +# phase_id :bigint not null +# user_id :bigint not null +# created_at :datetime not null +# updated_at :datetime not null +# require 'rails_helper' RSpec.describe ChallengePhasesEvaluator, type: :model do diff --git a/spec/models/evaluation_criterion_spec.rb b/spec/models/evaluation_criterion_spec.rb index 24d56226..d366245b 100644 --- a/spec/models/evaluation_criterion_spec.rb +++ b/spec/models/evaluation_criterion_spec.rb @@ -1,3 +1,19 @@ +# == Schema Information +# +# Table name: evaluation_criteria +# +# id :bigint not null, primary key +# evaluation_form_id :bigint not null +# title :string not null +# description :string not null +# points_or_weight :integer not null +# scoring_type :integer not null +# option_range_start :integer +# option_range_end :integer +# option_labels :json +# created_at :datetime not null +# updated_at :datetime not null +# require 'rails_helper' RSpec.describe EvaluationCriterion, type: :model do diff --git a/spec/models/evaluation_form_spec.rb b/spec/models/evaluation_form_spec.rb index 4beb2295..e4cdc1f6 100644 --- a/spec/models/evaluation_form_spec.rb +++ b/spec/models/evaluation_form_spec.rb @@ -3,15 +3,15 @@ # Table name: evaluation_forms # # id :bigint not null, primary key -# title :string -# instructions :string -# phase_id :integer +# title :string not null +# instructions :string not null # comments_required :boolean default(FALSE) # weighted_scoring :boolean default(FALSE) -# closing_date :date -# challenge_id :bigint +# closing_date :date not null +# challenge_id :bigint not null # created_at :datetime not null # updated_at :datetime not null +# phase_id :bigint not null # require 'rails_helper' diff --git a/spec/models/evaluator_invitation_spec.rb b/spec/models/evaluator_invitation_spec.rb index eab3e072..3717fe40 100644 --- a/spec/models/evaluator_invitation_spec.rb +++ b/spec/models/evaluator_invitation_spec.rb @@ -1,3 +1,17 @@ +# == Schema Information +# +# Table name: evaluator_invitations +# +# id :bigint not null, primary key +# challenge_id :bigint not null +# phase_id :bigint not null +# first_name :string not null +# last_name :string not null +# email :string not null +# last_invite_sent :datetime +# created_at :datetime not null +# updated_at :datetime not null +# require 'rails_helper' RSpec.describe EvaluatorInvitation, type: :model do diff --git a/spec/models/evaluator_submission_assignment_spec.rb b/spec/models/evaluator_submission_assignment_spec.rb index a12d490f..9b6f6680 100644 --- a/spec/models/evaluator_submission_assignment_spec.rb +++ b/spec/models/evaluator_submission_assignment_spec.rb @@ -1,3 +1,14 @@ +# == Schema Information +# +# Table name: evaluator_submission_assignments +# +# id :bigint not null, primary key +# user_id :bigint not null +# submission_id :bigint not null +# status :integer not null +# created_at :datetime not null +# updated_at :datetime not null +# require 'rails_helper' RSpec.describe EvaluatorSubmissionAssignment, type: :model do diff --git a/spec/models/submission_spec.rb b/spec/models/submission_spec.rb index 2eab74de..fc3e416f 100644 --- a/spec/models/submission_spec.rb +++ b/spec/models/submission_spec.rb @@ -1,3 +1,28 @@ +# == Schema Information +# +# Table name: submissions +# +# id :bigint not null, primary key +# submitter_id :bigint not null +# challenge_id :bigint not null +# title :string(255) +# brief_description :text +# description :text +# external_url :string(255) +# status :string(255) +# deleted_at :datetime +# inserted_at :datetime not null +# updated_at :datetime not null +# phase_id :bigint not null +# judging_status :string(255) default("not_selected") +# manager_id :bigint +# terms_accepted :boolean +# review_verified :boolean +# description_delta :text +# brief_description_delta :text +# pdf_reference :string(255) +# comments :text +# require 'rails_helper' RSpec.describe Submission, type: :model do