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

[gitguardian]

⚠️ GitGuardian has uncovered 1 secret following the scan of your pull request.

Please consider investigating the findings and remediating the incidents. Failure to do so may lead to compromising the associated services or software components.

🔎 Detected hardcoded secret in your pull request

GitGuardian id	GitGuardian status	Secret	Commit	Filename
21945278	Triggered	Generic Password	ee65db4	docassemble/AssemblyLine/data/sources/fr-words.yml	View secret

🛠 Guidelines to remediate hardcoded secrets

1. Understand the implications of revoking this secret by investigating where it is used in your code.
2. Replace and store your secret safely. Learn here the best practices.
3. Revoke and rotate this secret.
4. If possible, rewrite git history. Rewriting git history is not a trivial act. You might completely break other contributing developers' workflow and you risk accidentally deleting legitimate data.

To avoid such incidents in the future consider

• following these best practices for managing and storing secrets including API keys and other credentials
• install secret detection on pre-commit to catch secret before it leaves your machine and ease remediation.

---

^{🦉 GitGuardian detects secrets in your source code to help developers and security teams secure the modern development process. You are seeing this because you or someone else with access to this repository has authorized GitGuardian to scan your pull request.}