Initial ideas around a related-to special property.

pit.nimble

@@ -1,6 +1,6 @@
 # Package
 
-version       = "4.23.0"
+version       = "4.24.0"
 author        = "Jonathan Bernard"
 description   = "Personal issue tracker."
 license       = "MIT"
@@ -20,7 +20,7 @@ requires @[
 
 # Dependencies from git.jdb-software.com/nim-jdb/packages
 requires @[
-  "cliutils >= 0.6.4",
+  "cliutils >= 0.8.1",
   "langutils >= 0.4.0",
   "timeutils >= 0.5.4",
   "data_uri > 1.0.0",

src/pit.nim

@@ -51,7 +51,7 @@ proc getIssueContextDisplayName(ctx: CliContext, context: string): string =
     else: return context.capitalize()
   return ctx.contexts[context]
 
-proc formatIssue(ctx: CliContext, issue: Issue): string =
+proc formatIssue*(issue: Issue): string =
   result = ($issue.id).withColor(fgBlack, true) & "\n"&
            issue.summary.withColor(fgWhite) & "\n"
 
@@ -70,10 +70,9 @@ proc formatIssue(ctx: CliContext, issue: Issue): string =
 
   result &= termReset
 
-proc formatSectionIssue(
+proc formatSectionIssue*(
-    ctx: CliContext,
     issue: Issue,
-    width: int,
+    width: int = 80,
     indent = "",
     verbose = false): string =
 
@@ -135,12 +134,15 @@ proc formatSectionIssue(
 
   result &= termReset
 
-proc formatSectionIssueList(ctx: CliContext, issues: seq[Issue], width: int,
+proc formatSectionIssueList*(
-        indent: string, verbose: bool): string =
+    issues: seq[Issue],
+    width: int = 80,
+    indent: string = "",
+    verbose: bool = false): string =
 
   result = ""
   for i in issues:
-    var issueText = ctx.formatSectionIssue(i, width, indent, verbose)
+    var issueText = formatSectionIssue(i, width, indent, verbose)
     result &= issueText & "\n"
 
 proc formatSection(ctx: CliContext, issues: seq[Issue], state: IssueState,
@@ -161,10 +163,10 @@ proc formatSection(ctx: CliContext, issues: seq[Issue], state: IssueState,
         indent & ctx.getIssueContextDisplayName(context) & ":" &
         termReset & "\n\n"
 
-      result &= ctx.formatSectionIssueList(ctxIssues, innerWidth - 2, indent & "  ", verbose)
+      result &= formatSectionIssueList(ctxIssues, innerWidth - 2, indent & "  ", verbose)
       result &= "\n"
 
-  else: result &= ctx.formatSectionIssueList(issues, innerWidth, indent, verbose)
+  else: result &= formatSectionIssueList(issues, innerWidth, indent, verbose)
 
 proc loadIssues(ctx: CliContext, state: IssueState) =
   ctx.issues[state] = loadIssues(ctx.cfg.tasksDir, state)
@@ -224,7 +226,7 @@ proc edit(issue: Issue) =
     # Try to parse the newly-edited issue to make sure it was successful.
     let editedIssue = loadIssue(issue.filepath)
     editedIssue.store()
-  except:
+  except CatchableError:
     fatal "updated issue is invalid (ignoring edits): \n\t" &
       getCurrentExceptionMsg()
     issue.store()
@@ -379,7 +381,7 @@ when isMainModule:
 
     ctx.cfg.tasksDir.store(issue, state)
 
-    stdout.writeLine ctx.formatIssue(issue)
+    stdout.writeLine formatIssue(issue)
 
   elif args["reorder"]:
     ctx.reorder(parseEnum[IssueState]($args["<state>"]))
@@ -390,7 +392,7 @@ when isMainModule:
       var stateOption = none(IssueState)
 
       try: stateOption = some(parseEnum[IssueState](editRef))
-      except: discard
+      except CatchableError: discard
 
       if stateOption.isSome:
         let state = stateOption.get
@@ -442,9 +444,9 @@ when isMainModule:
         issue["completed"] = getTime().local.formatIso8601
         if issue.hasProp("recurrence") and issue.getRecurrence.isSome:
           let nextIssue = ctx.cfg.tasksDir.nextRecurrence(issue.getRecurrence.get, issue)
-          ctx.cfg.tasksDir.store(nextIssue, Todo)
+          ctx.cfg.tasksDir.store(nextIssue, TodoToday)
           info "created the next recurrence:"
-          stdout.writeLine ctx.formatIssue(nextIssue)
+          stdout.writeLine formatIssue(nextIssue)
 
 
       issue.changeState(ctx.cfg.tasksDir, targetState)
@@ -543,8 +545,12 @@ when isMainModule:
 
     if args["contexts"]: listContexts = true
     elif args["<stateOrId>"]:
-      try: statesOption = some(args["<stateOrId>"].mapIt(parseEnum[IssueState]($it)))
+      try:
-      except: issueIdsOption = some(args["<stateOrId>"].mapIt($it))
+        statesOption =
+          some(args["<stateOrId>"].
+          mapIt(parseEnum[IssueState]($it)))
+      except CatchableError:
+        issueIdsOption = some(args["<stateOrId>"].mapIt($it))
 
     # List the known contexts
     if listContexts:
@@ -567,7 +573,7 @@ when isMainModule:
     elif issueIdsOption.isSome:
       for issueId in issueIdsOption.get:
         let issue = ctx.cfg.tasksDir.loadIssueById(issueId)
-        stdout.writeLine ctx.formatIssue(issue)
+        stdout.writeLine formatIssue(issue)
 
     # List all issues
     else:
@@ -608,7 +614,23 @@ when isMainModule:
     try: write(propOut, decodeDataUri(issue[$(args["<propName>"])]))
     finally: close(propOut)
 
- except:
+  elif args["show-dupes"]:
+    ctx.loadAllIssues()
+
+    var idsToPaths = newTable[string, var seq[string]]()
+    for (state, issues) in pairs(ctx.issues):
+      for issue in issues:
+        let issueId = $issue.id
+
+        if idsToPaths.hasKey(issueId): idsToPaths[issueId].add(issue.filepath)
+        else: idsToPaths[issueId] = @[issue.filepath]
+
+    for (issueId, issuePaths) in pairs(idsToPaths):
+      if issuePaths.len < 2: continue
+      stdout.writeLine(issueId & ":\p  " & issuePaths.join("\p  ") & "\p\p")
+
+ except CatchableError:
   fatal getCurrentExceptionMsg()
+  debug getCurrentException().getStackTrace()
   #raise getCurrentException()
   quit(QuitFailure)

src/pitpkg/cliconstants.nim

@@ -1,4 +1,4 @@
-const PIT_VERSION* = "4.23.0"
+const PIT_VERSION* = "4.24.0"
 
 const USAGE* = """Usage:
   pit ( new | add) <summary> [<state>] [options]
@@ -14,6 +14,7 @@ const USAGE* = """Usage:
   pit ( delete | rm ) <id>... [options]
   pit add-binary-property <id> <propName> <propSource> [options]
   pit get-binary-property <id> <propName> <propDest> [options]
+  pit show-dupes
   pit help [options]
 
 Options:
@@ -100,7 +101,9 @@ Issue Properties:
     created
 
       If present, expected to be an ISO 8601-formatted date that represents the
-      time when the issue was created.
+      time when the issue was created. E.g.:
+
+          created: 2023-07-13T13:28:41-05:00
 
     completed
 
@@ -109,12 +112,16 @@ Issue Properties:
       property automatically when you use the "done" command, and can filter on
       this value.
 
+          completed: 2023-04-27T11:52:28-05:00
+
     context
 
       Allows issues to be organized into contexts. The -c option is short-hand
       for '-p context:<context-name>' and the 'list contexts' command will show
       all values of 'context' set in existing issues.
 
+          context: family
+
     delegated-to
 
       When an issue now belongs to someone else, but needs to be monitored for
@@ -122,17 +129,23 @@ Issue Properties:
       note how it has been delegated. When present PIT will prepend this value
       to the issue summary with an accent color.
 
+          delegated-to: Bob Ross
+
     hide-until
 
       When present, expected to be an ISO 8601-formatted date and used to
       supress the display of the issue until on or after the given date.
 
+          hide-until: 2024-01-01T13:45:00-05:00
+
     pending
 
       When an issue is blocked by a third party, this property can be used to
       capture details about the dependency When present PIT will display this
       value after the issue summary.
 
+          pending: Results of WCAG analysis.
+
     recurrence
 
       When an issue is moved to the "done" state, if the issue has a valid
@@ -143,7 +156,7 @@ Issue Properties:
       A valid recurrence value has a time value and optionally has an source
       issue ID. For example:
 
-        every 5 days, 10a544
+          recurrence: every 5 days, 10a544
 
       The first word, "every", is expected to be either "every" or "after".
 
@@ -161,15 +174,39 @@ Issue Properties:
 
       Examples:
 
-        every day
+          every day
-        every 2 days
+          every 2 days
-        after 2 days
+          after 2 days
-        every week
+          every week
-        after 12 hours
+          after 12 hours
-        every 2 weeks, 10a544
+          every 2 weeks, 10a544
+
+    relations
+
+      Used to store information about relationships between issues. PIT treats
+      all relations as bi-directional and will update related tickets as
+      necessary to maintain the integrity of the links.
+
+      Relations are captured as <relation-type> <related-issue-id>. Multiple
+      relations can be separated by ",". The <related-issue-id> must be a unique
+      issue ID or ID prefix (in the case of multiple matching issues, the first
+      found will be used with no guarantee on ordering). Valid value pairs for
+      <relation-type> are:
+
+        - child-of / parent-of
+        - related-to (default)
+        - blocks / blocked-by
+        - follows / precedes
+        - caused / caused-by
+
+      Examples:
+
+          relation: child-of fb3e63, blocked-by 2b71c1
+          relation: 2b71c1, 8f2b4c, follows 184dc6
+          relation: relates-to 2b71c1
 
     tags
 
       If present, expected to be a comma-delimited list of text tags. The -g
       option is a short-hand for '-p tags:<tags-value>'.
-"""
+"""

src/pitpkg/private/libpit.nim

@@ -11,6 +11,7 @@ type
     filepath*: string
     summary*, details*: string
     properties*: TableRef[string, string]
+    relations*: seq[Relation]
     tags*: seq[string]
     state*: IssueState
 
@@ -40,7 +41,21 @@ type
     interval*: TimeInterval
     isFromCompletion*: bool
 
+  Relation* = tuple[rel: RelationType, id: UUID]
+
+  RelationType* = enum
+    ParentOf = "parent-of",
+    ChildOf = "child-of",
+    RelatedTo = "related-to",
+    Blocks = "blocks",
+    BlockedBy = "blocked-by",
+    Follow = "follows",
+    FollowedBy = "followed-by",
+    Caused = "caused",
+    CausedBy = "caused-by"
+
 const DONE_FOLDER_FORMAT* = "yyyy-MM"
+const ISO8601_MS = "yyyy-MM-dd'T'HH:mm:ss'.'fffzzz"
 
 let ISSUE_FILE_PATTERN = re"[A-Fa-f0-9]{8}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{4}-[A-Fa-f0-9]{12}\.txt"
 let RECURRENCE_PATTERN = re"(every|after) ((\d+) )?((hour|day|week|month|year)s?)(, ([0-9a-fA-F]+))?"
@@ -167,11 +182,16 @@ proc parseDate*(d: string): DateTime =
   var errMsg = ""
   for df in DATE_FORMATS:
     try: return d.parse(df)
-    except:
+    except CatchableError:
       errMsg &= "\n\tTried " & df & " with " & d
       continue
   raise newException(ValueError, "Unable to parse input as a date: " & d & errMsg)
 
+proc parseRelation*(relStr: string): Relation =
+  let parts = relStr.split({' '})
+  if parts.len == 1: result = (RelatedTo, parseUUID(parts[0]))
+  else: result = (parseEnum[RelationType](parts[0]), parseUUID(parts[1]))
+
 ## Parse and format issues
 proc fromStorageFormat*(id: string, issueTxt: string): Issue =
   type ParseState = enum ReadingSummary, ReadingProps, ReadingDetails
@@ -179,6 +199,7 @@ proc fromStorageFormat*(id: string, issueTxt: string): Issue =
   result = Issue(
     id: parseUUID(id),
     properties: newTable[string,string](),
+    relations: @[],
     tags: @[])
 
   var parseState = ReadingSummary
@@ -202,14 +223,16 @@ proc fromStorageFormat*(id: string, issueTxt: string): Issue =
         parseState = ReadingDetails
         continue
 
-
       let parts = line.split({':'}, 1) --> map(it.strip())
       if parts.len != 2:
         raise newException(ValueError, "unable to parse property line: " & line)
 
-      # Take care of special properties: `tags`
+      # Take care of special properties: `tags` and `relations`
       if parts[0] == "tags":
         result.tags = parts[1].split({','}) --> map(it.strip())
+      elif parts[0] == "relations":
+        result.relations = parts[1].split({','}) -->
+          map(parseRelation(it.strip))
       else: result[parts[0]] = parts[1]
 
     of ReadingDetails:
@@ -219,12 +242,22 @@ proc fromStorageFormat*(id: string, issueTxt: string): Issue =
 
 proc toStorageFormat*(issue: Issue, withComments = false): string =
   var lines: seq[string] = @[]
+
   if withComments: lines.add("# Summary (one line):")
   lines.add(issue.summary)
+
   if withComments: lines.add("# Properties (\"key:value\" per line):")
+  issue.properties["last-updated"] = now().format(ISO8601_MS)
   for key, val in issue.properties:
     if not val.isEmptyOrWhitespace: lines.add(key & ": " & val)
+
   if issue.tags.len > 0: lines.add("tags: " & issue.tags.join(","))
+
+  if issue.relations.len > 0:
+    lines.add("relations: " &
+      (issue.relations --> map(it.rel & " " & it.id)).
+      join(', '))
+
   if not isEmptyOrWhitespace(issue.details) or withComments:
     if withComments: lines.add("# Details go below the \"--------\"")
     lines.add("--------")
@@ -326,6 +359,7 @@ proc changeState*(issue: Issue, tasksDir: string, newState: IssueState) =
   if newState == Done: issue.setDateTime("completed", getTime().local)
   tasksDir.store(issue, newState)
   if oldFilePath != issue.filepath: removeFile(oldFilepath)
+  issue.state = newState
 
 proc delete*(issue: Issue) = removeFile(issue.filepath)
 
@@ -406,14 +440,12 @@ proc find*(
 
 ### Configuration utilities
 proc loadConfig*(args: Table[string, Value] = initTable[string, Value]()): PitConfig =
-  let pitrcLocations = @[
+  var pitrcFilename: string
-    if args["--config"]: $args["--config"] else: "",
-    ".pitrc", $getEnv("PITRC"), $getEnv("HOME") & "/.pitrc"]
 
-  var pitrcFilename: string =
+  try:
-    pitrcLocations --> fold("", if fileExists(it): it else: a)
+    pitrcFilename = findConfigFile(".pitrc",
-
+      if args["--config"]: @[$args["--config"]] else: @[])
-  if not fileExists(pitrcFilename):
+  except ValueError:
     warn "could not find .pitrc file: " & pitrcFilename
     if isEmptyOrWhitespace(pitrcFilename):
       pitrcFilename = $getEnv("HOME") & "/.pitrc"
@@ -421,25 +453,19 @@ proc loadConfig*(args: Table[string, Value] = initTable[string, Value]()): PitCo
     try:
       cfgFile = open(pitrcFilename, fmWrite)
       cfgFile.write("{\"tasksDir\": \"/path/to/tasks\"}")
-    except: warn "could not write default .pitrc to " & pitrcFilename
+    except CatchableError: warn "could not write default .pitrc to " & pitrcFilename
     finally: close(cfgFile)
 
-  var cfgJson: JsonNode
+  debug "loading config from '$#'" % [pitrcFilename]
-  try: cfgJson = parseFile(pitrcFilename)
+  let cfg = initCombinedConfig(pitrcFilename, args)
-  except: raise newException(IOError,
-    "unable to read config file: " & pitrcFilename &
-    "\x0D\x0A" & getCurrentExceptionMsg())
-
-  let cfg = CombinedConfig(docopt: args, json: cfgJson)
 
   result = PitConfig(
     cfg: cfg,
     contexts: newTable[string,string](),
     tasksDir: cfg.getVal("tasks-dir", ""))
 
-  if cfgJson.hasKey("contexts"):
+  for k, v in cfg.getJson("contexts", newJObject()):
-    for k, v in cfgJson["contexts"]:
+    result.contexts[k] = v.getStr()
-      result.contexts[k] = v.getStr()
 
   if isEmptyOrWhitespace(result.tasksDir):
     raise newException(Exception, "no tasks directory configured")