Skip to main content

ferromark_transforms/
github.rs

1//! Optional links for explicit GitHub issue, user, team, and commit references.
2
3use std::error::Error;
4use std::fmt;
5use std::ops::Range;
6
7use ferromark::ast::{Document, Span};
8
9use crate::prose::{NodeList, is_in_raw_html, visit_document_prose};
10use crate::{BoxError, TransformContext, TransformPass, text_runs};
11
12const MIN_COMMIT_LENGTH: usize = 7;
13const MAX_COMMIT_LENGTH: usize = 40;
14const MAX_OWNER_LENGTH: usize = 39;
15const MAX_REPOSITORY_LENGTH: usize = 100;
16const DENIED_BARE_HASHES: [&str; 5] = ["acceded", "deedeed", "defaced", "effaced", "fabaceae"];
17
18/// Error returned when a configured GitHub repository is not a safe `owner/repo` path.
19#[derive(Debug, Clone, PartialEq, Eq)]
20pub struct InvalidGitHubRepository {
21    value: String,
22}
23
24impl InvalidGitHubRepository {
25    /// Returns the rejected repository configuration.
26    #[must_use]
27    pub fn value(&self) -> &str {
28        &self.value
29    }
30}
31
32impl fmt::Display for InvalidGitHubRepository {
33    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
34        write!(
35            formatter,
36            "invalid GitHub repository {:?}; expected an explicit owner/repository with safe ASCII path segments",
37            self.value
38        )
39    }
40}
41
42impl Error for InvalidGitHubRepository {}
43
44/// Links a qualified subset of GitHub references using an explicit repository.
45///
46/// Supported forms are local `#123` and `GH-123` issues, `owner/repo#123`,
47/// `@user`, `@org/team`, 7–40 character hexadecimal commits and `start...end`
48/// commit ranges. Link labels preserve the exact authored text. Existing links,
49/// link destinations and titles, image metadata, code, math, raw HTML, MDX
50/// expressions and renderer-recognized bare URLs stay unchanged. No GitHub API,
51/// repository inference, callback, or filesystem access is used.
52pub struct GitHubReferencesPass {
53    owner: String,
54    repository: String,
55}
56
57impl GitHubReferencesPass {
58    /// Creates a pass for an explicit `owner/repository` pair.
59    ///
60    /// Owner and repository segments are validated before the pass can mutate a
61    /// document. The repository is never inferred from package metadata or Git.
62    pub fn new(repository: &str) -> Result<Self, InvalidGitHubRepository> {
63        let Some((owner, name)) = validated_repository(repository) else {
64            return Err(InvalidGitHubRepository {
65                value: repository.to_owned(),
66            });
67        };
68
69        Ok(Self {
70            owner: owner.to_owned(),
71            repository: name.to_owned(),
72        })
73    }
74}
75
76impl TransformPass for GitHubReferencesPass {
77    fn name(&self) -> &'static str {
78        "github-references"
79    }
80
81    fn apply<'arena>(
82        &mut self,
83        document: &mut Document<'arena>,
84        context: &TransformContext<'arena>,
85    ) -> Result<(), BoxError> {
86        let owner = &self.owner;
87        let repository = &self.repository;
88        let mut visitor = |nodes: &mut NodeList<'arena>,
89                           context: &TransformContext<'arena>,
90                           raw_html_spans: &[Span]| {
91            transform_text_runs(nodes, context, raw_html_spans, owner, repository)
92        };
93        visit_document_prose(document, context, false, &mut visitor)
94    }
95}
96
97struct ReferenceMatch {
98    node_range: Range<usize>,
99    byte_range: Range<usize>,
100    label: String,
101    url: String,
102}
103
104fn transform_text_runs<'arena>(
105    nodes: &mut NodeList<'arena>,
106    context: &TransformContext<'arena>,
107    raw_html_spans: &[Span],
108    local_owner: &str,
109    local_repository: &str,
110) -> Result<(), BoxError> {
111    let mut matches = Vec::new();
112    for run in text_runs(nodes) {
113        if is_in_raw_html(&run, raw_html_spans) {
114            continue;
115        }
116        let value = run.value();
117        let protected = run.protected_url_ranges(context);
118        for matched in find_references(&value, &protected, local_owner, local_repository) {
119            matches.push(ReferenceMatch {
120                node_range: run.node_range(),
121                label: value[matched.range.clone()].to_owned(),
122                byte_range: matched.range,
123                url: matched.url,
124            });
125        }
126    }
127
128    let mut active_run = None;
129    let mut boundary = 0;
130    for matched in matches.into_iter().rev() {
131        let start = matched.node_range.start;
132        if active_run != Some(start) {
133            active_run = Some(start);
134            boundary = matched.node_range.end;
135        }
136        let replacement_span = TransformContext::replace_text_range_with_node(
137            nodes,
138            start..boundary,
139            matched.byte_range,
140            |span| Some(context.text_link_node(&matched.label, &matched.url, span)),
141        )?;
142        boundary = nodes
143            .iter()
144            .position(
145                |node| matches!(node, ferromark::ast::Node::Link(link) if link.span == replacement_span),
146            )
147            .ok_or_else(|| {
148                std::io::Error::other("GitHub reference link node was not inserted")
149            })?;
150    }
151
152    Ok(())
153}
154
155struct TextMatch {
156    range: Range<usize>,
157    url: String,
158}
159
160fn find_references(
161    value: &str,
162    protected: &[Range<usize>],
163    local_owner: &str,
164    local_repository: &str,
165) -> Vec<TextMatch> {
166    let bytes = value.as_bytes();
167    let mut matches = Vec::new();
168    let mut cursor = 0;
169
170    while cursor < bytes.len() {
171        if let Some(range) = protected
172            .iter()
173            .find(|range| range.start <= cursor && cursor < range.end)
174        {
175            cursor = range.end;
176            continue;
177        }
178
179        if let Some((end, url)) = match_reference(value, cursor, local_owner, local_repository)
180            && !protected
181                .iter()
182                .any(|range| cursor < range.end && range.start < end)
183        {
184            matches.push(TextMatch {
185                range: cursor..end,
186                url,
187            });
188            cursor = end;
189        } else {
190            cursor += value[cursor..].chars().next().map_or(1, char::len_utf8);
191        }
192    }
193
194    matches
195}
196
197fn match_reference(
198    value: &str,
199    start: usize,
200    local_owner: &str,
201    local_repository: &str,
202) -> Option<(usize, String)> {
203    let bytes = value.as_bytes();
204    if !left_boundary(value, start) {
205        return None;
206    }
207
208    if let Some((end, owner, repository, reference)) =
209        parse_cross_repository_reference(bytes, start)
210        && right_boundary(value, end)
211    {
212        let url = match reference {
213            RepositoryReference::Issue(number) => issue_url(owner, repository, number),
214            RepositoryReference::Commit(hash) => commit_url(owner, repository, hash),
215        };
216        return Some((end, url));
217    }
218
219    if bytes.get(start) == Some(&b'@')
220        && let Some((end, username, team)) = parse_mention(bytes, start)
221        && left_boundary(value, start)
222        && mention_right_boundary(value, end, team)
223        && !matches_ignore_ascii_case(username, &["mention", "mentions"])
224    {
225        return Some((end, format!("https://github.com/{username}")));
226    }
227
228    if is_gh_prefix(bytes, start)
229        && let Some((end, number)) = parse_issue_number(bytes, start + 3)
230        && right_boundary(value, end)
231    {
232        return Some((end, issue_url(local_owner, local_repository, number)));
233    }
234
235    if bytes.get(start) == Some(&b'#')
236        && let Some((end, number)) = parse_issue_number(bytes, start + 1)
237        && right_boundary(value, end)
238    {
239        return Some((end, issue_url(local_owner, local_repository, number)));
240    }
241
242    if let Some((end, base, compare)) = parse_commit_range(bytes, start)
243        && right_boundary(value, end)
244    {
245        return Some((
246            end,
247            format!(
248                "https://github.com/{local_owner}/{local_repository}/compare/{base}...{compare}"
249            ),
250        ));
251    }
252
253    if let Some((end, hash)) = parse_commit_hash(bytes, start)
254        && right_boundary(value, end)
255        && !matches_ignore_ascii_case(hash, &DENIED_BARE_HASHES)
256        && !bytes
257            .get(end..)
258            .is_some_and(|suffix| suffix.starts_with(b"..."))
259    {
260        return Some((end, commit_url(local_owner, local_repository, hash)));
261    }
262
263    None
264}
265
266enum RepositoryReference<'a> {
267    Issue(&'a str),
268    Commit(&'a str),
269}
270
271fn parse_cross_repository_reference(
272    bytes: &[u8],
273    start: usize,
274) -> Option<(usize, &str, &str, RepositoryReference<'_>)> {
275    let owner_end = parse_account(bytes, start)?;
276    if bytes.get(owner_end) != Some(&b'/') {
277        return None;
278    }
279    let repository_start = owner_end + 1;
280    let repository_end = parse_repository_name(bytes, repository_start)?;
281    let owner = std::str::from_utf8(&bytes[start..owner_end]).ok()?;
282    let repository = std::str::from_utf8(&bytes[repository_start..repository_end]).ok()?;
283
284    match bytes.get(repository_end) {
285        Some(&b'#') => {
286            let (end, number) = parse_issue_number(bytes, repository_end + 1)?;
287            Some((end, owner, repository, RepositoryReference::Issue(number)))
288        }
289        Some(&b'@') => {
290            let (end, hash) = parse_commit_hash(bytes, repository_end + 1)?;
291            Some((end, owner, repository, RepositoryReference::Commit(hash)))
292        }
293        _ => None,
294    }
295}
296
297fn parse_mention(bytes: &[u8], start: usize) -> Option<(usize, &str, bool)> {
298    let user_start = start + 1;
299    let user_end = parse_account(bytes, user_start)?;
300    if bytes.get(user_end) == Some(&b'/') {
301        let team_start = user_end + 1;
302        let team_end = parse_account(bytes, team_start)?;
303        let mention = std::str::from_utf8(&bytes[user_start..team_end]).ok()?;
304        return Some((team_end, mention, true));
305    }
306
307    Some((
308        user_end,
309        std::str::from_utf8(&bytes[user_start..user_end]).ok()?,
310        false,
311    ))
312}
313
314fn parse_account(bytes: &[u8], start: usize) -> Option<usize> {
315    if !bytes.get(start).is_some_and(u8::is_ascii_alphanumeric) {
316        return None;
317    }
318    let mut cursor = start + 1;
319    while bytes
320        .get(cursor)
321        .is_some_and(|byte| byte.is_ascii_alphanumeric() || *byte == b'-')
322    {
323        cursor += 1;
324    }
325    if cursor - start > MAX_OWNER_LENGTH || bytes.get(cursor.wrapping_sub(1)) == Some(&b'-') {
326        return None;
327    }
328    Some(cursor)
329}
330
331fn parse_repository_name(bytes: &[u8], start: usize) -> Option<usize> {
332    let mut cursor = start;
333    while bytes
334        .get(cursor)
335        .is_some_and(|byte| byte.is_ascii_alphanumeric() || matches!(*byte, b'-' | b'_' | b'.'))
336    {
337        cursor += 1;
338    }
339    let length = cursor.checked_sub(start)?;
340    if length == 0 || length > MAX_REPOSITORY_LENGTH {
341        return None;
342    }
343    if &bytes[start..cursor] == b"." || &bytes[start..cursor] == b".." {
344        return None;
345    }
346    Some(cursor)
347}
348
349fn parse_issue_number(bytes: &[u8], start: usize) -> Option<(usize, &str)> {
350    if !bytes
351        .get(start)
352        .is_some_and(|byte| byte.is_ascii_digit() && *byte != b'0')
353    {
354        return None;
355    }
356    let mut cursor = start + 1;
357    while bytes.get(cursor).is_some_and(u8::is_ascii_digit) {
358        cursor += 1;
359    }
360    Some((cursor, std::str::from_utf8(&bytes[start..cursor]).ok()?))
361}
362
363fn parse_commit_hash(bytes: &[u8], start: usize) -> Option<(usize, &str)> {
364    if !bytes.get(start).is_some_and(u8::is_ascii_hexdigit) {
365        return None;
366    }
367    let mut cursor = start + 1;
368    while bytes.get(cursor).is_some_and(u8::is_ascii_hexdigit) {
369        cursor += 1;
370    }
371    let length = cursor - start;
372    if !(MIN_COMMIT_LENGTH..=MAX_COMMIT_LENGTH).contains(&length) {
373        return None;
374    }
375    Some((cursor, std::str::from_utf8(&bytes[start..cursor]).ok()?))
376}
377
378fn parse_commit_range(bytes: &[u8], start: usize) -> Option<(usize, &str, &str)> {
379    let (base_end, base) = parse_commit_hash(bytes, start)?;
380    if bytes
381        .get(base_end..base_end + 3)
382        .is_none_or(|separator| separator != b"...")
383    {
384        return None;
385    }
386    let (end, compare) = parse_commit_hash(bytes, base_end + 3)?;
387    Some((end, base, compare))
388}
389
390fn is_gh_prefix(bytes: &[u8], start: usize) -> bool {
391    bytes
392        .get(start..start + 3)
393        .is_some_and(|prefix| prefix.eq_ignore_ascii_case(b"gh-"))
394}
395
396fn left_boundary(value: &str, start: usize) -> bool {
397    value[..start].chars().next_back().is_none_or(|previous| {
398        !previous.is_alphanumeric() && !matches!(previous, '_' | '-' | '.' | '/' | '@' | '\\')
399    })
400}
401
402fn right_boundary(value: &str, end: usize) -> bool {
403    value[end..]
404        .chars()
405        .next()
406        .is_none_or(|next| !next.is_alphanumeric() && !matches!(next, '_' | '-' | '/'))
407}
408
409fn mention_right_boundary(value: &str, end: usize, team: bool) -> bool {
410    if !right_boundary(value, end) {
411        return false;
412    }
413    if team {
414        return true;
415    }
416
417    let mut suffix = value[end..].chars();
418    match suffix.next() {
419        Some('@') => false,
420        Some('.') => !suffix.next().is_some_and(char::is_alphanumeric),
421        _ => true,
422    }
423}
424
425fn matches_ignore_ascii_case(value: &str, candidates: &[&str]) -> bool {
426    candidates
427        .iter()
428        .any(|candidate| value.eq_ignore_ascii_case(candidate))
429}
430
431fn validated_repository(value: &str) -> Option<(&str, &str)> {
432    let (owner, repository) = value.split_once('/')?;
433    if repository.contains('/') || owner.is_empty() || repository.is_empty() {
434        return None;
435    }
436    let owner_bytes = owner.as_bytes();
437    let repository_bytes = repository.as_bytes();
438    let owner_end = parse_account(owner_bytes, 0)?;
439    let repository_end = parse_repository_name(repository_bytes, 0)?;
440    (owner_end == owner.len() && repository_end == repository.len()).then_some((owner, repository))
441}
442
443fn issue_url(owner: &str, repository: &str, number: &str) -> String {
444    format!("https://github.com/{owner}/{repository}/issues/{number}")
445}
446
447fn commit_url(owner: &str, repository: &str, hash: &str) -> String {
448    format!("https://github.com/{owner}/{repository}/commit/{hash}")
449}
450
451#[cfg(test)]
452mod tests {
453    use super::{GitHubReferencesPass, find_references};
454
455    fn references(source: &str) -> Vec<(String, String)> {
456        find_references(source, &[], "ferromark", "fixtures")
457            .into_iter()
458            .map(|matched| (source[matched.range].to_owned(), matched.url))
459            .collect()
460    }
461
462    #[test]
463    fn validates_explicit_repository_path_segments() {
464        assert!(GitHubReferencesPass::new("ferromark/fixtures").is_ok());
465        for invalid in [
466            "",
467            "ferromark",
468            "/fixtures",
469            "ferromark/",
470            "ferromark/a/b",
471            "ferromark/..",
472            "https://github.com/ferromark/fixtures",
473            "ferromark/repo?query",
474        ] {
475            assert!(GitHubReferencesPass::new(invalid).is_err(), "{invalid:?}");
476        }
477    }
478
479    #[test]
480    fn links_the_qualified_reference_forms_without_changing_labels() {
481        assert_eq!(
482            references(
483                "Fixes #123 and closes gH-7; see org/project#9 and @user, @org/team.\nCommit 1f2a4fb and range e2acebc...2aa9311."
484            ),
485            vec![
486                (
487                    "#123".to_owned(),
488                    "https://github.com/ferromark/fixtures/issues/123".to_owned()
489                ),
490                (
491                    "gH-7".to_owned(),
492                    "https://github.com/ferromark/fixtures/issues/7".to_owned()
493                ),
494                (
495                    "org/project#9".to_owned(),
496                    "https://github.com/org/project/issues/9".to_owned()
497                ),
498                ("@user".to_owned(), "https://github.com/user".to_owned()),
499                (
500                    "@org/team".to_owned(),
501                    "https://github.com/org/team".to_owned()
502                ),
503                (
504                    "1f2a4fb".to_owned(),
505                    "https://github.com/ferromark/fixtures/commit/1f2a4fb".to_owned()
506                ),
507                (
508                    "e2acebc...2aa9311".to_owned(),
509                    "https://github.com/ferromark/fixtures/compare/e2acebc...2aa9311".to_owned()
510                ),
511            ]
512        );
513    }
514
515    #[test]
516    fn excludes_emails_hash_like_words_urls_and_invalid_boundaries() {
517        assert_eq!(
518            references(
519                "foo@bar.com; @mention; @mentions; x#123; #0; #123word; acceded; a1b2c3; https://example.com/x#123."
520            ),
521            Vec::new()
522        );
523        let protected_url = 0..30;
524        assert_eq!(
525            find_references(
526                "See https://example.com/x#123.",
527                std::slice::from_ref(&protected_url),
528                "ferromark",
529                "fixtures"
530            )
531            .len(),
532            0
533        );
534    }
535
536    #[test]
537    fn preserves_large_issue_numbers_without_integer_conversion() {
538        let number = "999999999999999999999999999999999999999999999999";
539        assert_eq!(
540            references(&format!("Fixes #{number}.")),
541            vec![(
542                format!("#{number}"),
543                format!("https://github.com/ferromark/fixtures/issues/{number}")
544            )]
545        );
546    }
547
548    #[test]
549    fn links_cross_repository_commits_and_the_supported_hash_lengths() {
550        let long_hash = "0123456789abcdef0123456789abcdef01234567";
551        let source = format!("org/my_repo@AbCd123 {long_hash}");
552        assert_eq!(
553            references(&source),
554            vec![
555                (
556                    "org/my_repo@AbCd123".to_owned(),
557                    "https://github.com/org/my_repo/commit/AbCd123".to_owned()
558                ),
559                (
560                    long_hash.to_owned(),
561                    format!("https://github.com/ferromark/fixtures/commit/{long_hash}")
562                ),
563            ]
564        );
565    }
566
567    #[test]
568    fn scans_past_multibyte_prose_before_ascii_references() {
569        assert_eq!(
570            references("Grüße: #123"),
571            vec![(
572                "#123".to_owned(),
573                "https://github.com/ferromark/fixtures/issues/123".to_owned()
574            )]
575        );
576    }
577}