Add preferred_name support to ALIndividual.familiar() method

[Copilot]

The familiar() method in ALIndividual now uses preferred_name.first when available, providing better support for individuals who go by a name different from their legal first name.

Changes Made

Updated ALIndividual.familiar() method

• Added logic to check for preferred_name.first and use it when available and non-empty
• Falls back to existing name.first behavior when preferred_name is not set, empty, or None
• Updated all internal references within the method to use the determined first name consistently
• Business and organization person types continue to use name.first as before (no behavior change)

Implementation

# Use preferred_name.first if it exists and is non-empty, otherwise use name.first
first_name_to_use = self.name.first
if (hasattr(self, "preferred_name") and 
    hasattr(self.preferred_name, "first") and 
    self.preferred_name.first):
    first_name_to_use = self.preferred_name.first

Added comprehensive tests

• Basic preferred_name functionality and fallback behavior
• Business/organization type compatibility verification
• Name conflict resolution scenarios
• Edge cases (empty strings, None values, whitespace)

Added interactive test file

• test_preferred_name.yml: Interactive docassemble test that includes assembly_line.yml and provides manual verification of preferred name functionality
• Tests multiple scenarios: with/without preferred name, business entities, and conflict resolution
• Includes ending screen that demonstrates .familiar() behavior for each test case

Behavior Examples

# Without preferred_name (existing behavior)
individual.name.first = "Robert"
individual.familiar()  # Returns "Robert"

# With preferred_name set
individual.preferred_name.first = "Bob" 
individual.familiar()  # Returns "Bob"

# Business types ignore preferred_name
business.person_type = "business"
business.name.first = "Acme Corp"
business.preferred_name.first = "ACME"
business.familiar()  # Returns "Acme Corp" (unchanged)

Backward Compatibility

This change is fully backward compatible. Existing code using .familiar() will continue to work exactly as before unless preferred_name is explicitly set.

Fixes #688.

---

💬 Share your feedback on Copilot coding agent for the chance to win a $200 gift card! Click here to start the survey.

[nonprofittechy]

@copilot using existing test_feature.yml as a model, can you add a test_preferred_name.yml that goes through the iterations for an interactive confirmation of the behavior:

• includes assembly_line.yml
• asks for preferred name in various combinations, or doesn't ask for it so we can test each branch interactively
• has an ending screen that shows .familiar()

[Copilot]

@copilot using existing test_feature.yml as a model, can you add a test_preferred_name.yml that goes through the iterations for an interactive confirmation of the behavior:

• includes assembly_line...

I've created test_preferred_name.yml as requested, which provides interactive testing of the preferred name functionality. The test file includes:

• Includes assembly_line.yml as specified
• Multiple test scenarios to cover different preferred name combinations:
  • Test with preferred name set
  • Test without preferred name (fallback behavior)
  • Test business with preferred name (should ignore preferred name)
  • Test conflict resolution with multiple people
• Interactive flow that asks for preferred names in various combinations or skips asking to test each branch
• Ending screen that shows .familiar() results and explains the behavior for each scenario

The test allows manual verification of all the preferred name logic paths, including edge cases like business entities ignoring preferred names and conflict resolution when multiple people have similar names.

Commit: 40eed61

[nonprofittechy]

Implementation tested and works as designed

[nonprofittechy]

Will slow down and figure out unit tests