add repoRef pii transformer (#3383)

adds a transformer func in path/elements.go to safely log a repoRef (or any other dir ref) without needing to conceal the entire string.

---

#### Does this PR need a docs update or release note?

- [x] ⛔ No

#### Type of change

- [x] 🧹 Tech Debt/Cleanup

#### Test Plan

- [x] ⚡ Unit test

src/internal/connector/graph/middleware.go

@@ -33,6 +33,7 @@ type LoggingMiddleware struct{}
 
 // well-known path names used by graph api calls
 // used to un-hide path elements in a pii.SafeURL
+// https://learn.microsoft.com/en-us/graph/api/resources/mailfolder?view=graph-rest-1.0
 var SafeURLPathParams = pii.MapWithPlurals(
 	//nolint:misspell
 	"alltime",
@@ -46,11 +47,16 @@ var SafeURLPathParams = pii.MapWithPlurals(
 	"childfolder",
 	"children",
 	"clone",
+	"clutter",
 	"column",
+	"conflict",
 	"contactfolder",
 	"contact",
 	"contenttype",
+	"conversationhistory",
+	"deleteditem",
 	"delta",
+	"draft",
 	"drive",
 	"event",
 	"group",
@@ -59,18 +65,28 @@ var SafeURLPathParams = pii.MapWithPlurals(
 	"invitation",
 	"item",
 	"joinedteam",
+	"junkemail",
 	"label",
 	"list",
+	"localfailure",
 	"mailfolder",
 	"member",
 	"message",
+	"msgfolderroot",
 	"notification",
+	"outbox",
 	"page",
 	"primarychannel",
+	"recoverableitemsdeletion",
 	"root",
+	"scheduled",
+	"searchfolder",
 	"security",
+	"sentitem",
+	"serverfailure",
 	"site",
 	"subscription",
+	"syncissue",
 	"team",
 	"unarchive",
 	"user",

src/pkg/path/elements.go

@@ -2,6 +2,7 @@ package path
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/alcionai/clues"
 
@@ -28,7 +29,26 @@ var piiSafePathElems = pii.MapWithPlurals(
 	LibrariesCategory.String(),
 	PagesCategory.String(),
 	DetailsCategory.String(),
-)
+
+	// well known folders
+	// https://learn.microsoft.com/en-us/graph/api/resources/mailfolder?view=graph-rest-1.0
+	"archive",
+	"clutter",
+	"conflict",
+	"conversationhistory",
+	"deleteditem",
+	"draft",
+	"inbox",
+	"junkemail",
+	"localfailure",
+	"msgfolderroot",
+	"outbox",
+	"recoverableitemsdeletion",
+	"scheduled",
+	"searchfolder",
+	"sentitem",
+	"serverfailure",
+	"syncissue")
 
 var (
 	// interface compliance required for handling PII
@@ -95,3 +115,24 @@ func (el Elements) Last() string {
 
 	return el[len(el)-1]
 }
+
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+
+// LoggableDir takes in a path reference (of any structure) and conceals any
+// non-standard elements (ids, filenames, foldernames, etc).
+func LoggableDir(ref string) string {
+	r := ref
+	n := strings.TrimSuffix(r, string(PathSeparator))
+
+	for n != r {
+		r = n
+		n = strings.TrimSuffix(r, string(PathSeparator))
+	}
+
+	elems := Split(r)
+	elems = pii.ConcealElements(elems, piiSafePathElems)
+
+	return join(elems)
+}

src/pkg/path/elements_test.go

@@ -98,3 +98,40 @@ func (suite *ElementsUnitSuite) TestElements_piiHandling() {
 		})
 	}
 }
+
+func (suite *ElementsUnitSuite) TestLoggableDir() {
+	table := []struct {
+		inpt   string
+		expect string
+	}{
+		{
+			inpt:   "archive/clutter",
+			expect: "archive/clutter",
+		},
+		{
+			inpt:   "foo/bar",
+			expect: "***/***",
+		},
+		{
+			inpt:   "inbox/foo",
+			expect: "inbox/***",
+		},
+		{
+			inpt:   "foo/",
+			expect: "***",
+		},
+		{
+			inpt:   "foo//",
+			expect: "***",
+		},
+		{
+			inpt:   "foo///",
+			expect: "***",
+		},
+	}
+	for _, test := range table {
+		suite.Run(test.inpt, func() {
+			assert.Equal(suite.T(), test.expect, LoggableDir(test.inpt))
+		})
+	}
+}