1use 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#[derive(Debug, Clone, PartialEq, Eq)]
20pub struct InvalidGitHubRepository {
21 value: String,
22}
23
24impl InvalidGitHubRepository {
25 #[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
44pub struct GitHubReferencesPass {
53 owner: String,
54 repository: String,
55}
56
57impl GitHubReferencesPass {
58 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}