feat(cli): handle oversized CODEOWNERS files

watson · watson · commit 4fc6f5cd3be9 · 2026-03-11T12:28:52.000+01:00
GitHub ignores active CODEOWNERS files larger than 3 MB, which can make audits
report ownership that GitHub would skip. Surface the warning in report output and
add a dedicated fail flag so CI can enforce the parity check directly.

Made-with: Cursor
diff --git a/README.md b/README.md
@@ -86,6 +86,7 @@ In interactive mode, `--no-report` implies `--list-unowned` so output still stay
 | `--no-report` | Skip HTML report generation (implies `--list-unowned`) |
 | `--list-unowned` | Print unowned file paths to stdout |
 | `--fail-on-unowned` | Exit non-zero when one or more files are unowned |
+| `--fail-on-oversized-codeowners` | Exit non-zero when the active `CODEOWNERS` file exceeds GitHub's 3 MB limit |
 | `--fail-on-missing-paths` | Exit non-zero when one or more CODEOWNERS paths match no repository files |
 | `--validate-github-owners` | Validate `@username` and `@org/team` owners against GitHub and use only validated owners for coverage |
 | `--fail-on-invalid-owners` | Exit non-zero when one or more CODEOWNERS rules contain invalid GitHub owners |
diff --git a/lib/audit.js b/lib/audit.js
@@ -16,6 +16,7 @@ import { validateGithubOwners } from './github-owner-validation.js'
 
 const SUPPORTED_CODEOWNERS_PATHS = ['.github/CODEOWNERS', 'CODEOWNERS', 'docs/CODEOWNERS']
 const SUPPORTED_CODEOWNERS_PATHS_LABEL = SUPPORTED_CODEOWNERS_PATHS.join(', ')
+const GITHUB_CODEOWNERS_MAX_BYTES = 3 * 1024 * 1024
 
 /**
  * Run a complete CODEOWNERS audit on a repository.
@@ -57,6 +58,7 @@ async function audit (repoRoot, options) {
 
   const codeownersDescriptor = loadCodeownersDescriptor(repoRoot, codeownersPath)
   const discoveryWarnings = collectCodeownersDiscoveryWarnings(discoveredCodeownersPaths, codeownersPath)
+  const oversizedCodeownersWarnings = collectOversizedCodeownersWarnings(codeownersDescriptor)
   /** @type {import('./types.js').InvalidOwnerWarning[]} */
   let invalidOwnerWarnings = []
   /** @type {string[]} */
@@ -107,6 +109,8 @@ async function audit (repoRoot, options) {
   report.codeownersValidationMeta = {
     discoveryWarnings,
     discoveryWarningCount: discoveryWarnings.length,
+    oversizedCodeownersWarnings,
+    oversizedCodeownersWarningCount: oversizedCodeownersWarnings.length,
     missingPathWarnings,
     missingPathWarningCount: missingPathWarnings.length,
     invalidOwnerWarnings,
@@ -265,15 +269,38 @@ function buildMissingSupportedCodeownersError (discoveredCodeownersPaths) {
  * @returns {import('./types.js').CodeownersDescriptor}
  */
 function loadCodeownersDescriptor (repoRoot, codeownersPath) {
-  const fileContent = readFileSync(path.join(repoRoot, codeownersPath), 'utf8')
-  const rules = parseCodeowners(fileContent)
+  const fileBuffer = readFileSync(path.join(repoRoot, codeownersPath))
+  const sizeBytes = fileBuffer.byteLength
+  const oversized = sizeBytes > GITHUB_CODEOWNERS_MAX_BYTES
+  const rules = oversized ? [] : parseCodeowners(fileBuffer.toString('utf8'))
 
   return {
     path: codeownersPath,
     rules,
+    sizeBytes,
+    sizeLimitBytes: GITHUB_CODEOWNERS_MAX_BYTES,
+    oversized,
   }
 }
 
+/**
+ * Build warnings for an active CODEOWNERS file that GitHub ignores due to size.
+ * @param {import('./types.js').CodeownersDescriptor} codeownersDescriptor
+ * @returns {import('./types.js').OversizedCodeownersWarning[]}
+ */
+function collectOversizedCodeownersWarnings (codeownersDescriptor) {
+  if (!codeownersDescriptor.oversized) {
+    return []
+  }
+
+  return [{
+    codeownersPath: codeownersDescriptor.path,
+    sizeBytes: codeownersDescriptor.sizeBytes,
+    sizeLimitBytes: codeownersDescriptor.sizeLimitBytes,
+    message: `${codeownersDescriptor.path} is ignored because it is ${codeownersDescriptor.sizeBytes} bytes and exceeds GitHub's 3 MB CODEOWNERS limit of ${codeownersDescriptor.sizeLimitBytes} bytes.`,
+  }]
+}
+
 /**
  * Build missing-path warnings for CODEOWNERS rules that match no repository files.
  * @param {import('./types.js').CodeownersDescriptor} codeownersDescriptor
@@ -560,6 +587,7 @@ export {
   collectCodeownersDiscoveryWarnings,
   collectCodeownersPatternDiffChangeSet,
   collectCodeownersPatternHistory,
+  collectOversizedCodeownersWarnings,
   collectMissingDirectorySlashWarnings,
   collectMissingCodeownersPathWarnings,
   collectRepoDirectories,
diff --git a/lib/cli-args.js b/lib/cli-args.js
@@ -19,6 +19,7 @@ const OPTIONS_CONFIG = {
   'no-report': { type: 'boolean', default: false },
   'list-unowned': { type: 'boolean', default: false },
   'fail-on-unowned': { type: 'boolean', default: false },
+  'fail-on-oversized-codeowners': { type: 'boolean', default: false },
   'fail-on-missing-paths': { type: 'boolean', default: false },
   'validate-github-owners': { type: 'boolean', default: false },
   'fail-on-invalid-owners': { type: 'boolean', default: false },
@@ -52,6 +53,7 @@ const OPTIONS_CONFIG = {
  *   noReport: boolean,
  *   listUnowned: boolean,
  *   failOnUnowned: boolean,
+ *   failOnOversizedCodeowners: boolean,
  *   failOnMissingPaths: boolean,
  *   validateGithubOwners: boolean,
  *   failOnInvalidOwners: boolean,
@@ -206,6 +208,7 @@ export function parseArgs (args) {
     noReport: /** @type {boolean} */ (values['no-report']),
     listUnowned: /** @type {boolean} */ (values['list-unowned']),
     failOnUnowned: /** @type {boolean} */ (values['fail-on-unowned']),
+    failOnOversizedCodeowners: /** @type {boolean} */ (values['fail-on-oversized-codeowners']),
     failOnMissingPaths: /** @type {boolean} */ (values['fail-on-missing-paths']),
     validateGithubOwners: /** @type {boolean} */ (values['validate-github-owners']),
     failOnInvalidOwners: /** @type {boolean} */ (values['fail-on-invalid-owners']),
@@ -256,6 +259,7 @@ function helpResult (args) {
     noReport: false,
     listUnowned: false,
     failOnUnowned: false,
+    failOnOversizedCodeowners: false,
     failOnMissingPaths: false,
     validateGithubOwners: false,
     failOnInvalidOwners: false,
@@ -292,6 +296,7 @@ export function printUsage () {
     ['--no-report', 'Skip HTML report generation (implies --list-unowned)'],
     ['--list-unowned', 'Print unowned file paths to stdout'],
     ['--fail-on-unowned', 'Exit non-zero when one or more files are unowned'],
+    ['--fail-on-oversized-codeowners', 'Exit non-zero when the active CODEOWNERS file exceeds GitHub\'s 3 MB limit'],
     ['--fail-on-missing-paths', 'Exit non-zero when CODEOWNERS paths match no files'],
     ['--validate-github-owners', 'Validate @username and @org/team owners against GitHub and use that for coverage'],
     ['--fail-on-invalid-owners', 'Exit non-zero when CODEOWNERS rules contain invalid GitHub owners'],
diff --git a/lib/cli-output.js b/lib/cli-output.js
@@ -74,6 +74,23 @@ export function formatMissingPathWarningForCli (warning, useColor) {
   return bullet + warningPath + ownerLabel + ownerText
 }
 
+/**
+ * Format an oversized CODEOWNERS warning for CLI output.
+ * @param {import('./types.js').OversizedCodeownersWarning} warning
+ * @param {boolean} useColor
+ * @returns {string}
+ */
+export function formatOversizedCodeownersWarningForCli (warning, useColor) {
+  const bullet = colorizeCliText('- ', [ANSI_DIM], useColor)
+  const warningPath = colorizeCliText(warning.codeownersPath, [ANSI_YELLOW], useColor)
+  const detail = colorizeCliText(
+    ` is ignored because it is ${formatByteCount(warning.sizeBytes)} and exceeds GitHub's 3 MB limit (${formatByteCount(warning.sizeLimitBytes)}).`,
+    [ANSI_DIM],
+    useColor
+  )
+  return bullet + warningPath + detail
+}
+
 /**
  * Format an invalid GitHub owner warning for CLI output.
  * @param {import('./types.js').InvalidOwnerWarning} warning
@@ -138,6 +155,15 @@ export function formatCodeownersOwnersList (owners) {
   return owners.join(', ')
 }
 
+/**
+ * Format a raw byte count for human-readable CLI output.
+ * @param {number} value
+ * @returns {string}
+ */
+export function formatByteCount (value) {
+  return `${new Intl.NumberFormat('en-US').format(value)} bytes`
+}
+
 /**
  * Format invalid owner reasons for human-readable output.
  * @param {import('./types.js').InvalidOwnerEntry[]|undefined} invalidOwners
@@ -158,6 +184,7 @@ export function formatInvalidOwnerReasons (invalidOwners) {
  *   unownedFiles: string[],
  *   codeownersValidationMeta?: {
  *     discoveryWarnings?: import('./types.js').DiscoveryWarning[],
+ *     oversizedCodeownersWarnings?: import('./types.js').OversizedCodeownersWarning[],
  *     missingPathWarnings?: import('./types.js').MissingPathWarning[],
  *     invalidOwnerWarnings?: import('./types.js').InvalidOwnerWarning[],
  *     ownerValidationWarnings?: string[],
@@ -169,6 +196,7 @@ export function formatInvalidOwnerReasons (invalidOwners) {
  *   noReport: boolean,
  *   listUnowned: boolean,
  *   failOnUnowned: boolean,
+ *   failOnOversizedCodeowners: boolean,
  *   failOnMissingPaths: boolean,
  *   failOnInvalidOwners: boolean,
  *   failOnMissingDirectorySlashes: boolean,
@@ -190,6 +218,10 @@ export function outputUnownedReportResults (report, options) {
     ? report.codeownersValidationMeta.discoveryWarnings
     : []
   const locationWarningCount = discoveryWarnings.length
+  const oversizedCodeownersWarnings = Array.isArray(report.codeownersValidationMeta?.oversizedCodeownersWarnings)
+    ? report.codeownersValidationMeta.oversizedCodeownersWarnings
+    : []
+  const oversizedCodeownersWarningCount = oversizedCodeownersWarnings.length
   const missingPathWarnings = Array.isArray(report.codeownersValidationMeta?.missingPathWarnings)
     ? report.codeownersValidationMeta.missingPathWarnings
     : []
@@ -238,6 +270,20 @@ export function outputUnownedReportResults (report, options) {
     console.error('')
   }
 
+  if (options.noReport && oversizedCodeownersWarningCount > 0) {
+    console.error(
+      colorizeCliText(
+        `Oversized CODEOWNERS files (${oversizedCodeownersWarningCount}):`,
+        [ANSI_BOLD, ANSI_YELLOW],
+        colorStderr
+      )
+    )
+    for (const warning of oversizedCodeownersWarnings) {
+      console.error('%s', formatOversizedCodeownersWarningForCli(warning, colorStderr))
+    }
+    console.error('')
+  }
+
   if (options.noReport && invalidOwnerWarningCount > 0) {
     console.error(
       colorizeCliText(
@@ -318,6 +364,7 @@ export function outputUnownedReportResults (report, options) {
           : []),
         `${colorizeCliText('analyzed files:', [ANSI_DIM], colorStdout)} ${colorizeCliText(String(report.totals.files), [ANSI_BOLD], colorStdout)}`,
         `${colorizeCliText('unknown files:', [ANSI_DIM], colorStdout)} ${colorizeCliText(String(report.totals.unowned), report.totals.unowned > 0 ? [ANSI_BOLD, ANSI_RED] : [ANSI_BOLD, ANSI_GREEN], colorStdout)}`,
+        `${colorizeCliText('oversized CODEOWNERS warnings:', [ANSI_DIM], colorStdout)} ${colorizeCliText(String(oversizedCodeownersWarningCount), oversizedCodeownersWarningCount > 0 ? [ANSI_BOLD, ANSI_YELLOW] : [ANSI_BOLD, ANSI_GREEN], colorStdout)}`,
         `${colorizeCliText('missing path warnings:', [ANSI_DIM], colorStdout)} ${colorizeCliText(String(missingPathWarningCount), missingPathWarningCount > 0 ? [ANSI_BOLD, ANSI_YELLOW] : [ANSI_BOLD, ANSI_GREEN], colorStdout)}`,
         `${colorizeCliText('invalid owner warnings:', [ANSI_DIM], colorStdout)} ${colorizeCliText(String(invalidOwnerWarningCount), invalidOwnerWarningCount > 0 ? [ANSI_BOLD, ANSI_YELLOW] : [ANSI_BOLD, ANSI_GREEN], colorStdout)}`,
         `${colorizeCliText('owner validation warnings:', [ANSI_DIM], colorStdout)} ${colorizeCliText(String(ownerValidationWarningCount), ownerValidationWarningCount > 0 ? [ANSI_BOLD, ANSI_YELLOW] : [ANSI_BOLD, ANSI_GREEN], colorStdout)}`,
@@ -338,6 +385,10 @@ export function outputUnownedReportResults (report, options) {
     process.exitCode = EXIT_CODE_UNCOVERED
   }
 
+  if (options.failOnOversizedCodeowners && oversizedCodeownersWarningCount > 0) {
+    process.exitCode = EXIT_CODE_UNCOVERED
+  }
+
   if (options.failOnMissingPaths && missingPathWarningCount > 0) {
     process.exitCode = EXIT_CODE_UNCOVERED
   }
diff --git a/lib/report-builder.js b/lib/report-builder.js
@@ -114,6 +114,8 @@ export function buildReport (repoRoot, files, codeownersDescriptor, options, pro
     codeownersValidationMeta: {
       discoveryWarnings: [],
       discoveryWarningCount: 0,
+      oversizedCodeownersWarnings: [],
+      oversizedCodeownersWarningCount: 0,
       missingPathWarnings: [],
       missingPathWarningCount: 0,
       invalidOwnerWarnings: [],
diff --git a/lib/report.template.html b/lib/report.template.html
@@ -508,6 +508,11 @@ <h2>Active CODEOWNERS File</h2>
         </thead>
         <tbody id="codeowners-table-body"></tbody>
       </table>
+      <div id="oversized-codeowners-warnings" class="validation-warnings" hidden>
+        <h3 id="oversized-codeowners-warnings-heading">Oversized CODEOWNERS Files</h3>
+        <p class="warning-text" style="margin: 4px 0 0; font-size: 13px;">GitHub ignores `CODEOWNERS` files larger than 3 MB, so coverage from these files should not be trusted.</p>
+        <ul id="oversized-codeowners-warnings-list"></ul>
+      </div>
       <div id="missing-path-warnings" class="validation-warnings" hidden>
         <h3 id="missing-path-warnings-heading">Patterns With No Matching Repository Paths</h3>
         <ul id="missing-path-warnings-list"></ul>
@@ -560,6 +565,8 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
       const codeownersValidationMeta = report.codeownersValidationMeta || {
         discoveryWarnings: [],
         discoveryWarningCount: 0,
+        oversizedCodeownersWarnings: [],
+        oversizedCodeownersWarningCount: 0,
         missingPathWarnings: [],
         missingPathWarningCount: 0,
         invalidOwnerWarnings: [],
@@ -620,6 +627,7 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
       document.getElementById('coverage-unowned').style.width = clamp(100 - report.totals.coverage) + '%'
 
       renderCodeownersFiles(report.codeownersFiles)
+      renderOversizedCodeownersWarnings(codeownersValidationMeta)
       renderMissingPathWarnings(codeownersValidationMeta)
       renderInvalidOwnerWarnings(codeownersValidationMeta)
       renderOwnerValidationWarnings(codeownersValidationMeta)
@@ -657,6 +665,42 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
         }
       }
 
+      function renderOversizedCodeownersWarnings (validationMeta) {
+        const container = document.getElementById('oversized-codeowners-warnings')
+        const heading = document.getElementById('oversized-codeowners-warnings-heading')
+        const list = document.getElementById('oversized-codeowners-warnings-list')
+        const warningRows = Array.isArray(validationMeta && validationMeta.oversizedCodeownersWarnings)
+          ? validationMeta.oversizedCodeownersWarnings
+          : []
+
+        list.innerHTML = ''
+        if (warningRows.length === 0) {
+          container.hidden = true
+          return
+        }
+
+        const warningCount = Number(validationMeta && validationMeta.oversizedCodeownersWarningCount) || warningRows.length
+        heading.textContent = 'Oversized CODEOWNERS Files (' + fmt.format(warningCount) + ')'
+
+        for (const warning of warningRows) {
+          const item = document.createElement('li')
+          const pathSpan = document.createElement('span')
+          pathSpan.className = 'warning-path'
+          pathSpan.textContent = warning.codeownersPath
+          item.appendChild(pathSpan)
+
+          const textSpan = document.createElement('span')
+          textSpan.className = 'warning-text'
+          textSpan.textContent = ' is ignored because it is ' + formatByteCount(warning.sizeBytes) +
+            ' and exceeds GitHub\'s 3 MB limit (' + formatByteCount(warning.sizeLimitBytes) + ').'
+          item.appendChild(textSpan)
+
+          list.appendChild(item)
+        }
+
+        container.hidden = false
+      }
+
       function renderMissingPathWarnings (validationMeta) {
         const container = document.getElementById('missing-path-warnings')
         const heading = document.getElementById('missing-path-warnings-heading')
@@ -911,6 +955,10 @@ <h3 id="unprotected-directory-warnings-heading">Directories With Fragile Coverag
         return 'just now'
       }
 
+      function formatByteCount (value) {
+        return fmt.format(value) + ' bytes'
+      }
+
       function renderCodeownersDiscoveryWarnings (validationMeta) {
         const container = document.getElementById('codeowners-discovery-warnings')
         const heading = document.getElementById('codeowners-discovery-warnings-heading')
diff --git a/lib/types.js b/lib/types.js
@@ -21,7 +21,10 @@
  * A CODEOWNERS file descriptor with its path and parsed rules.
  * @typedef {{
  *   path: string,
- *   rules: CodeownersRule[]
+ *   rules: CodeownersRule[],
+ *   sizeBytes: number,
+ *   sizeLimitBytes: number,
+ *   oversized: boolean
  * }} CodeownersDescriptor
  */
 
@@ -64,6 +67,17 @@
  * }} MissingDirectorySlashWarning
  */
 
+/**
+ * Warning about an active CODEOWNERS file that GitHub ignores because it
+ * exceeds the documented 3 MB size limit.
+ * @typedef {{
+ *   codeownersPath: string,
+ *   sizeBytes: number,
+ *   sizeLimitBytes: number,
+ *   message: string
+ * }} OversizedCodeownersWarning
+ */
+
 /**
  * A single invalid GitHub owner entry attached to a CODEOWNERS rule.
  * @typedef {{
@@ -99,6 +113,8 @@
  * @typedef {{
  *   discoveryWarnings: DiscoveryWarning[],
  *   discoveryWarningCount: number,
+ *   oversizedCodeownersWarnings: OversizedCodeownersWarning[],
+ *   oversizedCodeownersWarningCount: number,
  *   missingPathWarnings: MissingPathWarning[],
  *   missingPathWarningCount: number,
  *   invalidOwnerWarnings: InvalidOwnerWarning[],
diff --git a/test/cli-args.test.js b/test/cli-args.test.js
@@ -17,6 +17,7 @@ test('parseArgs: returns defaults with no arguments', () => {
   assert.equal(result.noReport, false)
   assert.equal(result.listUnowned, false)
   assert.equal(result.failOnUnowned, false)
+  assert.equal(result.failOnOversizedCodeowners, false)
   assert.equal(result.failOnMissingPaths, false)
   assert.equal(result.validateGithubOwners, false)
   assert.equal(result.failOnInvalidOwners, false)
@@ -64,6 +65,10 @@ test('parseArgs: --fail-on-unowned', () => {
   assert.equal(parseArgs(['--fail-on-unowned']).failOnUnowned, true)
 })
 
+test('parseArgs: --fail-on-oversized-codeowners', () => {
+  assert.equal(parseArgs(['--fail-on-oversized-codeowners']).failOnOversizedCodeowners, true)
+})
+
 test('parseArgs: --fail-on-missing-paths', () => {
   assert.equal(parseArgs(['--fail-on-missing-paths']).failOnMissingPaths, true)
 })
diff --git a/test/cli.test.js b/test/cli.test.js
