@team: annotations with colons don't work (but look like they should)

[technicalpickles]

@team: annotations with colons don't work (but look like they should)

What's happening

If you write @team: SomeTeam (with a colon), the gem just ignores it completely. The file shows up as "unowned" even though it looks like it has a perfectly valid team annotation. There's no error or warning - it just silently doesn't work.

What works vs what doesn't

This works ✅:

# @team Developer Productivity Async

This doesn't work ❌:

# @team: Developer Productivity Async

The difference? Just that colon after @team.

Why this is annoying

1. Silent failures - Your file just shows up as "unowned" with zero indication why
2. Confusing build errors - You get "missing ownership" errors even though the file clearly has a team annotation
3. Feels broken - The annotation looks totally fine but just doesn't work
4. Hard to debug - Nothing tells you the colon is the problem
5. Inconsistent codebases - Some people figure out the no-colon rule, others don't

Real example that bit us

We had a file with # @team: Developer Productivity Async at the top. Looked fine, right?

• bin/codeownership for_file spec/support/kafka_migration_validation.rb → "Unowned" 🤔
• bin/codeownership validate --skip-autocorrect → "Some files are missing ownership" 😤
• The error gave us no clue what was wrong
• Had to manually compare against other files to figure out the colon was the problem

Why this happens

The regex in lib/code_ownership/private/ownership_mappers/file_annotations.rb looks for this exact pattern:

TEAM_PATTERN = T.let(%r{\A(?:#|//|-#) @team (?<team>.*)\Z}.freeze, Regexp)

It expects exactly @team (with a space) but doesn't handle @team: (with a colon). So the regex just doesn't match.

Environment

• code_ownership version: 1.39.0
• Ruby version: 3.4.5
• Repository: Large monorepo with ~600+ team annotations

Why people expect colons to work

Every other Ruby magic comment uses colons:

# frozen_string_literal: true
# typed: strict  
# encoding: UTF-8
# rubocop:disable Style/StringLiterals

So when you're writing a file header, this feels totally natural:

# @team: Developer Productivity Async
# typed: strict
# frozen_string_literal: true

But only the @team line gets ignored while the others work fine. It's just inconsistent with how the rest of the Ruby ecosystem works.

[technicalpickles]

Follow-up Comment: Proposed Solutions

Potential Solutions

After thinking about this more, here are a few ways this could be addressed:

Option 1: Support both formats (recommended)

Change: Update the regex to make the colon optional:

TEAM_PATTERN = T.let(%r{\A(?:#|//|-#) @team:?\s+(?<team>.*)\Z}.freeze, Regexp)

Pros:

• ✅ Fully backward compatible - existing annotations keep working
• ✅ Follows principle of least surprise - both natural formats work
• ✅ Aligns with Ruby ecosystem conventions (colon-based magic comments)
• ✅ Minimal code change - just the regex pattern
• ✅ No migration needed for existing codebases

Cons:

• ❌ Allows two different styles in the same codebase (though this already happens due to the confusion)

Option 2: Better error messages

Change: Detect colon usage and show a helpful error message

Pros:

• ✅ Maintains current strict format requirements
• ✅ Much better developer experience than silent failures
• ✅ Guides users toward the correct format

Cons:

• ❌ Still requires developers to fix their annotations
• ❌ Doesn't solve the ecosystem inconsistency problem
• ❌ More complex implementation (need to detect and warn)

Option 3: Auto-migration tool

Change: Provide a command to convert @team: to @team format

Pros:

• ✅ Helps existing codebases migrate
• ✅ Maintains format consistency

Cons:

• ❌ Doesn't prevent the problem from happening again
• ❌ Still leaves the ecosystem inconsistency
• ❌ Requires manual intervention

My take

Option 1 seems like the best approach because:

1. It's what users expect - When every other Ruby magic comment uses colons, @team: feels natural
2. Zero breaking changes - All existing code continues to work unchanged
3. Fixes the root cause - No more silent failures or confusion
4. Simple implementation - Just a small regex change

The "two formats" concern is pretty minor since:

• Many codebases already have mixed formats due to this confusion
• Teams can standardize on one format via linting if they want consistency
• Both formats are equally readable and clear

What do you think? Happy to help test any approach you'd prefer!