refactor for reads and writes to immigration model of fa applicant

[saikumar9]

PR Checklist

Please check if your PR fulfills the following requirements:

• The title follows our guidelines
• Tests for the changes have been added (for bug fixes/features), and they use let helpers and before blocks.
• For all UI changes, there is Cucumber coverage.
• Any endpoint touched in the PR has an appropriate Pundit policy. For open endpoints, the reasoning is documented in the PR and code.
• Any endpoint modified in the PR only responds to the expected MIME types.
• For all scripts or rake tasks, how to run them is documented in both the PR and the code.
• There are no inline styles added.
• There is no inline JavaScript added.
• There is no hard-coded text added/updated in helpers/views/JavaScript. New/updated translation strings do not include markup/styles unless there is supporting documentation.
• Code does not use .html_safe.
• All images added/updated have alt text.
• Does not bypass RuboCop rules in any way.

PR Type

What kind of change does this PR introduce?:

• Bugfix
• Feature (requires Feature flag)
• Data fix, Migration, or Report (inert code, no impact until run)
• Refactoring (no functional changes, no API changes)
• Build related changes
• CI related changes
• Dependency updates (e.g., add a new gem or update to a version)
• Release (Prepares code for a release, e.g., version bumps, changelog updates, tagging, deployment scripts)

What is the ticket # detailing the issue?

Ticket: CU-868hw0g86

A brief description of the changes:

Current behavior: N/A

New behavior: Adds new immigration_information model as part of the VLP upgrade to V37.1.2 project for separating immigration related information into a separate model for both Financial Assistance and Individual Market Applications.

Feature Flag

For all new feature development, a feature flag is required to control the exposure of the feature to our end users. A feature flag needs a corresponding environment variable to initialize the state of the flag. Please share the name of the environment variable below that would enable/disable the feature and indicate which client(s) it applies to.

Variable name:

• DC
• ME

Additional Context

Include any additional context that may be relevant to the peer review process.

---

This pull request implements a major refactor to how immigration information is handled for financial assistance applicants, driven by the new :vlp_upgrade_v37_1_2 feature flag. When enabled, individual immigration fields are deprecated in favor of a single embedded immigration_information object, which centralizes and standardizes the management of all immigration-related attributes and document statuses. The changes also introduce a suite of helper methods for document type validation, update controller logic to support the new structure, and ensure backward compatibility when the feature flag is disabled.

Key changes include:

1. Migration to Embedded Immigration Information Object

• When the :vlp_upgrade_v37_1_2 feature is enabled, applicant immigration data is now managed through an embedded immigration_information object, replacing the previous use of individual fields. This includes updating parameter parsing, attribute assignment, and serialization logic across the codebase. [1] [2] [3] [4] [5] [6]

2. Controller and Parameter Handling Updates

• The ApplicantsController is updated to conditionally permit and process the new immigration_information parameters, including a new build_or_update_immigration_information method to safely assign or update the embedded object. The update and edit actions are also adjusted to use the new structure when the feature is enabled. [1] [2] [3] [4]

3. Model Enhancements and Helper Methods

• The ImmigrationInformation model now stores expiration_date as a Date (not DateTime) and adds a comprehensive set of helper methods for validating the presence and correctness of document-type-specific fields, improving code clarity and maintainability. [1] [2]

4. Backward Compatibility and Feature Flag Support

• All changes are gated behind the :vlp_upgrade_v37_1_2 feature flag, ensuring that legacy logic using individual fields is preserved and only replaced when the feature is enabled. This includes conditional logic in attribute construction, parameter merging, and VLP document management. [1] [2] [3]

5. Data Synchronization and Migration Logic

• Updates to person and applicant objects ensure that immigration_doc_statuses and VLP document fields are correctly synchronized between the new embedded object and the existing data model, minimizing risk of stale or inconsistent data during the transition. [1] [2] [3]

These changes lay the groundwork for a more robust and extensible approach to managing immigration documentation, improving both data integrity and developer experience.

[Copilot]

Pull request overview

This PR refactors Financial Assistance applicant VLP (immigration) reads/writes to use the embedded ImmigrationInformation document (behind the :vlp_upgrade_v37_1_2 feature flag), while keeping legacy vlp_* fields for non-upgraded behavior.

Changes:

• Adds nested immigration_information parameter handling across FAA form object, controller, and views (feature-flagged).
• Moves VLP document-type predicate logic onto ImmigrationInformation and delegates FAA applicant checks to the embedded model when upgraded.
• Expands test coverage to validate nested immigration_information behavior, persistence, and legacy alias removal.

Reviewed changes

Copilot reviewed 35 out of 35 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
spec/models/immigration_information_spec.rb	Updates expiration_date type expectation; adds alias-removal expectations.
components/financial_assistance/spec/models/financial_assistance/forms/applicant_spec.rb	Adds extensive integration specs for nested immigration_information behavior in FAA form.
components/financial_assistance/spec/models/financial_assistance/applicant_spec.rb	Updates legacy i766 setup for feature flag; adds upgraded VLP predicate coverage.
components/financial_assistance/spec/controllers/financial_assistance/applicants_controller_spec.rb	Adds controller specs for nested immigration_information edit/update behavior when upgraded.
components/financial_assistance/app/views/financial_assistance/shared/_naturalization_cert_fields.html.erb	Switches hidden subject field between :subject and :vlp_subject based on feature flag.
components/financial_assistance/app/views/financial_assistance/shared/_immigration_document_fields.html.erb	Allows helpers/hidden fields to target the applicant even when rendering nested fields_for.
components/financial_assistance/app/views/financial_assistance/shared/_consumer_fields.html.erb	Wraps immigration doc fields in fields_for :immigration_information when upgraded.
components/financial_assistance/app/views/financial_assistance/shared/_citizenship_cert_fields.html.erb	Switches hidden subject field between :subject and :vlp_subject based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/immigration_document_options.js.erb	Renders immigration doc partials using nested fields_for when upgraded.
components/financial_assistance/app/views/financial_assistance/applicants/edit.js.erb	Initializes FAA immigration doc JS fields on edit.
components/financial_assistance/app/views/financial_assistance/applicants/docs_shared/_document_description.html.erb	Switches between :description and :vlp_description based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_unexpired_foreign_passport_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_temporary_i_551_stamp_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_other_with_i94_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_other_with_alien_number_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_machine_readable_immigrant_visa_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_i_94_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_i_94_2_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_i_766_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_i_571_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_i_551_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_i_327_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_i_20_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/views/financial_assistance/applicants/_ds_2019_fields.html.erb	Switches hidden subject field based on feature flag.
components/financial_assistance/app/models/financial_assistance/forms/applicant.rb	Adds nested immigration_information setter/getter, immigration_params, and save-time persistence/clearing logic.
components/financial_assistance/app/models/financial_assistance/applicant.rb	Deprecates flat VLP fields under flag; delegates VLP predicates to embedded immigration_information when upgraded.
components/financial_assistance/app/domain/financial_assistance/validators/immigration_information_contract.rb	Introduces a Dry::Validation contract intended for nested immigration info.
components/financial_assistance/app/domain/financial_assistance/validators/applicant_contract.rb	Adds immigration_information key; reorganizes deprecated VLP fields.
components/financial_assistance/app/domain/financial_assistance/operations/application/create.rb	Builds embedded immigration_information during application create.
components/financial_assistance/app/domain/financial_assistance/entities/immigration_information.rb	Adds a Dry::Struct entity for immigration info.
components/financial_assistance/app/domain/financial_assistance/entities/applicant.rb	Adds immigration_information field on applicant entity.
components/financial_assistance/app/controllers/financial_assistance/applicants_controller.rb	Reads subject from embedded doc on edit; permits nested params; adds build/update helper.
app/models/individual_market/applicant.rb	Documents embeds_one immigration_information behavior and flag-dependent class selection.
app/models/immigration_information.rb	Changes expiration_date to Date; adds document-type predicate methods.
app/domain/operations/financial_assistance/parse_applicant.rb	Emits immigration_information hash instead of flat VLP fields when upgraded.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 38 out of 38 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[satish2025-crew]

Looks good