✨ Add references support!

Closes #13

README.md

···
 
 Indentation is done with tab characters only.
 
-- **Title:** The title is made up of any word in the line that does not start with `~`, `@` or `%`. Words that start with any of these symbols will not be added to the title, except if they are in the middle (in that case, they both get added as tags/assignees/milestones and as a word in the title, without the prefix symbol)
+- **Title:** The title is made up of any word in the line that does not start with `~`, `@`, `%` or `#.`. Words that start with any of these symbols will not be added to the title, except if they are in the middle (in that case, they both get added as tags/assignees/milestones and as a word in the title, without the prefix symbol)
 - **Tags:** Prefix a word with `~` to add a label to the issue
 - **Assignees:** Prefix with `@` to add an assignee. The special assignee `@me` is supported.
 - **Milestone:** Prefix with `%` to set the milestone
+- **References:** Prefix with `#.NUMBER` to define a reference for this issue. See [Cross-reference other issues](#cross-reference-other-issues) for more information.
 - **Comments:** You can add comments by prefixing a line with `//`
 - **Description:** To add a description, finish the line with `:`, and put the description on another line (or multiple), just below, indented once more than the issue's line. Exemple:
 
···
 
 Another issue.
 ```
+
+#### Cross-reference other issues
+
+As you might know, you can link an issue to another by using `#NUMBER`, with `NUMBER` the number of the issue you want to reference. You could want to write that, to reference `First issue` in `Second issue`:
+
+```
+First issue
+
+Second issue:
+  Needs #11  
+```
+
+However, this assumes that the current latest issue, before running issurge on this file, is `#9`. It also assumes that issues get created in order (which is the case for now), and that no other issue will get created while running issurge.
+
+As managing all of this by hand can be annoying, you can create references in the issurge file:
+
+```
+#.1 First issue
+
+Second issue:
+  Needs #.1
+```
+
+And that `#.1` in `Needs #.1` will be replaced by the actual issue number of `First issue` when the issue gets created.
+
+> [!WARNING]
+> For now, issues are created in order, so you need to define a reference _before_ you can use it.
 
 ### One-shot mode
 

issurge/main.py

···
 #!/usr/bin/env python
 """
 Usage:
-    issurge [options] new <words>... 
+    issurge [options] new <words>...
     issurge [options] <file> [--] [<submitter-args>...]
     issurge --help
 
···
     --dry-run   Don't actually post the issues
     --debug     Print debug information
 """
+
 import os
 from pathlib import Path
 
···
     if opts["new"]:
         issue = interactive.create_issue(" ".join(opts["<words>"]))
         debug(f"Submitting {issue.display()}")
-        issue.submit(opts["<submitter-args>"])
+        number = issue.submit(opts["<submitter-args>"])
+        print(f"Created issue #{number}")
     else:
         print("Submitting issues...")
+        references_resolutions: dict[int, int] = {}
         for issue in parse(Path(opts["<file>"]).read_text()):
-            issue.submit(opts["<submitter-args>"])
+            issue = issue.resolve_references(references_resolutions, strict=True)
+            number = issue.submit(opts["<submitter-args>"])
+            print(f"Created issue #{number}")
+            if issue.reference and number:
+                references_resolutions[issue.reference] = number

issurge/main_test.py

···
 
 from issurge.utils import debugging, dry_running
 
+class MockedSubprocessOutput:
+    def __init__(self, stdout: str, stderr: str):
+        self.stdout = stdout.encode('utf-8')
+        self.stderr = stderr.encode('utf-8')
 
 @fixture
 def setup():
···
 \tAn issue to submit
 Another ~issue to submit @me"""
     )
-    subprocess.run = Mock()
+    subprocess.run = Mock(
+        return_value=MockedSubprocessOutput("https://github.com/gwennlbh/gh-api-playground/issues/5\n", "Some unrelated stuff haha")
+    )
     Issue._get_remote_url = Mock(
         return_value=urlparse("https://github.com/ewen-lbh/gh-api-playground")
     )
···
             "common",
             "-l",
             "common",
+            "-m",
+            "common",
         ],
         [
             "gh",
···
             "-a",
             "common",
             "-l",
+            "common",
+            "-m",
             "common",
         ],
         [

issurge/parser.py

···
 import os
+import re
 import subprocess
 from typing import Any, Iterable, NamedTuple
 from urllib.parse import urlparse
···
     labels: set[str] = set()
     assignees: set[str] = set()
     milestone: str = ""
+    reference: int|None = None
 
     def __rich_repr__(self):
         yield self.title
···
         yield "labels", self.labels, set()
         yield "assignees", self.assignees, set()
         yield "milestone", self.milestone, ""
+        yield "ref", self.reference, None
+        yield "references", self.references, set()
 
     def __str__(self) -> str:
-        result = f"{self.title}" or "<No title>"
+        result = ""
+        if self.reference:
+            result += f"<#{self.reference}> "
+        result += f"{self.title}" or "<No title>"
         if self.labels:
             result += f" {' '.join(['~' + l for l in self.labels])}"
         if self.milestone:
···
         return result
 
     def display(self) -> str:
-        result = f"[white]{self.title[:30]}[/white]" or "[red]<No title>[/red]"
+        result = ""
+        if self.reference:
+            result += f"[bold blue]<#{self.reference}>[/bold blue] "
+        result += f"[white]{self.title[:30]}[/white]" or "[red]<No title>[/red]"
         if len(self.title) > 30:
             result += " [white dim](...)[/white dim]"
         if self.labels:
···
             result += " [white][...][/white]"
         return result
 
+    @property
+    def references(self) -> set[int]:
+        # find all \b#\.(\d+)\b in description
+        references = set()
+        for word in self.description.strip().split(" "):
+            if word.startswith("#.") and word[2:].strip().isdigit():
+                references.add(int(word[2:].strip()))
+
+        return references
+
+    def resolve_references(self, resolution_map: dict[int, int], strict=False) -> 'Issue':
+        resolved_description = self.description
+        for reference in self.references:
+            if (resolved := resolution_map.get(reference)):
+                resolved_description = resolved_description.replace(f"#.{reference}", f"#{resolved}")
+            elif strict:
+                raise Exception(f"Could not resolve reference #.{reference}")
+
+        return Issue(**(self._asdict() | {"description": resolved_description}))
+            
+
     def submit(self, submitter_args: list[str]):
         remote_url = self._get_remote_url()
         if remote_url.hostname == "github.com":
-            self._github_submit(submitter_args)
+            return self._github_submit(submitter_args)
         else:
-            self._gitlab_submit(submitter_args)
+            return self._gitlab_submit(submitter_args)
 
     def _get_remote_url(self):
         try:
···
                 "Could not determine remote url, make sure that you are inside of a git repository that has a remote named 'origin'"
             ) from e
 
-    def _gitlab_submit(self, submitter_args: list[str]):
+    def _gitlab_submit(self, submitter_args: list[str]) -> int|None:
         command = ["glab", "issue", "new"]
         if self.title:
             command += ["-t", self.title]
···
         if self.milestone:
             command += ["-m", self.milestone]
         command.extend(submitter_args)
-        self._run(command)
+        out = self._run(command)
+        # parse issue number from command output url: https://.+/-/issues/(\d+)
+        if out and (url := re.search(r"https://.+/-/issues/(\d+)", out)):
+            return int(url.group(1))
+        
+        # raise Exception(f"Could not parse issue number from {out!r}")
 
-    def _github_submit(self, submitter_args: list[str]):
+    def _github_submit(self, submitter_args: list[str]) -> int|None:
         command = ["gh", "issue", "new"]
         if self.title:
             command += ["-t", self.title]
···
         if self.milestone:
             command += ["-m", self.milestone]
         command.extend(submitter_args)
-        self._run(command)
+        out = self._run(command)
+        # parse issue number from command output url: https://github.com/.+/issues/(\d+)
+        pattern = re.compile(r"https:\/\/github\.com\/.+\/issues\/(\d+)")
+        if out and (url := pattern.search(out)):
+            return int(url.group(1))
+
+        # raise Exception(f"Could not parse issue number from {out!r}, looked for regex {pattern}")
+        return None
 
     def _run(self, command):
         if dry_running() or debugging():
···
             )
         if not dry_running():
             try:
-                subprocess.run(command, check=True, capture_output=True)
+                out = subprocess.run(command, check=True, capture_output=True)
+                return out.stderr.decode() + "\n" + out.stdout.decode()
             except subprocess.CalledProcessError as e:
                 print(
                     f"Calling [white bold]{e.cmd}[/] failed with code [white bold]{e.returncode}[/]:\n{NEWLINE.join(TAB + line for line in e.stderr.decode().splitlines())}"
···
 
     @staticmethod
     def _word_and_sigil(raw_word: str) -> tuple[str, str]:
+        if raw_word.startswith("#.") and raw_word[2:].isdigit():
+            return "#.", raw_word[2:]
+
         sigil = raw_word[0]
         word = raw_word[1:]
         if sigil not in ("~", "%", "@"):
···
         labels = set()
         assignees = set()
         milestone = ""
+        reference = None
         # only labels/milestones/assignees at the beginning or end of the line are not added to the title as words
         add_to_title = False
         remaining_words = [word.strip() for word in raw.split(" ") if word.strip()]
+        _debug_sigils = []
 
         while remaining_words:
             sigil, word = cls._word_and_sigil(remaining_words.pop(0))
+
+            _debug_sigils.append(sigil)
 
             if sigil and add_to_title:
                 title += f" {word}"
···
                     milestone = word
                 case "@":
                     assignees.add(word)
+                case "#.":
+                    reference = int(word)
                 case _:
                     title += f" {word}"
                     # add to title if there are remaining regular words
···
                 labels=labels,
                 assignees=assignees,
                 milestone=milestone,
+                reference=reference 
             ),
             expects_description,
         )
···
         labels=current_labels,
         assignees=current_assignees,
         milestone=current_milestone,
+        reference=parsed.reference
     )
 
     if current_issue.title:

issurge/parser_test.py

···
         Issue(title="A label with a description following it", labels={"now"}),
         True,
     ),
+    (
+        "#.1 An issue with a reference definition",
+        Issue(title="An issue with a reference definition", reference=1),
+        False,
+    ),
 ]:
 
     @test(f"parse {fragment!r}")
···
             ),
         ],
     ),
+    (
+        """
+An issue that references another ~blocked:
+\tSee #.1
+
+#.1 The other one ^w^
+""",
+        [
+            Issue(
+                title="An issue that references another",
+                labels={"blocked"},
+                description="See #.1\n",
+            ),
+            Issue(
+                title="The other one ^w^",
+                reference=1,
+            ),
+        ],
+    ),
 ]:
 
     @test(f"parse issues from {textwrap.dedent(lines)!r}")
     def _(lines=lines, expected=expected):
         assert list(parse(lines)) == expected
 
+
+@test("resolves references")
+def _():
+    [issue, *_] = list(parse("An issue that references another ~blocked:\n\tSee #.2"))
+    assert issue.references == {2}
+    issue = issue.resolve_references({2: 1})
+    assert issue.description == "See #1\n"
+
+@test("splits #. sigil")
+def _():
+    assert Issue._word_and_sigil("#.1") == ("#.", "1")
 
 @test("parse issue with missing description fails")
 def _():