fix(report): surface email CODEOWNERS owners

watson · watson · commit 0e2e5962b419 · 2026-03-11T12:37:49.000+01:00
Align the ownership explorer with CODEOWNERS coverage by including email owners in the
report index and HTML UI. Rename the report schema to generic owner terminology and add
CLI regression coverage for email-owner parity.

Made-with: Cursor
diff --git a/README.md b/README.md
@@ -26,7 +26,7 @@ See how ownership coverage looks in practice with [this interactive report](http
 - Coverage summary: total files, owned, unowned, and percentage
 - Directory explorer with filtering, sorting, and drill-down
 - Full unowned file list with scope and text filtering
-- Ownership explorer with quick chips and file filtering for `@org/team` and `@username` owners
+- Ownership explorer with quick chips and file filtering for resolved CODEOWNERS owners, including `@org/team`, `@username`, and email owners
 - Matches GitHub `CODEOWNERS` discovery precedence: `.github/`, repository root, then `docs/`
 - Detects CODEOWNERS patterns that match no repository paths
 - Detects directories with fragile coverage — 100% covered through individual file rules, but new files would lack owners
@@ -204,6 +204,7 @@ The report follows practical `CODEOWNERS` resolution behavior:
 
 - A file is considered **owned** if at least one owner is resolved.
 - When `--validate-github-owners` is enabled, `@username` and `@org/team` owners only count if GitHub confirms they exist and have write access to the repository.
+- The ownership explorer surfaces the resolved owners for each matched file, including email owners.
 - Within a single `CODEOWNERS` file, the **last matching rule wins**.
 - A pattern line with no owners acts as an ownerless override only when it is the last matching rule for a path, matching GitHub's documented behavior.
 - GitHub only considers `CODEOWNERS` at `.github/CODEOWNERS`, `CODEOWNERS`, and `docs/CODEOWNERS`, using the first file found in that order.
@@ -228,7 +229,7 @@ The generated page includes:
 - repository-level ownership metrics and coverage bar
 - scoped directory table with coverage bars
 - searchable list of unowned files
-- ownership explorer for filtering files by `@org/team` or `@username`
+- ownership explorer for filtering files by resolved CODEOWNERS owner, including `@org/team`, `@username`, and email owners
 - active `CODEOWNERS` file and rule count
 - warnings for extra or unsupported `CODEOWNERS` files that GitHub will ignore
 - warnings for CODEOWNERS patterns that match no repository paths
diff --git a/lib/report-builder.js b/lib/report-builder.js
@@ -25,8 +25,8 @@ export function buildReport (repoRoot, files, codeownersDescriptor, options, pro
   const directoryStats = new Map()
   /** @type {string[]} */
   const unownedFiles = []
-  /** @type {Map<string, { team: string, files: string[] }>} */
-  const teamOwnership = new Map()
+  /** @type {Map<string, { owner: string, files: string[] }>} */
+  const ownerIndex = new Map()
 
   let owned = 0
   let unowned = 0
@@ -40,11 +40,11 @@ export function buildReport (repoRoot, files, codeownersDescriptor, options, pro
     if (isOwned) {
       owned++
       for (const owner of fileOwners) {
-        const ownerEntry = teamOwnership.get(owner.toLowerCase())
+        const ownerEntry = ownerIndex.get(owner.toLowerCase())
         if (ownerEntry) {
           ownerEntry.files.push(filePath)
         } else {
-          teamOwnership.set(owner.toLowerCase(), { team: owner, files: [filePath] })
+          ownerIndex.set(owner.toLowerCase(), { owner, files: [filePath] })
         }
       }
     } else {
@@ -82,18 +82,18 @@ export function buildReport (repoRoot, files, codeownersDescriptor, options, pro
 
   const directories = mapToRows(directoryStats).sort(compareRows)
   unownedFiles.sort((first, second) => first.localeCompare(second))
-  const teamOwnershipRows = Array.from(teamOwnership.values())
+  const ownerIndexRows = Array.from(ownerIndex.values())
     .map((entry) => {
       entry.files.sort((first, second) => first.localeCompare(second))
       return {
-        team: entry.team,
+        owner: entry.owner,
         total: entry.files.length,
         files: entry.files,
       }
     })
     .sort((first, second) => {
       if (first.total !== second.total) return second.total - first.total
-      return first.team.localeCompare(second.team)
+      return first.owner.localeCompare(second.owner)
     })
 
   return {
@@ -110,7 +110,7 @@ export function buildReport (repoRoot, files, codeownersDescriptor, options, pro
     }],
     directories,
     unownedFiles,
-    teamOwnership: teamOwnershipRows,
+    ownerIndex: ownerIndexRows,
     codeownersValidationMeta: {
       discoveryWarnings: [],
       discoveryWarningCount: 0,
@@ -141,7 +141,8 @@ export function buildReport (repoRoot, files, codeownersDescriptor, options, pro
 }
 
 /**
- * Collect unique CODEOWNERS owner entries (both @org/team teams and @username individuals).
+ * Collect unique CODEOWNERS owner entries for the report explorer/index.
+ * This includes GitHub owners (`@org/team`, `@username`) and email owners.
  * @param {string[]|undefined} owners
  * @returns {string[]}
  */
@@ -151,22 +152,23 @@ function collectOwners (owners) {
   /** @type {Map<string, string>} */
   const unique = new Map()
   for (const owner of owners) {
-    if (!looksLikeOwner(owner)) continue
+    if (!looksLikeIndexedOwner(owner)) continue
     const normalized = owner.trim()
     unique.set(normalized.toLowerCase(), normalized)
   }
   return Array.from(unique.values())
 }
 
 /**
- * Determine whether a CODEOWNERS owner token is a recognized `@`-prefixed owner
- * (either an `@org/team` or an `@username`).
+ * Determine whether a CODEOWNERS owner token should be surfaced in the report
+ * explorer/index.
  * @param {unknown} owner
  * @returns {boolean}
  */
-function looksLikeOwner (owner) {
+function looksLikeIndexedOwner (owner) {
   if (typeof owner !== 'string') return false
-  return /^@[^\s]+$/.test(owner.trim())
+  const normalized = owner.trim()
+  return /^@[^\s]+$/.test(normalized) || /^[^\s@]+@[^\s@]+$/.test(normalized)
 }
 
 /**
diff --git a/lib/report.template.html b/lib/report.template.html
@@ -188,19 +188,19 @@
     }
     .controls label { color: var(--muted); display: flex; gap: 8px; align-items: center; font-size: 14px; }
     .suggestion-muted { color: var(--muted); }
-    .team-controls {
+    .owner-controls {
       display: grid;
       grid-template-columns: minmax(260px, 420px) minmax(280px, 1fr);
       gap: 12px;
       align-items: center;
     }
-    .team-chip-list {
+    .owner-chip-list {
       display: flex;
       flex-wrap: wrap;
       gap: 8px;
       margin-bottom: 10px;
     }
-    .team-chip {
+    .owner-chip {
       border: 1px solid rgba(139, 92, 246, 0.55);
       background: rgba(139, 92, 246, 0.18);
       color: #ddd6fe;
@@ -209,15 +209,15 @@
       font-size: 12px;
       cursor: pointer;
     }
-    .team-chip:hover {
+    .owner-chip:hover {
       background: rgba(139, 92, 246, 0.3);
     }
-    .team-chip.is-active {
+    .owner-chip.is-active {
       border-color: #c4b5fd;
       background: rgba(196, 181, 253, 0.34);
       color: #f5f3ff;
     }
-    .team-empty {
+    .owner-empty {
       border: 1px dashed var(--border);
       border-radius: 10px;
       padding: 12px;
@@ -354,7 +354,7 @@
       margin-top: 10px;
       margin-bottom: 6px;
     }
-    #team-file-count {
+    #owner-file-count {
       margin-top: 10px;
       margin-bottom: 6px;
     }
@@ -403,7 +403,7 @@
       .hero-title { align-items: flex-start; }
       .controls input[type="text"] { min-width: 100%; }
       .controls select { min-width: 100%; }
-      .team-controls {
+      .owner-controls {
         grid-template-columns: 1fr;
       }
     }
@@ -485,14 +485,14 @@ <h2>Unowned Files</h2>
         <h2>Ownership Explorer</h2>
         <p class="muted">Select an owner to view the files they own</p>
       </div>
-      <div class="team-empty muted" id="team-empty-state"></div>
-      <div class="controls field-controls team-controls">
-        <select id="team-select" aria-label="Select owner"></select>
-        <input id="team-file-filter" type="text" placeholder="Filter selected owner's files..." />
+      <div class="owner-empty muted" id="owner-empty-state"></div>
+      <div class="controls field-controls owner-controls">
+        <select id="owner-select" aria-label="Select owner"></select>
+        <input id="owner-file-filter" type="text" placeholder="Filter selected owner's files..." />
       </div>
-      <div class="team-chip-list" id="team-chip-list"></div>
-      <div class="file-list" id="team-file-list"></div>
-      <p class="muted" id="team-file-count"></p>
+      <div class="owner-chip-list" id="owner-chip-list"></div>
+      <div class="file-list" id="owner-file-list"></div>
+      <p class="muted" id="owner-file-count"></p>
     </section>
 
     <section class="panel">
@@ -559,7 +559,7 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
       const clamp = value => Math.max(0, Math.min(100, value))
       const scopeQueryParam = 'scope'
       const directoryRows = report.directories.filter(row => row.path !== '(root)')
-      const teamOwnershipRows = Array.isArray(report.teamOwnership) ? report.teamOwnership : []
+      const ownerIndexRows = Array.isArray(report.ownerIndex) ? report.ownerIndex : []
       const suggestionRows = Array.isArray(report.directoryTeamSuggestions) ? report.directoryTeamSuggestions : []
       const suggestionMeta = report.directoryTeamSuggestionsMeta || { enabled: false, warnings: [] }
       const codeownersValidationMeta = report.codeownersValidationMeta || {
@@ -595,7 +595,7 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
       let selectedPath = readScopeFromLocation()
       let directoryController
       let unownedController
-      let teamController
+      let ownerController
 
       function setScope (nextPath, options) {
         const historyMode = options && options.historyMode ? options.historyMode : 'push'
@@ -605,7 +605,7 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
 
         if (directoryController) directoryController.render()
         if (unownedController) unownedController.render()
-        if (teamController) teamController.render()
+        if (ownerController) ownerController.render()
 
         if (historyMode !== 'none') {
           if (historyMode === 'replace') {
@@ -643,7 +643,7 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
         getDirectScopeStats
       )
       unownedController = setupUnownedFiles(report.unownedFiles, () => selectedPath)
-      teamController = setupTeamOwnershipExplorer(teamOwnershipRows, () => selectedPath)
+      ownerController = setupOwnerIndexExplorer(ownerIndexRows, () => selectedPath)
       syncScopeToLocation(selectedPath, true)
 
       globalThis.addEventListener('popstate', () => {
@@ -1342,26 +1342,26 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
         return { render }
       }
 
-      function setupTeamOwnershipExplorer (rows, getScope) {
-        const teamSelect = document.getElementById('team-select')
-        const fileFilter = document.getElementById('team-file-filter')
-        const chipList = document.getElementById('team-chip-list')
-        const list = document.getElementById('team-file-list')
-        const count = document.getElementById('team-file-count')
-        const emptyState = document.getElementById('team-empty-state')
+      function setupOwnerIndexExplorer (rows, getScope) {
+        const ownerSelect = document.getElementById('owner-select')
+        const fileFilter = document.getElementById('owner-file-filter')
+        const chipList = document.getElementById('owner-chip-list')
+        const list = document.getElementById('owner-file-list')
+        const count = document.getElementById('owner-file-count')
+        const emptyState = document.getElementById('owner-empty-state')
         const safeRows = rows
-          .filter(row => row && typeof row.team === 'string' && Array.isArray(row.files))
+          .filter(row => row && typeof row.owner === 'string' && Array.isArray(row.files))
           .map((row) => ({
-            team: row.team,
+            owner: row.owner,
             total: Number(row.total) || row.files.length,
             files: row.files,
           }))
-        const rowByTeam = new Map(safeRows.map(row => [row.team, row]))
-        let selectedTeam = safeRows.length > 0 ? safeRows[0].team : ''
+        const rowByOwner = new Map(safeRows.map(row => [row.owner, row]))
+        let selectedOwner = safeRows.length > 0 ? safeRows[0].owner : ''
 
         if (safeRows.length === 0) {
-          emptyState.textContent = 'No @-prefixed owners found in resolved CODEOWNERS matches. Ownership entries appear when rules use @org/team or @username.'
-          teamSelect.disabled = true
+          emptyState.textContent = 'No resolved owners found in CODEOWNERS matches. Ownership entries appear when rules use @org/team, @username, or email owners.'
+          ownerSelect.disabled = true
           fileFilter.disabled = true
           chipList.innerHTML = ''
           list.textContent = '(none)'
@@ -1372,28 +1372,28 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
         emptyState.hidden = true
         for (const row of safeRows) {
           const option = document.createElement('option')
-          option.value = row.team
-          option.textContent = row.team + ' \u2014 ' + fmt.format(row.total) + ' files'
-          teamSelect.appendChild(option)
+          option.value = row.owner
+          option.textContent = row.owner + ' \u2014 ' + fmt.format(row.total) + ' files'
+          ownerSelect.appendChild(option)
         }
 
-        const quickTeams = safeRows.slice(0, 12)
-        for (const row of quickTeams) {
+        const quickOwners = safeRows.slice(0, 12)
+        for (const row of quickOwners) {
           const chip = document.createElement('button')
           chip.type = 'button'
-          chip.className = 'team-chip'
-          chip.textContent = row.team + ' (' + fmt.format(row.total) + ')'
-          chip.setAttribute('data-team', row.team)
+          chip.className = 'owner-chip'
+          chip.textContent = row.owner + ' (' + fmt.format(row.total) + ')'
+          chip.setAttribute('data-owner', row.owner)
           chip.addEventListener('click', () => {
-            selectedTeam = row.team
-            teamSelect.value = selectedTeam
+            selectedOwner = row.owner
+            ownerSelect.value = selectedOwner
             render()
           })
           chipList.appendChild(chip)
         }
 
-        teamSelect.addEventListener('change', () => {
-          selectedTeam = teamSelect.value
+        ownerSelect.addEventListener('change', () => {
+          selectedOwner = ownerSelect.value
           render()
         })
         fileFilter.addEventListener('input', render)
@@ -1402,17 +1402,17 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
         function render () {
           const scope = getScope()
           const query = fileFilter.value.trim().toLowerCase()
-          const selectedRow = rowByTeam.get(selectedTeam) || safeRows[0]
+          const selectedRow = rowByOwner.get(selectedOwner) || safeRows[0]
           if (!selectedRow) {
             list.textContent = '(none)'
             count.textContent = 'Showing 0 files.'
             return
           }
 
-          if (teamSelect.value !== selectedRow.team) {
-            teamSelect.value = selectedRow.team
+          if (ownerSelect.value !== selectedRow.owner) {
+            ownerSelect.value = selectedRow.owner
           }
-          selectedTeam = selectedRow.team
+          selectedOwner = selectedRow.owner
           const scopedFiles = scope
             ? selectedRow.files.filter(file => file === scope || file.startsWith(scope + '/'))
             : selectedRow.files
@@ -1422,12 +1422,12 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
           const shown = filteredFiles.slice(0, 6000)
 
           list.textContent = shown.join('\n') || '(none)'
-          count.textContent = 'Owner: ' + selectedRow.team + ' — scope: ' + (scope || '(root)') +
+          count.textContent = 'Owner: ' + selectedRow.owner + ' — scope: ' + (scope || '(root)') +
             ' — showing ' + fmt.format(shown.length) + ' of ' + fmt.format(filteredFiles.length) + ' files.'
 
-          const chips = chipList.querySelectorAll('.team-chip')
+          const chips = chipList.querySelectorAll('.owner-chip')
           for (const chip of chips) {
-            const isActive = chip.getAttribute('data-team') === selectedRow.team
+            const isActive = chip.getAttribute('data-owner') === selectedRow.owner
             chip.classList.toggle('is-active', isActive)
           }
         }
diff --git a/lib/types.js b/lib/types.js
@@ -150,12 +150,12 @@
  */
 
 /**
- * Ownership summary for a single team.
+ * Ownership summary for a single resolved CODEOWNERS owner.
  * @typedef {{
- *   team: string,
+ *   owner: string,
  *   total: number,
  *   files: string[]
- * }} TeamOwnershipRow
+ * }} OwnerIndexRow
  */
 
 /**
@@ -206,7 +206,7 @@
  *   codeownersFiles: { path: string, rules: number }[],
  *   directories: DirectoryRow[],
  *   unownedFiles: string[],
- *   teamOwnership: TeamOwnershipRow[],
+ *   ownerIndex: OwnerIndexRow[],
  *   codeownersValidationMeta: CodeownersValidationMeta,
  *   directoryTeamSuggestions: TeamSuggestionRow[],
  *   directoryTeamSuggestionsMeta: TeamSuggestionsMeta
diff --git a/test/cli.test.js b/test/cli.test.js
