[ubmarco]

Problem

Fixes #88.

The one-line marker scanner locates the start sequence with str.find, so it
matches the sequence (default @) anywhere in a comment. When @ appears
inside free-form prose followed by a comma, the text is mis-parsed as
title, id, … and the bogus id (with spaces/specials) later fails the
sphinx-needs id regex with InvalidNeedException:

// See @author, check the example      → id = "check the example"  → InvalidNeedException
// We parse things matching @pattern, then act
// Some prose that mentions @@another-tag(item_1, item_2): more text

Fix

Anchor markers whose end_sequence is the newline (i.e. they run to
end-of-line) to the start of the comment content: only comment decoration
(//, #, *, ///, //!, …) and whitespace may precede the start sequence.
A word character before it means the sequence is prose, and the line is ignored.

Explicitly-bounded markers (e.g. [[ … ]]) are self-delimiting, so they stay
position-independent and may still be embedded after prose — this is what keeps
the recommended bracket-style workaround (and the existing supercharge.cpp
fixture) working.

Tests

• New: the three issue-codelinks: One-line marker scanner triggers on @-mentions anywhere in a comment line, not just at line start #88 prose lines are ignored; decoration-prefixed markers
  (line-comment, indented, block *, ///, //!) still parse; a bounded
  [[ … ]] marker embedded after prose still parses.
• Full suite green (271 passed), mypy clean.

Workaround (no upgrade required)

Switch the affected project to a self-delimiting bracket style, which does not
collide with @ in prose:

[codelinks.projects.<name>.analyse.oneline_comment_style]
start_sequence = "[["
end_sequence   = "]]"

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.44%. Comparing base (43927d0) to head (929401d).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #89      +/-   ##
==========================================
+ Coverage   91.40%   91.44%   +0.04%     
==========================================
  Files          34       34              
  Lines        3012     3027      +15     
  Branches      322      323       +1     
==========================================
+ Hits         2753     2768      +15     
  Misses        160      160              
  Partials       99       99              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ubmarco]

Correct, well-tested, and merge-ready. One backwards-incompatible behavior change worth a changelog note; the rest are minor.

The guard is well-placed — right after start_idx is located, before field parsing — and localized to oneline_parser.py.

Backwards-compat (intended, but please note in the release notes)

For newline-terminated styles (the default @), a marker is now recognized only if nothing alphanumeric precedes it on the comment line. Previously @ matched anywhere and the pre-@ text was discarded, so these previously parsed and are now ignored:

// TODO @My Title, ID
// NOTE: @My Title, ID
// some description @Title, ID

The drop is silent — oneline_parser returns None, which extract_oneline_need treats as "no marker", so no warning is emitted. That is the right call for the prose case in #88 (which otherwise crashed the build with InvalidNeedException), and the documented style always puts the marker first, so real-world impact is low. Still worth stating explicitly: newline-terminated markers must now start the comment content.

Correctness — verified

• The guard uses the original start_idx (before it is advanced past the start sequence). ✔
• All standard comment leaders (//, #, *, ///, //!, /*) are non-alphanumeric, so decoration-prefixed markers still parse — covered by the new tests. ✔
• Bracket style is unaffected: end_sequence != "\n", so the guard is skipped and [[ … ]] stays position-independent (covered). ✔
• Empty / whitespace-only prefix pass; no false negatives for the standard style.
• Pure function, single O(n) scan — no perf or durability concern.

Minor

• The comment "Explicitly-bounded markers … are self-delimiting … exempt" is keyed in code on end_sequence == newline, not on bracket-ness. A hypothetical start="[[", end="\n" config would still be anchored. Consider rewording to "markers not terminated by newline are exempt."
• Latent: if a language with an alphanumeric comment leader is ever supported (e.g. Batch REM), REM @T, ID would be wrongly rejected by the alnum predicate. Not reachable today.

No outstanding review comments to address.