feat: allow more customisation to how encodings are included in source issues

[galargh]

It'd be cool if we could customise how encodings are presented in source issues.

E.g. for testground, I think the issue (testground/testground#1491) would look better if we could put children: and description: encodings in headers as Description and Children respectively. As in:

# Description
<!-- DESCRIPTION GOES HERE -->

# Children
<!-- CHILDREN GO HERE -->

---
<!-- THE REST OF THE CONTENT -->

Even better if we had full control over the encodings' text. Maybe we could achieve that by allowing the encodings to be hidden inside comments? As in:

# Description
<!-- description: -->
<!-- DESCRIPTION GOES HERE -->

# Related Issues
<!-- children: -->
<!-- CHILDREN GO HERE -->

# Other Things
<!-- ... -->

[SgtPooki]

I love the idea of the encodings being more readable, and giving users a chance to customize those. Leaving this decision for @wilkyr31d

[SgtPooki]

@galargh with your approach, do you think it would work fine like this:

1. Check for label ("description:", "children:", etc..)
2. search on next lines for github links (short-id, long-id, full URL, etc), stopping when there is no match
3. repeat for all markdown sections

@whizzzkid @juliaxbow what do you two think of this feature request?

[galargh]

I'm not sure I quite understand this algorithm. Could you add an example maybe?

[SgtPooki]

@galargh I have since added support for github tasklists, so that provides another solution for defining children, but the description parsing still needs some love.

The code for parsing children is at

1. Starmap/lib/parser.ts

   Lines 63 to 75 in e26da1f

   	function getChildrenFromTaskList(issue: Pick<GithubIssueData, 'body' | 'html_url'>): ParserGetChildrenResponse[] {
   	// tasklists require the checkbox style format to recognize children
   	const lines = getSectionLines(issue.body, '```[tasklist]')
   	.filter(ensureTaskListChild)
   	.map(splitAndGetLastItem)
   	.filter(Boolean);
   	if (lines.length === 0) {
   	throw new Error('Section missing or has no children')
   	}
   	return convertLinesToChildren(lines, issue, 'tasklist')
   	}

2. Starmap/lib/parser.ts

   Lines 32 to 40 in e26da1f

   	function getSectionLines(text: string, sectionHeader: string) {
   	const sectionIndex = text.indexOf(sectionHeader);
   	if (sectionIndex === -1) {
   	return [];
   	}
   	return text.substring(sectionIndex)
   	.split(/[\r\n]+/).slice(1)
   	.map(getUrlFromMarkdownText)
   	}

---

Apparently, description parsing wasn't done already, so i'm adding it as a part of #120, and my algorithm is going to be something like this for description:

1. Search for "description:" in the text. if not found, skip, there is no description
2. If found, split on the line where "description:" was found on a space (" ") and select the second half (index=1) as the very first line (it may be empty)
3. Remove any "-->" text from the first line (handle the edge-case mentioned below)
4. While no blank line is found, add found lines to a line array.
5. When a blank line is found, it's the end of the description

steps 1-2 are basically covered at

Starmap/lib/parser.ts

Lines 32 to 40 in e26da1f

	function getSectionLines(text: string, sectionHeader: string) {
	const sectionIndex = text.indexOf(sectionHeader);
	if (sectionIndex === -1) {
	return [];
	}
	return text.substring(sectionIndex)
	.split(/[\r\n]+/).slice(1)
	.map(getUrlFromMarkdownText)
	}

.

Using the basic algorithm above, you could format a description like so and it should work (I'll add a test for this):

<!-- description: 
My milestone description
thing1
thing2

-->

Ideally, descriptions should be renderable. We don't want users to have to maintain two lists of descriptions, so the following should also work.

edge-case

<!-- description: -->
My milestone description
thing1
thing2

Some other thing that's not considered part of the description

---

Some questions based on the above:

1. Do you want to leave in support for "children:" similar to the above description approach (beyond tasklists)
2. Is the above approach satisfactory for descriptions?
3. I don't imagine we will support newlines in starmap, so starmap description snippets end as soon as a newline is encountered. Do you see any issues with this?